Implementing XpressDox : Best practices (Part 2)

The interview is a very important part of any application developed in XpressDox as this is the user experience. You will get a long way with Manage Interview but for some further understanding, it is good to read through this article to understand why certain things are required.

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. You will end up with a very clean “Document Template” and one (or several) “Interview Template/s”.
• 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. The Manage Interview feature will do this for you.

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, clicking on the top right menu and then “Show Hidden Fields” will present some debugging information as you hover over them.  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?” or “Why not?”.
• 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.  Clicking on the top right menu in the Interview, then on Advanced and then on Open Dataset, will open the current data set in an editor. You can also choose to copy it to the clipboard and then open a different editor. Notepad++ is particularly useful for this.