XpressDox Help Center

Use Google To Find Help Fast, e.g. xpressdox choosefromlist


Press Getting Started in the XpressDox toolbar for basic template development
Watch the tutorial videos
View command help from list of commands
Press F1 for help on a command in the Command Editor
Email support@xpressdox.com for assistance

Catalog

The Command Editor

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 functioning of the Command Editor has been enhanced substantially with Version 12. These new features will be available to all template authors whose XpressDox instance has been licensed for version 11.1 and later.

The filter area near the top of the Command Editor (CE) (it has the label “Enter the text to search for”) will restrict the display to only those commands, functions, data elements, and scripts that contain the text typed. Thereafter the required item can be double-clicked to display the wizard and have the result placed in the current position in the Word template. Better still, with version 12, the item can be dragged into the relevant spot on the template.

In order to edit an existing fillpoint, you can place the cursor anywhere inside the fillpoint, and then double-click. The wizard for the fillpoint will be presented for your use. If you do not yet have a V12 license, then using the Edit Fillpoint button on the XpressDox ribbon will achieve the same thing.

If you want to select a word inside a fillpoint in the default Word way (i.e. without getting a CE wizard presented) – you can ask XpressDox to switch to the Word double-click mode using the CE button:

What follows is the legacy Help text for the pre-version 12 CE. The use of the shortcut key – referred to by <key> – as discussed below, will no longer work as described. Also, the concept of the Master List, while preserved for legacy purposes, has been replaced by the Standard Items concept, which is accessed via the <Right Click> menu on the CE command list.

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 <key> 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. “«Choose”, but can’t remember how to continue, so presses <key>.  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, <double-click>ing or pressing <Enter> 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 <Enter> (or clicking <OK>) will cause the resulting constructed command to be placed into the template,  replacing the “«Choose” that the author had typed.

If you press <Esc> at any point in the above interaction with the Command Editor or wizard (or close or cancel the wizard instead of pressing <OK>), the focus will return to the Word document at the point where you pressed <key>, and the text which the Command Editor will have removed temporarily will be replaced.

Data Elements.

Command Editor Filter buttonsA 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 <right-click> menu items Include New Data Source/Template or Add/Refresh Current Template.  These two functions are also available on the right of the lower toolbar of the Command Editor).

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 «Name» into the template document (where Name is the name of the data element that you want).  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 <key> 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 <Enter> will insert that data element into the template, surrounded with the fillpoint delimiters « and ».  In addition, the data element name appears in the Command Editor list, below all the command names, grouped with other newly added data elements under the heading “Newly created data elements”.

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.

Master list of data elements

Particularly in a large system with many templates, it is useful to have one place where all the data elements are stored, so they can be referenced within new or existing templates. This master list could be a template into which fillpoints for all the data elements are typed, probably, but not necessarily, including descriptions of what the data elements refer to. The template author would then just need to open the template, or to include the template via the Include New Data Source/Template button.

It is possible to get the Command Editor to include data elements automatically without any user intervention. The way this works is to create a text file (i.e. in Notepad or Notepad++) where each line in the file is the fully-qualified file name of an XpressDox template file, or an XpressDox dataset file, or any other file containing XML. Save this text file with the name SchemaList.txt in your XpressDox Home folder, which is My Documents\XpressDox\Home. Then, when the Command Editor is next loaded, it will automatically load all the data elements referenced in the files listed in the SchemaList.txt file.

Help text in the Command Editor

If you (the template author) define Help text for a data element, then that Help text will be displayed in the tooltip when the cursor hovers over the data element name in the Command Editor.

This feature would be of particular use in the case of the Master List above.

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 <Ctrl – F> will position the cursor in the Find Area at the top of the Editor, and typing “checkbox” and pressing <Enter> 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 <Enter> will locate the next such command in the Editor.   Actually, 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 <Right Click> 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 fillpoint delimiters (i.e. « and ») can be selected and then <key> 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 fillpoint delimiters (») and select the entire command (and delimiters) and press <key>.

With effect from version 4 of XpressDox, this feature has been encapsulated in the “Edit Fillpoint” feature which is in the Template Author’s ribbon in Word. Just put the cursor anywhere inside the delimiters and press the Edit Fillpoint button and the wizard for that command or function will be presented, with the relevant parameters completed from the text of the fillpoint itself.

