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. Inline help should include the function's syntax, a brief description, webpage address (if any), version, and argument descriptions.
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.
TRIM() and TEXTSPLIT()
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. Alternatively, we can use Excel's Insert > Symbol (see right) into Excel's grid then copy/paste the symbol into source.
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
NOTE! I use Unicode Character code 2003 (see right) to insert space that TRIM() won't remove. In the source, it displays as an outlined block, as shown above.
NOTE! I use tab (spaces) to format the text so it looks in source very much like how it will look in Excel's grid.
The inline help text should include the following
Function Syntax - In the help text's first line is the label "FUNCTION:" and your function's syntax.
NOTE! Even though we declared all arguments as optional (with square brackets) to Excel, we need to let the user know which arguments are required and which are optional here.
Description - One or two sentences describing what this function does.
Webpage - We webpage's URL (if it exists) dedicated to this function
Version - You initials and the date of the most recent change
Parameters - The function's argument along with a breif description of each argument
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