The NEW XpressDox Version 14 is now available!

Edit Content
Click on the Edit Content button to edit/add the content.

Best Practices for Advanced Authors: Part I

XpressDox is designed to enable a template author to get started on authoring a template without having to do a lot of pre-configuring, or even much design.  You can just start typing the template and add XpressDox fillpoints as they are needed.

That’s OK if all you are doing is authoring standalone templates which don’t interact with other templates or with databases or other external (meaning external to XpressDox) systems.  As soon as these other interactions are introduced, you are beginning to move from authoring templates to creating systems or applications.

Once you start authoring applications, you have made a quantum leap forward and away from what is really just simple “mail merge”.  Even though you might not think about yourself as a systems developer, that’s in fact what you are doing.  And that means that some of the techniques used by geek-type application developers become useful.  This article tries to give you some hints and advice on how to go about developing a document-centric application using XpressDox.

1. Focus first on the document

The first thing to do is makes sure that the document that is going to be the end product is correctly formatted and worded.

  1. This includes coding the correct fillpoints and deciding on the names and source of data elements (by “source” is meant whether data are to be typed into the interview by the user or included from a data source, or both).
  2. Make sure that the document logic is correct – i.e. that the conditional inclusion of words, phrases and paragraphs is in order.
  3. Assign a useful set of Word styles to the document (this is a huge subject on its own and is not covered here, but that doesn’t mean it is unimportant).

2. Even before that, decide on a naming convention.

There are quite a few chicken-and-egg situations involved.  Although the document is the first priority, you can’t really start on a document without deciding on a naming convention for your data elements.  And a naming convention is very important because typically there will be more than one document in an application (even if the main document is many pages long and is the focus of most of the development, there will nonetheless probably be something like a covering letter and/or invoice to accompany it).  The Cookbook article A Rose by any Other Name contains some advice for designing a naming convention.

3. Code and test the document in small chunks.

Resist the temptation to mark up (i.e. code fillpoints into) the entire document before testing it.  Especially in advanced situations where you have complicated logic in the template – e.g. nested If commands or Select commands, or complex handling of plurals and wording when there are repeaters.

Rather code up to the end of the first bit of complexity, and test the document, making sure that everything you have coded works, under all the various circumstances (combinations of values which affect the conditional logic or number of specific repeaters).  Then continue coding up to the next complex part and test again, and so on.

In some situations it will make sense to create a “snippet” template which contains only one of the particularly complex parts and test that on its own.

4. Design the interview.

This topic requires an article all on its own, and so is covered in Best Practices for Advanced Authors: Part II.

There is a case for designing the interview before coding up the document(s).  Some authors prefer to take that approach because the user (template runner) will interact directly with the interview, and only indirectly with the template and merged document.  The reason for suggesting the sequence as “document first, then the interview”, is that the interview is created by XpressDox using the commands/fillpoints in the template as a guideline.  In particular, the interview relevance is determined in this way, as well as the sequence of appearance of data elements on the interview.  This means that you are going to get an interview created in any case, so if you create the document first with all its document-formatting fillpoints, then interview design becomes an exercise in guiding XpressDox to do it differently, rather than trying to get the interview created in a vacuum.

Table of Contents