Best Practices for Advanced Authors: Part II – The Interview.

The interview is a very important part of any application developed in XpressDox.  The amount of time spent developing the interview can often be the same as or even more than the time spent in getting the format and wording of the merged document correct.

As explained in Part I, it is recommended that the interview be developed only after the template has been developed to the point where it will correctly generate the required document and has been tested thoroughly.

1. Designing the interview

Consider the following when designing the interview:

• Put all of the interview-control code into a separate template, and include it using «IncludeCodeTemplate()».  There are many benefits to this.  Firstly, it makes the original template easier to read.  Then, if the code template is included at the beginning of the original template, it will determine the sequence in which data elements are presented in the interview.
• Use IncludeCodeTemplate for this rather than IncludeTemplate, because the IncludeCodeTemplate has the specific feature that all paragraphs in the included template that do not have any XpressDox fillpoint in them will be ignored.  That means that you can, for example, divide your template up using Word headings and table of contents, and put plain-text comments throughout the code template.  Be aware, though, that XpressDox commands and functions that would normally insert text into the document will continue to do this.
• If you have a number of templates in the application, consider including the same code template at the beginning of all the templates.  This will take advantage of Usage Relevance – i.e. if the value of a data element is not needed in the template (e.g. in a plain fillpoint like «Name» or to evaluate a condition, like «If(Name != ‘’)») then the control for capturing that data element will not appear in the interview.  This means that all templates that use that code template will have the same look-and-feel.
• Experiment with commands like «InterviewIsWizard(Yes)» and also «CaptureInGrid(Repeater,Yes)».  Take note of how these (and other commands) differ between the desktop and web versions of XpressDox.
• The «Define()» command is very useful in this context in keeping all the interview-related properties of a data element in one place.
• If you are going to be using Tabs, then placing the «Tab()» commands before all the other commands (or at least before the commands relating to the data elements within each Tab) will ensure an easy way of defining the sequence in which the data elements will appear on the interview: they will appear in the order in which they appear in the Tab commands. This does not mean that Tabs always define the sequence in which data elements appear on the interview – this will be true only if the Tab commands appear before other references to their data elements.

2. Debugging the Interview

Trying to work out why data elements are missing from the interview, or appear in the incorrect place or under the wrong conditions can be a tiresome and tedious exercise.  There are some tools available to the template author for this.

• When the focus is in a control for a data element, pressing <Ctrl-Alt> will present some debugging information in the Help area of the interview.  In particular, the name of the data element will be shown, and, if there is a condition on that element, it will also be shown.  Sometimes this will help answer the question, “Why is this data element showing up on the interview?”.
• One issue that often crops up is how to attach commands like Heading or Footing, etc. to a ChooseFromDataSource control.  The command does not refer explicitly to a data element, but XpressDox creates a place holder data element with the name “XD” followed by the data source name.  And it is this “XD<something>” which is used in the Heading, Footing, etc.
• Another issue around ChooseFromDataSource is that the only way to issue the command when it applies to a repeater is within a «ForEach()» block.
• Sometimes it helps to be able to see what the XML data set looks like at a particular point in the interview – for example to be able to view data which are included from a data source, or perhaps to work out why a condition governing a particular data element does not seem to be functioning correctly.  Pressing <Right Click> on the mouse in most parts of the interview will present an option to copy the data set to the clipboard.  If you choose that you can then paste the result into something like Notepad or (preferably) Notepad++ and then inspect the data set as it is at that point in the interview completion process.