Upgrading to Version 4

Version 4 of XpressDox (XDv4) represents a major change from Version 3.

The principle change is that the format of an XpressDox template is no longer Word 2003 XML, but Office Open XML. Office Open XML (or OOXML) is the format in which Microsoft Word 2007 and 2010 save their documents – i.e. documents saved with .docx (or .docm) extension. In addition, there are a number of useful new commands and functions introduced in Version 4.

This article presents just those issues which the template author needs to take into account when upgrading to version 4 of XpressDox. For a full list of all the changes in Version 4, please see Version 4.1.0 Released.

Word 2003 and XpressDox V4

If you are using Word 2003, then before upgrading to XDv4 you will need to install the Microsoft Office Compatibility Pack from the web site https://www.microsoft.com/en-us/download/.

This very useful extension to Word 2003 enables any documents in OOXML format to be opened in Word 2003 and also to saved from Word 2003 (using the “Save as” function). This capability is needed by XpressDox so that it can save its templates in OOXML format.

Word 2007 and XpressDox V4

It is recommended that you make sure your Office 2007 is at SP2 at least (the latest service pack is SP3). This is to cater for issues which occurred in earlier versions of Office 2007 when opening documents created in Office 2010.

Convert Version 3 templates to Version 4 format

This conversion needs to be done because the XDv4 template format is not the same as in Version 3.

The conversion happens fairly painlessly – using the XpressDox explorer, open a folder containing Version 3 templates, and the explorer will suggest that you convert all of the templates in that folder and its sub-folders.

Clicking “Yes” will cause XpressDox to convert the templates to Version 4 format, and will move the older format templates to a sub-folder called Version3Templates.

In addition, XpressDox can be asked to convert all the folders in the Explorer’s Recently Used list – which will probably cover most of the folders that you use which contain old Version 3 templates.

When a template in the “Favourites” list is converted to Version 4 format, there is no automatic conversion of the file name in the configuration where the Favourite is defined.  However, XpressDox will check, when asked to run a “Favourite”, that a new format template exists, and run that if it is there.

XDv4 Template File Extensions

In Version 3 and previous versions, the XpressDox templates were stored with the file extension .xdtpl.  With XDv4, the actual format of the template is Open XML, but the templates are stored with extension .xdtpx or .xdtpm.  This is purely to distinguish them (in the XpressDox and Windows explorers) from other Open XML documents which will probably be stored with extension .docx (and .docm).

During the conversion process referred to above, if XpressDox is converting an old format template which contains VBA macros, it will save that template as a “macro enabled document”  (which is what Word 2007 and 2010 require), and use the extension .xdtpm.

This change in extension might cause problems where a template author has specified the .xdtpl extension in IncludeTemplate or BaseTemplate commands.  If this has happened, then the templates containing those commands will need to be changed.  The best course is to specify only a template file name without extension, optionally qualified with a helper folder alias.  This permits the actual template file to be saved with either .xdtpx or .xdtpm extension, and XpressDox will resolve that at the time it executes the IncludeTemplate or BaseTemplate.

Fillpoint Delimiters

Prior to XDv4, the default fillpoint delimiters were « and ».  These are now called XpressDox Classic delimiters.  With Version 4, the default fillpoint delimiters for all new installations of XpressDox will be the “chevrons”, i.e. « and ».  This will not affect existing installations of XpressDox.  As before, XpressDox will in any case recognise on a per-assembly basis which delimiters are being used, so that even where a new installation at a site will default to chevrons as the delimiters for authoring, any templates authored (on other workstations) with the XpressDox Classic delimiters will continue to function correctly.

Relevance

The XpressDox relevance “engine” has been upgraded.  XpressDox will now recognise data elements in various commands and contexts where this was not the case in earlier versions.  This will affect the layout of some interviews, because XpressDox has always used the first occurrence of a data element in a template to determine its position in the interview.  Because data elements are now recognised in more contexts than before, this might cause the position of some data elements to move higher up in the interview.

Tab:

Data elements referenced in Tab commands will now be used to determine relative position of the data elements in the interview.  As explained above, this means that if the first occurrence of a data element is in a Tab command, this will determine its relative position in the interview.  This might cause data elements to change their position in the interview compared to interviews created in Version 3.  A workaround for this might be to move the Tab commands to the end of the template or assembly.

If, When, Setv:

Prior to Version 4, these commands/functions (and some other contexts) were not scanned for the occurrence of data elements.  With Version 4, data element names inside these fillpoints are recognised and used to determine relative positioning of the data element in the interview.  This might cause data elements to appear earlier in an interview than in previous versions, and might cause a control for a data element to appear when it did not appear at all in an interview constructed in a previous version.  CaptureDataElement, CaptureLater and ExcludeFromIV can be used either to change the position on the interview of a control or to exclude it completely from the interview.

Choose… commands:

In pre-Version 4 XpressDox, commands such as ChooseFromList, ChooseUsingCheckbox, and others (those in the Data Capture category in the Command Editor) would cause the relevant control to appear in the interview, regardless of whether or not the data element being chosen was used elsewhere in the template.  With XDv4 the control will only appear in the interview if the data element being captured is used elsewhere in the assembly.  The command CaptureAllDataElements can be used to cause those Choose controls to appear even where the data element is not used in the current assembly.

Note that the SetInterviewDataOnly command will issue a CaptureAllDataElements command implicitly.

The new relevance algorithms result in a more consistent treatment of placement of controls on the interview. However, there will be some instances when controls are in different places on the version 4 interview compared to the interview created with earlier versions. Don’t worry if this happens, because judicious use of the CaptureDataElement and CaptureLater commands will place the controls exactly where needed on the interview.

InterviewIsWizard

«InterviewIsWizard(yes)» (see here) is now implemented in the desktop version of XpressDox.  If there are Tabs defined, then those tabs will now appear in the treeview, where repeated items go.

A pair of navigation buttons will appear inside the interview form to help the user navigate through the nodes of the treeview.

Source Formatting

This feature in the BaseTemplate, IncludeTemplate and InsertTemplate has been improved.  No longer will this cause new styles to be inserted into the destination template.  Instead, the style in the source template is inserted with the same name into the destination, and replaces a same-named style in the destination.

This might have unexpected results because if the style “StyleA” appears in source AND destination, then any and all paragraphs in the destination which are formatted according to StyleA will, after the merge, be formatted with the StyleA from the source template.

Please see Source and Destination formatting in Version 4 for more comprehensive coverage of this subject.

Supervisor Functions

The Supervisor, Template Author and Template Runner (new feature) functions are now controlled via special XpressDox licence keys. The “Supervisor Toolkit” program (i.e. the one which was used to “sign” the supervisor’s home configuration) is no longer needed. The Template Author features are also controlled by the licence which is registered for that user, and no longer requires the user to empower themselves as a template author by specifying a password in their home configuration. If you have been using the Supervisor features, please contact support@xpressdox.com to get more information on these features using Version 4.