XpressDox » XpressDox Cookbook

Document per Repeated Item – with Filter

Peter Tuffin — Thu, 15 Jul 2010 11:03:10 +0000

Please see the recipe Document per Repeated Item for an introduction to this concept.

Now, following on from the above discussion, suppose we need a separate document for each of the sureties, but only if a particular surety has a net asset value of $100,000 or more. The template itself will remain unchanged except that a SetMultipleDocumentFilter command will be applied to it. Here follows the original example, slightly modified and incorporating with this new command:

I, <> <> (Born on <>) hereby declare blah blah.
blah

My net assets are $<>

<= 100000)>>

Signed: <> <>

This would result in one document being produced for each surety, but only if that particular surety’s net asset value is greater than $100,000.

This is fine so long as the minimum net asset value is always going to be $100,000. But suppose you want the user (i.e. the person running the template) to be able to set this minimum value from one application to another. You would then have a data element called something like MinimumAssetValue which is captured in the interview outside the scope of the sureties, and the resulting template snippet would look like this:

<>

I, <> <> (Born on <>) hereby declare blah blah.
blah

My net assets are $<>

<= ../MinimumAssetValue)>>

Signed: <> <>

You will notice the ../ before MinimumAssetValue. This is because the scope of the data elements in the condition is by default the repeating data element – in this case Surety. In order to reference a data element higher in the XML hierarchy, the ../ notation is used. A fairly comprehensive discussion of this is contained in the recipe Working with repeated elements under the heading Referencing Non-repeating elements within a ForEach block.

Working with Repeating Data – Part 2

Peter Tuffin — Mon, 28 Jun 2010 16:15:31 +0000

This recipe continues the discussion in Working with repeated elements, which has as its example a Will where the children are the repeating elements.

Another common issue with repeating data is the requirement firstly to present a list of the repeating instances (in the previous example, the children) and then refer to items within the list by their ordinal values (i.e. first, second, third, etc.). This is a rather complicated way of saying something like this:

Suppose some of the children in the list are still at school, and some not. Then suppose the Will needs to refer to the still-at-school children by saying something like:

Any children still in school, which at the time of writing are the second, third and fifth child, will be provided for ….

As a starting point, something like this would get the process going:

Any children still in school, which at the time of writing < 1,are,is)>> the <><><>< 1),!, )>> <><> child, will be provided for …

This will work nicely if there is more than one child, but will not place “and” between the last and second-last children. Usually this is tackled using the last() function, but last() applies to all of the elements in the ForEach, and in this case that is not correct, as we need it to apply only to the sub-list of children who are still at school, not to all the children.

What we need to do is keep a separate count of children still at school (i.e. set a variable to the value of count(Child[StillAtSchool = ‘Yes’)])) and also a manual version of position() – recording the position in the sub-list of still-at-school children. For this we will set a variable NumberOfSchoolChild which will be incremented each time a still-in-school child is dealt with.

This is what it would look like:

<>
<><>

Any children still in school, which are the time of writing < 1,are,is)>> the <><><>< 1)>><>, <><> and <><>< 1)>><><><> child, will be provided for …

It is quite complicated, but then it’s a complicated problem! And this is the solution.

The CaptureLater Command

Peter Tuffin — Thu, 24 Jun 2010 13:37:56 +0000

The CaptureLater command assists the template author in defining the relative position of data elements on the data capture interview screen.

When a template is run, XpressDox constructs a data capture interview which is guided by the XpressDox merge fields which are coded in the template. In particular, the sequence in which controls (those areas on the form where data values are typed) appear on the screen is the sequence in which the corresponding data elements are encountered by XpressDox in the template.

Thus a template looking something like:

<>
<>
<>

would result in the controls for Addressee, AddressLine1 and AddressLine2 appearing in the interview in that sequence.

However, a slight modification to this, such as:

<>
<>
<>
<>

would cause AddressLine1 to appear first in the interview (followed by Addressee and then AddressLine2), as the Heading command is the first place that AddressLine1 is referred to.

Some template authors take advantage of this behaviour by, for example, defining a template with only <>, <> and <> commands which is included at the start of all templates (with the <> command) and this has the effect of defining the sequence in which data elements appear on all interviews for those templates. Read more about layout of the interview here.

However, there is a side effect of this behaviour related to the <> command, which may not be desired.

