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 <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.
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 <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. 
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:
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 <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.- 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 fillpoints 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. These are:
- 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.
- 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:
