Many of the examples of “Choose…” commands in this Cookbook are of the nature of choosing “Yes” or “No” values or other such terse values.
But another important branch of Document Assembly is the inclusion or exclusion of paragraphs or clauses depending on some or other set of criteria. Sometimes these criteria are inferred from the kind of terse “Yes” or “No” choices referred to above. But sometimes we need the user to choose the clause explicitly.
Here is an example of the inclusion of a clause referring to collateral being provided or not:
«ChooseFromRDBList(CollProv,Yes,No)»«Caption(CollProv,Collateral to be provided)»
«If(CollProv = "Yes")»Collateral is to be provided by the signatory.
«Else()»No collateral is required.
«End()»
This is a reasonable way to achieve the desired text in the document.
Another way would be:
«ChooseFromRDBList(CollProv,Collateral is to be provided by the signatory,No collateral is required)»«Caption(CollProv,Collateral to be provided)»
«CollProv»
Sometimes the number of different clauses from which a choice is to be made is such that the only way to indicate the content of the clause in the data capture dialog (so that the user can make a correctly informed choice) is to include the entire text of each clause in the RDB list, as in the example below:
The parcel is to be delivered by courier because:
«ChooseFromRDBList(Clause,
I do not trust the postal service to protect it from damage,
In this case the courier is the cheapest option,
Although the postal service is trustworthy and the courier is more expensive!, the courier reception depot is closer than the post office)»
«Clause».
This example is sufficient when the text of the data element is to be inserted directly into the document. But suppose the result of the choice is to be used again in one or more If commands. If the entire text of the above choice is to be used in an If then it would render the command difficult to read and also be liable to mis-typing (even using copy-and-paste). In this case, the following would place a short-hand code for the chosen clause into the data element ClauseCode, and yet still display the verbose text to the right of the radio buttons (note the use of the ~~ delimiter):
The parcel is to be delivered by courier because:
«ChooseFromRDBList(ClauseCode,
NoTrust~~I do not trust the postal service,
Cheap~~The courier is the cheapest option,
Close~~The courier reception depot is closer than the post office)»
«If(ClauseCode = "NoTrust")»
I do not trust the postal service to protect it from damage.
«End()»
«If(ClauseCode = "Cheap")»
In this case the courier is the cheapest option.
«End()»
«If(ClauseCode = "Close")»
Although the postal service is trustworthy and the courier is more expensive, the courier reception depot is closer than the post office.
«End()»
Note the following
1. The character ! before the comma in the third choice is an escape character, and is used to tell XpressDox that the comma following it is to be used as part of the text of the choice, and not to indicate the boundary between two choices in the list. The ! will not be included in the value chosen for the data element.
2. In the second RDB list, the choices appear each on a separate line. This can be coded into a Word document using the “soft line space” (<Shift Enter>). This renders the RDB list more readable, and the soft line spaces will not appear in the merged document.
Another example would be a kind of menu situation, where the user can choose more than one of a list of options. In this case an RDB List is not the answer, as by its nature an RDB list permits only one choice to be made. Here is an example of a multiple choice, using ChooseUsingCheckBox. Note how the ~~ delimiter causes the text to the right of it to be displayed to the right of the check box (as against the ? which would otherwise appear)
S/he is a vegetarian because:
«ChooseUsingCheckBox(Veg1,~~S/he doesn!'t like animals being killed)»
«ChooseUsingCheckBox(Veg2,~~The amount of air pollution caused by the farming of animals is too high)»
«ChooseUsingCheckBox(Veg3,~~Deforestation in order to make way for the cattle ranches is causing global warming)»
1.«ShowIfHasValue(Veg1)»
2.«ShowIfHasValue(Veg2)»
3.«ShowIfHasValue(Veg3)»
Note:
1. The ! before the quote in the first check box is an “escape” character – it tells XpressDox that the quote is to be used in the value of the option, and not as a string delimiter in the command. The ! itself won’t appear in the data element value.
2. Note that if Word paragraph numbering is used to number the numbered paragraphs above, then the correct paragraph numbering will appear in the merged document.
As with the RDB lists, it may be required that the data elements chosen via the check boxes have not the actual text of the paragraph, but a short hand code assigned to them. The following would put the value “Y” into the data elements Veg1, Veg2 and Veg3 if the user checks the check box, and “N” if not.
«ChooseUsingCheckBox(Veg1,Y~~S/he doesn!'t like animals being killed,N)»
«ChooseUsingCheckBox(Veg2,Y~~The amount of air pollution caused by the farming of animals is too high,N)»
«ChooseUsingCheckBox(Veg3,Y~~Deforestation in order to make way for the cattle ranches is causing global warming,N)»
Other mechanisms for selecting clauses in the data capture dialog are discussed in the article Conditional inclusion of paragraphs and clauses.