For example, a template (called the originating template) contains the <> command. The base template (i.e. the template called CompanyLetterHead.xdtpl) looks something like:

<>
<>
<>

<>

and the originating template (whose text will replace the <> field in the base template) looks something like:

<>
<>
<>
…
…
…

The intention of the template author is that the data elements ProductName and SerialNo appear at the top of the interview.

However, when the interview is constructed, the “template” that XpressDox is given to analyse is actually the base template with the originating template inserted where <> used to be. That means that XpressDox “sees” the Addressee, AddressLine1 and AddressLine2 data elements before it sees the Caption commands for ProductName and SerialNo. What this means is that the data elements in the base template will automatically appear in the interview above all the elements defined in the originating template. Which in this example is not what the template author wants.

The CaptureLater command was introduced to assist with this sort of scenario. When the command <> appears somewhere after the <> field (or, in fact, after any other command referencing the Addressee data element), this instructs XpressDox to defer its decision about where to place the Addressee field on the interview until it encounters another merge field referring to Addressee. If this next occurrence (after the CaptureLater command) of Addressee itself is followed by <> then the process continues until either an occurrence of Addressee is NOT followed by CaptureLater, or until the last occurrence of Addressee (whether followed by CaptureLater or not), in which case this defines the relative position of Addressee on the interview.

In the example above, the Base template could be coded something like:

<>
<>
<>

<><><>

<>

This would have the effect that the relative positioning of the three data elements (i.e. the 3 referred to in the CaptureLater commands) on the interview would be defined by the positions of those data elements within the originating template. If the originating template has no reference to the three address data elements, then the CaptureLater commands have no effect and the address data elements are positioned relative to where they were last encountered – i.e. at the top of the interview.

Another mechanism for directing the position of those three data elements in the interview would be to place the following in the originating template at the relevant position:

…
…

<><><>
<><><>

The CaptureLater command was introduced with Version 3 of XpressDox and is unavailable in previous versions.

Adding comments to a template

Peter Tuffin — Sat, 05 Jun 2010 11:12:59 +0000

When the template logic becomes complicated or there is some other need to record why certain constructs were used in a template, then commenting becomes useful and necessary.

Comments can be added to a template in two ways:

1. Include the comment text in the command itself. (This applies to commands as against functions, although this will be rectified with time. More information on commands and functions is available at Commands and Functions).

This is done by typing the comment after the closing parenthesis of the command, e.g.:

<>

2. The second mechanism for entering a comment in to the template is to use the Comment command, e.g.:

<>

The Command Editor

Peter Tuffin — Tue, 11 May 2010 15:25:27 +0000

The Command Editor empowers the template author by presenting an alphabetic list of all the XpressDox commands, with functionality which provides wizards for completion of the command as well as supplying examples of commands. The Command Editor also provides functionality for easily selecting the correct data element from a list of existing data elements.

The Command Editor is best accessed via a shortcut key, which in turn means it would be preferable to add the ribbon button to Word’s Quick Access Toolbar so that it is easily accessed via the Alt key and one further keystroke. (Or, in XpressDox for Word 2003, the shortcut key which can be seen in the XpressDox menu in Word can be used). In the rest of this discussion the symbol will stand for “(Press(ing)) the Command Editor shortcut key”.

Getting started.

Typically, the author will have a new or existing template and come to a point where she would like to enter a command but can’t remember either the command’s name or syntax or both. Imagine that she has typed the first few characters of the command, e.g. “<. The Command Editor will display and locate the first occurrence of a command which matches the word immediately to the left of the cursor – i.e. “Choose”. The author can then navigate either with the mouse or with the up-and-down arrow keys to the command that she requires. Navigation can also be achieved by typing even more of the command, e.g. “ChooseUsing”, and the Editor will position itself at the command first matching that (or, typing “C” and waiting a fraction then typing “C” again will scroll through the commands beginning with the letter “C”, and so forth).

Once the desired command is found, ing or pressing will select that command – meaning that a default wizard for that command will be presented with some sample values in its fields. The wizard fields can be modified, or else just left as is and pressing (or clicking ) will cause the resulting constructed command to be placed into the template, replacing the “<

Data Elements.

