|
<<*AskValue*>> Prompt |
|
|
|
|
<<*AskValue*>> Prompt |
|
|
<<*AskValue*>> Prompt
|
<<*AskValue*>> Prompt |
|
|
|
|
<<*AskValue*>> Prompt |
|
|
<<*AskOptional*>> and <<*AskOptions*>> require and return a 'fixed' result based on, for AskOptions, the position of the 'choice', and, for AskOptional, whether the prompt was answered 'yes' or 'no.'
Sometimes this 'positional' approach will not work. Sometimes the actual value (not the position) is needed to control the result. (The positional approach is a favored one. It is simply easier to set up related choices based on their relative positions in a list. It works in the majority of situations. But when it won't, use <<*AskValue*>>.)
Example:
Grades: An 'A' is a range from 90 to 100, a 'B' ranges from 80-89, etc. A score that deserves Honor Roll recognition is any score of 85 and above.
Let's assume a test score of 88. How should one convert that score into a letter grade. Based on the test results of a recent exam, how should one notify the student of the her placement on the Honor Roll.
The "AskOptions" method. Consider the following setup: <<*AskOptions*!Grade!0-59/60-69/70-79/80-89/90-100*>> The above requires the end user to manually click the 4th choice that is presented ('80-89'). Further in the document, you might have Your raw score on the most recent exam was <<!Grade!>>. This translates to a letter grade of<<*Options*!Grade!*F/D/C/B/A>> Still further down you could notify deserving students of the Honor Roll achievement with this line in the letter: <<*Options*!Grade!*///Congratulations! You made the Honor Roll!/Congratulations! You made the Honor Roll.>> But note: The requirement for Honor Roll was 85, not 80, so the selection of the Honor Roll designation cannot accurately be done with this method. (You can copy and paste the above sample into your document and 'process' it.) |
With the AskValue prompt, Pathagoras 'Asks' for a specific value of 'something' (grade, quantity, score, etc.) at the top of the document and then analyzes the response per a variety of 'ranges' provided elsewhere in the document. As with other <<*Ask*>> prompts, Pathagoras requires you to provide a !groupname! to associate it with other elements in the document.
The AskValue method. Example #1 (You can copy and paste the above sample into your document and 'process' it.) |
When the user assigns a value in response to the <<*AskValue*>> prompt, Pathagoras remembers it value and applies what it knows in one of two situations:
| 1. | If an options block containing only the !groupname! (written like this: <<!groupname!>>) is located within the document, it will be directly replaced with the designated value. This is similar to replacing a [variable] using the Instant Database. However, the replacements are done during the processing phase of document assembly. The value provided will not be stored with the other variables in the Instant Database. (They can be saved with the Ask responses.) This is shown in line b. above. |
| 2. | When you have provided a 'full' <<*Options* . . .>> block that contains value 'ranges' within the administrative section of the block, Pathagoras will analyze the answer using those ranges and return the appropriate value. This is shown in lines b. and c. above.  Note (and this illustrates the very important distinction between AskValue and AskOptions): The parameters need not be the same (even the number of options need not be the same -- 5 options are provided in line b. above, just 2 in line c.) |
The AskValue method. Example #2 (You can copy and paste the above sample into your document and 'process' it.) |
The above is example provides a different situation where AskValue might be used. It also illustrates that non-finite ranges can be used. Note the '>75' in both lines. You can use '>' and '<' and '<=' and '>=' (The order of the signs does not matter. So you could have '=>' as well.)
In the area of direct value replacement, you have to decide whether the value is best provided using the Instant Database or via the AskValue prompt.
When AskValue is better than Variables:
| • | With AskValue, the presumption is that the value will be analyzed in multiple locations in the document with varying sets of ranges. (This is not a requirement, but is the reason why the routine was written. You can use AskValue to replace AskOptions, but the setup for AskOptions is quite a bit easier. |
| • | Use AskValue where there is no pressing need to save the value as part of an Instant Database record. You want to save the customers name, address, etc., so that you can use that information in letter after letter, but you may not need to record (at least for document assembly purposes) the specific grade or the amount of the purchase that leads to the generation of the document. (That data presumably is recorded elsewhere.) |
Note the following structural requirements:
The <<*AskValue*>> prompt, like all <<*Ask . . .>> prompts, closes with a "*".
The comparison must be between a minimum of two sets of values. Those values can be a finite range (e.g., 0-75) or an non-finite range (e.g., >75; >=75 will also work).
Each 'range' option must have a corresponding 'return' option. So, in this example:
<<*Options*!Grade!0-89/90-100*Sorry, you did not make the honor roll/Congratulations! You have made the honor roll.>> |
there are two ranges: '0-89' and '90-100'. The 'return' text is whatever appears after the "*" that closes the administrative section of the block.
Let's provide one more example. There is no sense in 'rubbing in' the fact that the 75 grade student did not make the honor roll. Perhaps it is best just to say nothing.
<<*Options*!Grade!0-89/90-100*/Congratulations! You have made the honor roll.>> |
In the above example, "/Congratulations! You have made the honor roll" is now the return text. The slash, with no text preceding it, means it is a 'blank' choice. It returns 'nothing'.
When a [Variable] is better:
| • | When the result is a defined value needed only for a direct replacement and need not be analyzed for use elsewhere in the document and it is imperative that you save the value in the client/customer's Instant Database information. |