The Command Assistant (or Command Editor) empowers the template author by presenting a list of all the XpressDox commands, with functionality which provides wizards for completion of the command as well as supplying examples of those commands. The Command Editor also provides functionality for easily selecting the correct data element from a list of existing data elements.
Videos:
Please visit the Videos page for 2 videos on using the Command Assistant.
Getting started.
Typically, the author will have a new or existing template and come to a point where they 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?”. Type “checkbox” into the filter area near the top of the Command Editor (CE) (it has the label “Enter the text to search for”) and the contents that are subsequently displayed will be restricted 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 older versions of XpressDox, before the introduction of the filter the best method would be to use <Ctrl – F>. That will position the cursor in the Find Area at the top of the Editor. Thereafter, 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, simply double click on the fillpoint. There is a button on the CE to toggle between the XpressDox double click (which edits a fillpoint) and Word double click (which selects a word). The icons are described below.
There is also an Edit Fillpoint button on the XpressDox ribbon.
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
Note that all buttons are also available from the drop down button.
The Upper Toolbar
- The first 2 buttons increase and decrease the font size of the command names in the CE.
- The third button adds a new data source (schema) or a template to the CE in order for the data elements from the data source or template to be accessible under the Data Elements section.
- Add a Standard template. This is a set of data elements which will appear in the CE on all templates and is useful when authoring suites or packages of documents which all share common data element names.
- The short syntax of writing variables. e.g.
«::GAmount»
. For more information on variables and the syntax, click here. - Refreshes the current template i.e. add the current template’s data elements into the CE.
- 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 this button.
With the default XpressDox double click selected, you can place the cursor anywhere inside a fillpoint and double-click to edit it. The wizard for the fillpoint will be presented for your use. Clicking the Edit Fillpoint on the XpressDox ribbon will do the same thing.
The Lower Toolbar
- The left two buttons toggle between an alphabetic list and a list by category.
- Next is a “Most Frequently Used” list and shows the commands/functions in descending order of frequency of usage.
- The fourth button toggles whether results of the Command Editor are enclosed in « and » delimiters when selected. This button is checked by default.
- The last button is invisible by default and becomes visible when the fourth button is “unchecked” – when that third button is unchecked it means that the Command Editor results are NOT enclosed in « and ». By default this button is checked, meaning 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).
This can be useful if you are constructing say, a Tab command, and want to include data elements from the list in the Command Editor. In your template, type«Tab(Tab Caption,
and then instead of typing the data elements, double click on them from the CE. Each will be entered without delimiters and will be followed by a comma. Once you are done you can complete the syntax of the tab command with the closing)»
If that second button in the CE is unchecked by the author, then CE 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.
If you have an older version:
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 “Toggle Word/XD double click” button located on the second row of icons in the CE.:
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. In the rest of this discussion the symbol <key> will stand for “(Press(ing)) the Command Editor shortcut key”.