Special features.

It is permissible to press <key> 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 fillpoint 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 «Tab(Tab Caption, and then press <key>.  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 above makes use of some of the functions explained in the section on the Upper Toolbar below.

The <Right Click> 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:

  1. Command Editor Toggle Delimiters and Insert Comma ButtonsToggle 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 <key> 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.
  2. 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.
  3. Template PainterThe third button is the Template Painter – this colors the various fillpoints in the template, highlighting the block fields (if, ForEach, Else and End) in different colors to show their nesting levels.
  4. Template Author UtilitiesThe fourth button provides access to Template Author Tools.  These are:
    1. Fillpoint Coloring Configuration: using this tool you can specify how the Command Editor should format fillpoints that it inserts into the template.  The font and color can be provided, as well as colors for the different levels of nesting that the Template Painter will use.  Note that even though only 5 different colors can be provided, this does NOT mean that XpressDox permits levels of nesting only 5 deep – the number of levels is unlimited, it is just the number of colors that is limited to 5.
    2. Convert Templates is a tool which enables conversion of templates from document assembly systems to XpressDox.

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 middle two buttons are the filters: allowing either only commands to be shown, or only data elements, or both.  The right hand buttons are for inclusion of the data elements from a new data source or template and from the current template.

With Version 5 of XpressDox, a new button was added to the right of the “list by category” button.  This new button is a “Most Frequently Used” list and shows the commands/functions in descending order of frequency of usage.  This is the button selected in the screenshot below:

CommandEditorToolbars



The ChooseFromDataset Command

We have a ChooseFromRepeatingData command (which is the same as ChooseFromData, but is a more descriptive name), and a ChooseFromDataElements command. The ChooseFromDataset command combines the functionality of the other two, and adds some more flexibility.

The first argument is the name of the data element to be chosen. This is as per convention. The following arguments are in pairs – an XPATH to a particular choice, then an optional XPATH to the value to be shown in the drop down for that choice.

A simple example would be an interview which contains the names of the children in a family, a list of their friends, and the names of the parents. We would like to choose the name of the person most likely to be president. Here’s what the interview construction part of the template might look like:

«CaptureDataElements(Father,Mother)»
«CaptureInGrid(Child,Yes)»
«CaptureInGrid(Friend,Yes)»
«Heading(Child,|Children)»
«ForEach(Child)»
«Name»
«End()»
«Heading(Friend,|Friends)»
«ForEach(Friend)»
«Name»
«End()»
«ChooseFromDataset(President,Father,,Mother,,Child/Name,,Friend/Name)»
«President»

The items in the drop down would then be the Father’s name, the Mother’s name, followed by <each of the children’s names>, <each of the friend’s names>. When the user chooses an item in the drop-down, the value placed into President would be the corresponding value of the data elements Father, Mother, the chosen Child or the chosen Friend‘s name.

Look at what would happen if you replace the above ChooseFromDataset with the following:

«ChooseFromDataset(President,Father,'The Father',Mother,'The Mother','','CHILDREN and FRIENDS',(Child | Friend)/Name)»

This would display the text ‘The Father’ and ‘The Mother’ instead of the Father and Mother’s names (respectively), and put a “heading” between the Mother and the Child and Friend items. And yet the values chosen, and placed in the dataset, will be exactly as for the first example.

More Advanced Syntax

As with many of the XpressDox commands and functions, the power of XPATH is available to the template author. For example, the following command will achieve the same result as the first one:

«ChooseFromDataset(President,Father,'The Father',Mother,'The Mother','','CHILDREN and FRIENDS',(Child | Friend)/Name)»

Or, perhaps, you only want to present the children where the age is greater than 18 (which, obviously, would require capturing the Age inside the Child part of the interview):

«ChooseFromDataset(President,Father,'The Father',Mother,'The Mother','','CHILDREN and FRIENDS',Child[Age > 18]/Name,,Friend/Name)»


The YearsMonthsDaysBetween Function

As its name suggests, this function takes two dates as arguments and returns the difference as a number of years, months and days. It is not the same as combining the results of the MonthsBetween and DaysBetween functions together with the YearsBetween function.

The simplest form takes only the starting date and ending date as arguments, and returns a string with the years, months and days between these two dates. The years, months and days parts are separated from each other by a pipe symbol – |.

As usual, the operation is best explained by way of an example. Here are two scripts and some XpressDox code that demonstrate the various aspects of the function.

«Script(Phrase,Value,Name)»«&Value&» «Value(&Name&)»«Plural(&Value&,’’,’s’)»«ScriptEnd()»
«Script(YMDBetween,StartDate,EndDate)»
«SetVr(‘ymd’,YearsMonthsDaysBetween(&EndDate&,&StartDate&))»
«::ry,SubstringBefore(::gymd,’|’)»
«::rm,SubstringAfter(::gymd,’|’)->SubstringBefore(^,’|’)»
«::rd,SubstringAfterLast(::gymd,’|’)»
The period starting on «FormatDate(&StartDate&,’MMMM d, yyyy’)» and ending on «FormatDate(&EndDate&,’MMMM d, yyyy’)» is: «Phrase(::gy,’year’)», «Phrase(::gm,’month’)», and «Phrase(::gd,’day’)»
«ScriptEnd()»
«YMDBetween(BeginDate,EndDate)»
The value returned by the function with fewest arguments: «GetV(‘ymd’)»
The number of years only: «YearsMonthsDaysBetween(EndDate,BeginDate,’Y’)»
The number of months only: «YearsMonthsDaysBetween(EndDate,BeginDate,’M’)»
The number of days only: «YearsMonthsDaysBetween(EndDate,BeginDate,’d’)»

Remember that ::r is the shortcut for SetVr and ::g is the shortcut for GetV. Have a look at Using and storing variables.


The GT and LT functions

Sometimes it is syntactically impractical to use the characters < and > in a particular context.

For example, you might want to use a Dynamic Caption which is something like this (to use the word “names” or “name” in the caption depending on the number of children):

«Caption(DependantNames,Enter the <IIf(count(Child) > 1,'names','name')||[Names]>)»

The problem with this is that the > when in the context of > 1 will be interpreted as ending the Dynamic Caption and give a syntax error.

In this case, the comparison of the number of Child repeaters with 1 is best achieved with the GT function, thus:

«Caption(DependantNames,Enter the <IIf(GT(count(Child),1),'names','name')||[Names]>)»


Using Scripts in PDF Form fields

When you are defining a PDF form field map in the Prepare PDF Form UI, you can specify that the source for a particular PDF field is either a data element, function call (in fact any XPATH expression which returns a value), or a script.

If one or more scripts are specified, then the scripts need to be defined in a place that the MergePDFForm function knows about.

The way that the MergePDFForm works is that, if it finds a script invocation in the PDF field map, then it searches for a script definition. Suppose the PDF form is called “ABC-File.pdf“, then MergePDFForm will look (in the same folder as the PDF form) for an XpressDox template called “ABC-File.scripts.xdtpx“. If that file does not exist, then it will search for a template called “PDFScripts.xdtpx“.

This means that if you have a number of PDF forms that use the same scripts, then you can use the PDFScripts.xdtpx template instead of making a .scripts.xdtpx for each PDF form.

The scripts template does not need to contain the scripts themselves, but can reference another scripts template that you have. This is done in the normal way, using the IncludeTemplate command (or the IncludeCodeTemplate command).

Scripts as Functions

When including a script in a PDF Form mapping, the syntax for invoking the script must be of the form of a “script as a function”. In other words, if a script is defined as

«Script(Beneficiary)»«SuffixWith(BeneficiaryTitle,' ')»«BeneficiaryLastName»«ScriptEnd()»

In the PDF mapping you would invoke this script, not as UseScript(Beneficiary), but as

Beneficiary()

Then, of course, if you try that, you will get a message from XpressDox saying words to the effect that when you use a script “as a function” then the contents of the script should be exactly one fillpoint. There are a number of ways of achieving this, but here is a straightforward example of how to treat the above script definition:

«Script(Beneficiary)»«concat(SuffixWith(BeneficiaryTitle,' '),BeneficiaryLastName)»«ScriptEnd()»

A very useful side effect of this feature is that you can use, not only scripts, but XPATH expressions, in the PDF field map. So that if you need, for example, the month of signature in a PDF form field, instead of setting a data element to the month and then defining that data element in the field map, just put FormatDate(DateOfSignature,’MMMM’) into the field map.

These two features are available with version 11.4.0, and so you would need to be licensed for XpressDox version 10.5 or later to make use of them.


Save the Dataset into a Database Column

There are any number of reasons that you might want to save the dataset for a template into a single column in as database.  One of these would be to report on the data set, as described here.

The first step is to write the dataset into a column.  This is described in the GetDataset article.

But once the dataset is in a single column like this, you might want to retrieve it into the data set (using the LinkToDataSource command, or IncludeDataSourceData command for example).

Suppose you had stored the dataset in a column called “XML” in the database, and in a row where the primary key (and the ID of the data source) is “AccountNumber”. This saving of the dataset would have been achieved using SetDataSourceData,  something like this:

«SetDataSourceData(‘AccountDataSource’,AccountNumber, 'XML',GetDataset())»

You could get the same row in the database into your dataset when running a template by using

«IncludeDataSourceData(AccountDataSource,,id=)»

If you tried this, you would notice that the dataset column would be retrieved into your template’s dataset as a complex XML element with the parent being named “XML” (i.e. the name of the column). This is probably not what you would like. If you change the configuration of the data source slightly, then the dataset from the database XML column will be retrieved directly under to the root of the template’s dataset, and not under a parent called <XML>.

Here’s how to change the configuration:

Once you have configured the data source, you are able to edit the data source’s definition string, using the “Use Data Source’s Editor” button, as in the screenshot:

After that, select the Collection node in the treeview on the left. At the bottom right of the user interface, you will see something like this:

This is where the column containing the XML data set can be specified.

Once this is done, when that particular data source is used to retrieve the row in the database, then the XML data in the XML column will be inserted into the correct place in the XML hierarchy in the current data set.


The RepeaterPosition Function

Consider the commands OnExitSet and OnEnterSet. These commands are only executed during the lifetime of the interview, and also contain conditions which need to be evaluated when the user navigates through the interview.

Also consider the case where you would like certain actions to take place depending on the position of the current repeater. For instance, you might want to issue a warning as soon as the user adds a new Child repeater into the interview, but only if the new Child is not the first one. This might look like this:

«ForEach(Child)»
Name: «Name»
«Footing(Name,                        )»

«OnEnterSet(Name,Name,FootingText,(position() > 2),'You have exceeded the recommended number of children','',EvenWhenNotEmpty)»

«End()»

On the face of it, this would put the “You have exceeded…” message into the footing of data element Name when the position of the new Child repeater is greater than 2.

Unfortunately, the position() function does not operate until the document is being assembled, as it requires the ForEach to be active. There is, however, the XpressDox function RepeaterPosition() which will do what is required, as follows:

«ForEach(Child)»
Name: «Name»
«Footing(Name,                        )»
«OnEnterSet(Name,Name,FootingText,(RepeaterPosition(Child) > 2),'You have exceeded the recommended number of children','',EvenWhenNotEmpty)»
«End()»

A further feature of this function is easier to describe in the context of an example:

«ForEach(Child)»

Name: «Name»
«ForEach(Pet)»
Pet’s Name: «PetName»
«Footing(PetName,                        )»

«OnEnterSet(PetName,PetName,FootingText,(RepeaterPosition(../Child) > 1),'Only the first Child may have a pet!','',EvenWhenNotEmpty)»

«End(Pets)»
«End(Children)»

Here is an example of how to show the position in the interview:

«SetRepeaterQualifier(Child,No. <RepeaterPosition(Child)> <Name>)»

Try it inside one of the above examples to see the effect.


The Value Function

This function is usually used inside Scripts, when you want to use a script as a function inside another command. The function returns exactly what it is passed, as in:

«Script(DemoValue)»«Value('This is what will be returned by the function')»«ScriptEnd()»

The use of this script “as a function” would be something like

«If(A = DemoValue())»Data Element A has the value “This is what will be returned by the function”.«End()»

The contents of the Script in this case must be a fillpoint, and this fillpoint is invalid:

«'This is what will be returned by the function'»

Hence the use of Value.


The Execute Function

Execute is used when a sequence of functions need to be executed one after the other. It is typically of assistance in the HotDocs® converter.

Here is an (admittedly artificial, but useful for illustration) example:

«OnExitSet(Name,Number,Value,(),Execute(SetV('X',12),IncrementV('X'),GetV('X')),,EvenWhenNotEmpty)»

After the focus leaves the Name field, the Number data element will have its value set to 13.