A template author does not need assistance only with typing of commands, but also with selecting the correct data elements. The Command Editor helps with this as follows: the lower of the two toolbars which are visible in the Command Editor has two “Filter” buttons (the two on the right each with a little funnel in it), one for commands and the other for data elements. Checking the data elements filter (the buttons will display as highlighted when they are “checked”) will include data elements from any templates or data sources added to the Editor by the user. When a template is opened using the XpressDox Explorer, then its data elements are automatically included in the Command Editor view. (Other data elements can be included by using the menu items Include New Data Source/Template or Add/Refresh Current Template).

But when first starting off on marking up a template, there will be no data elements in the Command Editor. One way to add new data elements to a template is to just type <> into the template document. But, with a few more keystrokes all sorts of things are achieved. So: the recommended way of inserting a new data element into the template is:

Type the name of the data element where you would like it in the template (it’s not necessary to type the << beforehand). Then press and, (as long as the data element name is not part of an existing command or data element name) the first entry in the Command Editor is highlighted. This is the “Insert Field” entry – pressing will insert that data element into the template, surrounded with the merge field delimiters << and >>. In addition, the data element name appears in the Command Editor list, below all the command names.

This automatic insertion of the data element names into the Command Editor list also happens when a Command Editor wizard is run and the the new data element name typed into the wizard in the relevant place.

Thereafter, double-clicking a data element name in the Command Editor list will insert that data element into the template.

When a data element is required in a command (such as, for example, the first parameter to all the Choose… commands and many others like Caption, FormatNumber, ForEach, Heading, etc.) then the wizards will present the available data elements in a drop-down list.

Finding text within a command.

Sometimes you don’t know how a command begins but you do know that the name contains a particular string somewhere. “ChooseUsingCheckBox” is a case in point. “Is it ChooseWithCheckBox? or SelectUsingCheckBox? or CaptureWithCheckBox?”. The key will display the Find Area at the top of the Editor, and typing “checkbox” and pressing will locate the command (and, in fact, any data element that might contain “checkbox” in its name). If there is more than one command (or data element) which meets the search criteria, then pressing will locate the next such command in the Editor. The search for the string is not confined to the name of the command only, but also to the description, and also to the descriptions of any extra wizards and examples (available in the menu), to try to make the search yield a relevant result as often as possible.

Reverse Engineering a command.

Sometimes you have a command in an existing template which has some parameters omitted and you would like to supply some or all of the missing parameters. ChooseFromDataSource and IncludeDataSourceData are good examples of this, as they have quite a few optional parameters. Instead of re-typing (or getting the Command Editor to re-type) the command from scratch, the entire command, including merge field delimiters (i.e. << and >>) can be selected and then pressed. XpressDox will then do its best to reproduce the original wizard which would have been used for the command, with the parameters in the correct places and the optional parameters given reasonable suggestions.

This feature can also be done while inputting a new command, where you have entered some or most of it and can’t remember how to continue: just close it off with a closing parenthesis and optionally the end merge field delimiters (>>) and select the entire command (and delimiters) and press .

Special features.

It is permissible to press at any point in the document, but XpressDox tries to determine from the context what the author might want. In particular, if the character immediately to the left of the Word cursor is either a comma or an opening parenthesis (bracket), then XpressDox will infer that the cursor is already in the middle of a command. Then, any command or data element which is selected in the Command Editor will be inserted into the template without the enclosing merge field delimiters (<< and >>) and followed by a comma.

This is particularly useful when entering commands such as the Tab command which accepts multiple data element names as its list of parameters. The way a Tab command would be entered would be to type < and then press . The Command Editor will present a list of commands and data elements, and each data element selected will be inserted into the template, followed by a comma, and the focus will be left in the Command Editor, so that the next data element can be selected. When the last has been selected, the template author just presses <Escape> and deletes the last comma in the command and finishes the command off with )>>.


The  Menu
The items in this menu are fairly self explanatory.  Two of the very useful ones are the Wizard and Example menus.  Most commands will have at least on Example available and many have a choice of Wizards.
The Toolbar Buttons – the Upper Toolbar
The upper toolbar has buttons on it that govern the global functioning of the Command Editor.  From left to right their functions are:

