XpressDox : Best practices (Template authoring)

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.

Designing the interview

Consider the following when designing the interview:

1. 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 (let’s call it the “Document template”) easier to read and less cluttered.  Then, if the code template is included at the beginning of the document 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” that can be re-used across as many templates as necessary.
2. Use IncludeCodeTemplate for this rather than IncludeTemplate. The IncludeCodeTemplate has the specific feature that all paragraphs in the included template that do not have any XpressDox fillpoints 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.
3. 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. If you find you are using the same condition over and over for the purposes of the interview, consider using the «InterviewRelevance()» command.
4. Experiment with commands like «InterviewIsWizard(Yes)», «CaptureInGrid(Repeater,Yes)», «AlignCaptions(Top)» and «TabOrientation(Vertical)». These all affect the layout of the interview and you can pick which you prefer.
5. The «Define()» command is very useful in this context in keeping all the interview-related properties of a data element in one place.
6. 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. This is also true of «InterviewSequence()». The Manage Interview feature will do this for you.

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.
• You could choose to attach a heading or footing to a Placeholder. A Placeholder is an invisible data element that you can add to your interview for the purposes of attaching heading or footing text.
• 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.