Robust Options and Optional

Top  Previous  Next

<<*Options/Optional*. . .>> text blocks are specially marked sections of text that allow the end user to choose whether all or portions of the text block will remain in the final document.

    Two types of optional text blocks are used in Pathagoras. They are both created with, and denoted by, plain-text boundary markers “<<” and “>>” placed around the subject text. (Pathagoras provides a 'simplified' version of both of these blocks. They are discussed starting at this link.)

1.“Optional” text: This is pure ‘optional' (take it or delete it) text.’ It is sometimes called 'conditional' text. At document assembly time, the program will highlight the text, pause and ask “Do you want to keep this text?”. The user need only respond “Yes” or “No” to tell Pathagoras whether the text block should be retained in the final document.

<<*Optional*The widgets you have ordered are not currently in stock. We will ship them as soon as possible. If we have not shipped within 5 days of this date, you will have the option to cancel the order.>>

2.“Options” text: This block ‘type’ allows the user to select among several choices. Each choice is separated from the others by a simple, plain text slash (“/”). At document assembly time, the choice are presented to the user on a selection screen. The user selects one or more of the displayed choices.

Beginning with version 2013.6, you can use rows in a table to separate the various choices. See this page for examples.

  <<*Options*Per your request, the widgets will be shipped by Federal Express. We will bill you for the extra cost of shipping./Per your request, we will send the widgets by standard ground transport. This may take 3 to 5 additional days./As per your request, we will hold the widgets for pickup by your courier./The widgets you have ordered are not currently in stock. We will ship them as soon as possible. If we have not shipped within 5 days of this date, you will have the option to cancel the order.>>

   When Pathagoras encounters the optional text block (#1 above), it will highlight the text in the document and ask if you want to keep it (Figure 1).

Click to enlarge.

Figure 1 Optional Text dialog.
If  you select <Yes>, the boundary markers are removed
and the text remains in the document.
If you choose <No>, the entire text block is deleted from the document.

   When Pathagoras encounters the options block (#2 above), it will parse out the individual choices and display them onto buttons on a selection screen.  (If the text is too long to fit, only the first 200 or so characters of the particular option will display.) Checkboxes are shown at the left of each choice so that you can choose more than one option, if desired. If you want just a single choice, click on the 'bar' containing that choice.

Click to enlarge.

Figure 2 Options block dialog.
Note that the actual option text is provided (subject to space constraints.)

informationNotes:

Creating an <<*Options*>> or <<*Optional*>> text block really is no more difficult than what is described above. It is all plain text construction. No fields, no codes. Just remember that the 'administrative' section of an Options or Optional text block must end with an asterisk.
Instead of processing <<*Options*>> or <<*Optional*>> text blocks 'one at a time' (as the above examples and screen shots suggest) you can enable Document Logic, creating an Interview Screen and assigning values for all blocks from a single input screen.
We encourage you to liberally use <<*Options*>> and <<*Optional*>> text blocks. But it is possible to 'over-populate' a document with Optional text. By creating such a document, you will end up with a long, complex looking document that may actually 'scare' the end-user and impede the document assembly process.

   If you have inserted dozens of <<*Optional*>> text blocks inside your document, we would suggest that you consider creating individual 'selectable' clauses from the same text. Then, assemble the document from those separate clauses via the Clause Selection Screen (or insert them via a DropDown List). You will likely find this process more efficient and significantly faster. See this discussion: Optional Text vs. Individual Clauses

You can have only nine *Options* in an <<*Options*>> block. There are practical reasons for this, not the least of which is the amount of screen 'real estate' that is needed to display the various options in the Dialog (Figure 2). There are two 'work arounds' to this limit.
1.The first is to break the options into two or sets of (up to) nine choices, and create a 'super' options block encompassing the (nested) others. The 'super' level <<*Options*>> will be presented first. Selecting a choice from that level brings up the (smaller) sub-group.
2.If each of the options is relatively short (a few hundred characters or so), create a MultiChoice *List* of the various options. This routine is easy to implement and will solve most of the 'problems' caused by the limit of 'nine.' The options (and there could be dozens of them in the MultiChoice *List*) are referenced in the source text in this remarkably compact fashion: <<*Options**mylist*>>
Administrative Text: The text to the left of the last asterisk in an <<*Options*>> or <<*Optional*>> text block is referred to as the 'administrative text', as distinguished from the actual choices found to the right of that last asterisk.) We talk about 'administrative text' in other sections of this Manual.
Substantive Text: The text to the right of the 'administrative text' in an <<*Options*>> block is the text that will remain (if chosen) in the final document. This text can be 'real' text (such as was shown in the above examples) or the text can be references to other documents that you want Pathagoras to find and insert. So, an <<*Options*>> block can read like this:

  <<*Options*As per your request, the widgets will be shipped by Federal Express. We will bill you for the extra cost of shipping./As per your request, we will send the widgets by standard ground transport. This may take 3 to 5 additional days./As per your request, we will hold the widgets for pickup by your courier./The widgets you have ordered are not currently in stock. We will ship them as soon as possible. If we have not shipped within 5 days of this date, you will have the option to cancel the order.>>

or the same block can read like this:

  <<*Options*<<shp101>>/<<shp102>>/<<shp103>>>>

which shp101,102 and 103 point to text stored as a document in a folder or glossary. The 'double angle brackets' signal Pathagoras to make the call to the appropriate document. See 'BoilerPlate Text' for more information and more examples.

Tables and <<*Options/Optional*>> blocks: <<*Options/Optional*>> text blocks work well within and without tables. The only restriction is that the block cannot span more than a single cell of a table. This includes starting outside of a table and ending within a table or starting within a table and ending outside a table.
 
An <<*Options/Optional*>> text block can encompass an entire table. The opening "<<" marker must simply  be somewhere above the table and the closing ">>" marker must be below it.
Where to place the slash? Typically, the placement of the slash between choices is easy. When words or sentences are being separated, the slash goes after the last character of the preceding choice. But when the choices are 'paragraphs long', a little experimentation and trial and error might be needed. The logic built into Pathagoras as to how to process the keeping/elimination of  selected/discarded text is complex. Factors such as paragraph indentions, centering, automatic paragraph numbering, and other style considerations makes it impossible to articulate a hard and fast rule regarding where to place the slash. Just perform a couple of test runs using the Process button to see if the result is what you expect. Be sure to test all options.