Toggle whether results of the Command Editor are enclosed in << and >> delimiters when selected.  This button is checked by default, but will be “unchecked” automatically in situations where  is pressed and the character immediately to the left of the cursor is a comma or opening parenthesis – as described in the discussion on the Tab command above.
The second button is invisible by default and becomes visible when the first button is “unchecked” – when that first button is unchecked it means that the Command Editor results are NOT enclosed in << and >> (which is what happens in the Tab example above).  By default this second button is checked.  This means that when a result is inserted into the template, it will be followed by a comma (hence the icon on that button being a comma). If this second button is unchecked by the user, then Command Editor results are inserted into the template neither enclosed in << and >> nor followed by a comma.  This can be very useful if you are changing the names of data elements in an existing template – just select the old data element, and double-click on the new data element name in the Command Editor.  As long as this second button is visible and unchecked, the result will be the renaming of the old data element.
The third button is the Template Painter – this colors the various merge fields in the template, highlighting the block fields (if, ForEach, Else and End) in different colors to show their nesting levels.
The fourth button provides access to Template Author Tools.

The Toolbar Buttons – the Lower Toolbar
The lower toolbar buttons govern the appearance of the command/data element list in the Command Editor.  The left two buttons toggle between an alphabetic list and a list by category.  The right hand two buttons are the filters: allowing either only commands to be shown, or only data elements, or both.


Related posts:
The Template Author’s Toolkit
Caption command: provide a useful name for data capture
The CaptureLater Command
Version 2.1.3.1 (2009-07-27)
The SetInitialValue Command



Concatenating strings
Peter Tuffin — Sat, 24 Apr 2010 13:33:24 +0000

A pluralising example
Suppose you have a need to create an XpressDox Variable which will contain either a singular or plural from a data element.  Using the example of a Will in Working with repeated elements, we might want to use the word “child” or “children” in many places, and not want to use <> everywhere, but rather use a variable, e.g. <>.
There are a number of ways of setting the variable “childword” to the required value, but here is one that makes use of the concat function inside a <> to concatenate the suffix “ren” to the word “child” when the number of Child data  elements is greater than one:
<>

< 1)>>

<>

<>


Thereafter any execution of <> will put the correct variation of “child” or “children” into the merged document.
A file path example
Another use of the concat function would be to construct a file path given its constitutents.  For example, suppose the drive, folder and file name are located in three separate data elements.  Setting a variable to contain the full file path would look like this:

<>


Related posts:
Working with Repeating Data – Part 2
Test for Any or All repeated items meeting criteria
Notes on XpressDox syntax
Using variables
Using and storing variables



Test for Any or All repeated items meeting criteria
Peter Tuffin — Fri, 26 Mar 2010 13:36:07 +0000

Suppose you are preparing a template for a Will, where various provisions need to be made for the children of the testator.  The children will then be represented on the template as a repeating item, and in various parts of the template, tests would be made to determine whether any or all of the children meet the necessary criteria.
Somewhere in the template the children would be listed, perhaps like this:
The children are:

<>

Name: <>

Gender: <>

Age: <>

<>

You may then have a paragraph in the Will which needs to be included only if any (or in other words least one) of the children is a minor (i.e. age less than 18).  The test for “Any” would look like this:
< 0>>

The minor children must be blah blah …

<>

Another paragraph is required only if ALL the children are minors.  This test would look like this:

<>

blah …

<>
See the Cookbook article Working with repeated elements for more information on repeated data elements.


Related posts:
Working with repeated elements
Working with Repeating Data – Part 2
Document per Repeated Item – with Filter
Document per Repeated Item
Concatenating strings



Trouble shooting missing pictures in documents
Peter Tuffin — Mon, 15 Mar 2010 15:22:20 +0000

Pictures, logos, etc., are normally handled seamlessly by XpressDox.
Sometimes, though, pictures can go missing from the document when it is merged.
This can happen if the same picture occurs more than once in a template.  It seems that Word optimizes its memory usage by storing this picture once in the document, as a kind of master version of the picture, and then referring to this master version from the other places in the document where it’s required.  Which is quite clever, really.
This can lead to strange behaviour if the first occurrence of the picture in the document is made dependant on some or other condition.  If that condition works out to a “false” value when the template is merged, and the master picture is then excluded from the merged document, then the other places that require this picture will not be able to find the master.  Usually what happens is that Word puts a square with a red X in it where you would like the picture to be.
The way around this is to make sure that the first occurrence of the repeated picture always appears in the merged result.


