Embedded Files
Description
5g functions must provide inline help so users we have never met will know how to use our function properly.
Learning Objectives
At the end of this course, learners will know:
Why it is important to document components
How to document components for component consumers
Prerequisites
Understanding of the following Excel functions:
Discussion
5g is about creating functions for other people to use. When others use our functions for the first time, they may have little to no idea what the function does, what its arguments are, and what is appropriate for each argument. We must instruct them. Inline help readily provides that instruction and is what users are accustom to from Excel's functions.
Excel's Online Help
One way to get help with a function is shown at right. As we enter the function in the formula bar, we can click the fx icon to launch the function's prompt dialog. In the prompt is a hyperlink at the bottom left corner. Users can click that to launch a browser and open the webpage dedicated to that function.
Unfortunately, Microsoft has not extended this hypertext pop-up facility to LAMBDAs. We will have to find a way to mimic this feature.
Excel's Inline Help
Another way to get help with a function is in the function's argument tooltip. Shown at right is Excel Online's inline help which is what I believe Microsoft would consider their state of the art for inline help. As soon as we type the open parenthesis the function argument tooltip appears. It contains the function's name and its arguments. It then provides a brief description. It then provides a simple example followed by each argument and its description. In the bottom left corner is a hyperlink to go onto online help.
It would be great if Microsoft made this available to LAMBDAs as well but they haven't (as of this writing).
Mimicking Excel
We can mimic those features to some degree.
At right is a sample inline help. This displays when users omit any required argument. Excel does not allow us to enter functions without required arguments. To get around Excel, we must declare all arguments as optional by surrounding them with square brackets. Excel will then pass control to our function and our function can determine what is required and what is not, and if any required argument is missing, display inline help.
Constructing Inline Help
Below is the source to the inline help.
The inline help text is one long text string stitched together with the & (concatenate) operator. It is arranged in the formula's source to be easily edited and provide an approximation of what it will look like when displayed. When displayed to the user, our function will place the text in two columns and several rows. To separate the text into columns and rows we use the TEXTSPLIT() function.
TEXTSPLIT() converts the single text string into an array. Its arguments are a text string, a column delimiter, and a row delimiter. For the column delimiter we recommend using → (ALT-26). For the row delimiter we recommend using ¶ (ALT-0182).
NOTE! ALT-0182 means, with the ALT key held down enter the numbers on your keyboard's numeric keypad.
We recommend these characters because they are unlikely to be used in the help text. Additionally, we can use the TRIM() function to remove the spaces between the first and second columns when displayed. Those spaces were added to make the source easier to read.
Inline help should include:
The function's name and its arguments
A short description of the component's function
If available, the URL to a webpage devoted to explaining the function should be added.
NOTE! A space should be added between the end of the URL and the paragraph mark for the source to be clickable.The version date which is when this was last changed
A list of all arguments/parameters. Each argument should include
Whether the argument is required or optional
And if optional, what the default is.
If appropriate, the data type of the argument such as Date, Number, or Text
And if appropriate if the argument must be a: single value, a single row, a single column, or a matrix array.
One or more examples of how it is used. If practical, show a few examples with results.
Handling Help Request
Users will receive inline help if they omit any required arguments. To determine if any of the required arguments have been omitted, we place the code at right below the inline help text. The code uses the ISOMOTTED() function for each required argument. This return TRUE if omitted, and FALSE if not. We combine the results into an array and then OR() the array. The result of the OR() function will be TRUE if any of the required arguments have been omitted. The result is placed in LET() step Help?.
At the very bottom of our LET() function, we include the code at right. When TRUE and FALSE are used in an arithmetic operation, Excel converts TRUE to 1 and FALSE to 0. Thus, in the code at right, when Help? = TRUE, it will be converted to 1. When it is FALSE, it will be converted to 0. The CHOOSE() function with then select the Result LET() step's value when Help? = FALSE and the Help LET() step's value (at top) when Help? = TRUE.
Lab
Create the help text for an imaginary Timeline() function. Timeline() has four arguments: StartDate (Required), NumberOfPeriods (Optional), and PeriodInterval (Optional). The default for NumberOfPeriods is 12. The default for PeriodInterval is "M" (months). Pretend you have also created a webpage dedicated to explaining this function (create your own fictitious webpage address).
Summary
Summary
Microsoft knows that inline help is crucial to helping people understand how to use Excel's functions. They have devoted significant effort to documenting every Excel function. At this time, we cannot do exactly what Microsoft does, but we can provide alternatives that mimic their documentation strategy. Adding the help text is relatively simple. In a later class we will see how to display it when the circumstances call for that.
Navigation
Page updated
Google Sites
Report abuse