Related posts:
Trouble shooting Conditional Capture
Trouble Shooting XpressDox Startup
Trouble shooting Ends and Elses
Run a template for a number of data sets, and print the merged documents



Trouble shooting Conditional Capture
Peter Tuffin — Fri, 05 Mar 2010 10:32:07 +0000

Conditional Capture refers to the feature in XpressDox which hides fields in the data capture interview if the conditions for rendering that field into the merged document are not met.
Take the following snippet of a template as an example:
<>

<>

Spouse’s Name: <> <>

<>
When this template is run, the interview will include the radio button list with the Y button checked (because the first value in a ChooseFromRdbList is always the default value).  Because the value of Married is ‘Y’, the If command evaluates to true and so there will be fields for the capture of SpouseFirstNames and SpouseSurname on the interview.
As soon as the user running the template clicks the N button in the radio button list, then the SpouseFirstNames and SpouseSurname fields will disappear from the dialog.  This is Conditional Capture.
Some Typical Scenarios
Sometimes this feature can appear to be working incorrectly.  This can be for a number of reasons, typically:

Setting a value in a Choose… command but testing against another data element:  e.g. in the above example, if the If command were <> then the result will always be false (because the data element being tested is married, with a lower case “m”).  This is because Married and married are two different data elements, because data element names are case sensitive. So in this case the data element married will never be equal to ‘Y’.
Similar to the above, but testing against the incorrect value:  e.g. if the If command above were to read <> or <> or <>.  Notice that in the last case, the test is performed against the values of the data element Married and the data element Y.  This is because the Y is not in quotes and so is regarded as the name of a data element, not a string literal with the value ‘Y’.
Sometimes a data element can be subject to more than one condition, in which case the data element might always appear on the interview.

Show Hidden Fields
When conditional capture causes some fields to be hidden in the interview, then a checkbox labelled Show Hidden Fields will appear at the bottom of the interview screen.  When this is checked, XpressDox will display the hidden fields, but in a disabled, read-only state.
If you click on a disabled field, then the condition which governs that field will be shown in the Help area.
Often just inspecting that condition will be sufficient to detect any errors or misperceptions.

When the keyboard focus is on a non-hidden field, then if you press the Ctrl and Alt keys simultaneously, XpressDox will display the data element name (in case it is different to the caption) as well as the condition applying to that field.


Related posts:
Conditional Capture
Trouble shooting missing pictures in documents
Trouble shooting Ends and Elses
Trouble Shooting XpressDox Startup
Data capture interview layout tips



Trouble shooting Ends and Elses
Peter Tuffin — Fri, 05 Mar 2010 09:22:49 +0000

In complex templates, the balancing of <> and <> commands with the matching <> or <> can become difficult.
The Template Painter
The Template Painter tool can be very useful for this.  The Template Painter can be invoked either from the Common Tools menu (Word 2007) or the Template Author toolbar (Word 2003) or from the toolbar on the Template Author’s Toolkit (TAT).
The Template Painter will highlight matching start and end block commands (If and ForEach commands are known as block commands) with the same color, and at the same time format all the merge fields with the font and color which can be set using the Define the font and colour of merge fields button on the TAT (this feature in the TAT also enables you to change the colors that the Painter applies to the start and end block commands).
In addition, the Painter will notify you when there are missing or extra (floating) End commands.  Floating End commands are highlighted with the text <========.  The floating End command is not removed, because it might in fact be the correct command and an End earlier in the template might be the floating one.
Running a Template – the Debug command
When a template is run, XpressDox will check for missing and floating End commands as well as floating Else commands.
Wherever possible, the error message warning about one of these situations will give some context within the document where the relevant command is, so that you can find it easily and correct the situation.
But sometimes it’s not possible for XpressDox to provide a context.  When this happens, XpressDox will recommend that you use the <> command.  When you put the Debug command somewhere (preferably right at the top) in the template, then if there is a floating End or Else command in the template after that Debug command, then XpressDox will highlight that floating command in the text of the merged document.
When there is a Debug command in a template, XpressDox will put a big ugly warning at the top of the merged document warning about the presence of the Debug command, so once there are no more floating commands, the Debug command should be removed.


Related posts:
Trouble shooting missing pictures in documents
Trouble shooting Conditional Capture
Trouble Shooting XpressDox Startup
Using block commands in XpressDox Docussembly™
Version 2.3.1 (2010-03-03)