XML and Data Sets

The core process of XpressDox is the merging of data into a template to produce a final merged document. The XpressDox merging engine thus needs two things: a set of data to merge, and a template into which to merge the data.

The data which XpressDox merges into a template is referred to as a Data Set, and must be in XML format. The template then addresses the data elements in that Data Set by referring to them in Fillpoints.

A typical Data Set might look like this (this is taken from the file SampleLetterToBloggs.xddata.xml distributed with the XpressDox samples):

<SampleLetterToBloggs>
<email>petert@wherever</email>
<FirmName>Inkpen Inkpen & Inkpen, Inc</FirmName>
<Addressee>Mr J Bloggs</Addressee>
<AddressLine1>123 Short Road</AddressLine1>
<AddressLine2>Winelands</AddressLine2>
<AddressLine3>Cape Town</AddressLine3>
<PostalCode>8765</PostalCode>
<SirOrMadam>Sir</SirOrMadam>
<re>The ongoing situation</re>
</SampleLetterToBloggs>

Each data element is identified by a pair of tags which define the data element’s name, and the value of the element appears between the two tags.

In order to have the value of a data element in the Data Set inserted into a document, the template must include the name of the data element in a Fillpoint.

Using the above example, some Fillpoints addressing the above Data Set would be:

«Addressee»
«AddressLine1»
«AddressLine2»
«AddressLine3»
«PostalCode»

Dear «SirOrMadam»
etc

Where do Data Sets come from?

The XpressDox engine does not “care” where a Data Set comes from, as long as it is properly formed XML. And the engine will be able to take data elements from ANY XML document and, under control of a suitable template, insert those data elements into a merged Word document.

In particular that means that the Data Set could be constructed from a database table, or hand-constructed using NotePad or other XML editor.

Or, the Data Set could be constructed by XpressDox. This is what happens when you run an XpressDox template in Word.

The process is that XpressDox analyses the various Fillpoints in the template, and infers an XML structure from that. It then constructs the data capture interview necessary to collect the data element values for that Data Set. Once the user has captured the values for that Data Set, the Data Set and template are presented to the XpressDox engine for merging.

One of the nice things about XpressDox’s Data Set handling is that it is possible for the template author to include XML from various sources into the current Data Set.

For example, the IncludeDataSourceData command will insert data from a Data Set into the Data Set just before the data capture interview is presented to the template user.

Also, ChooseFromDataSource and ChooseFromFile will give the template user the chance to select data which are then included in the Data Set at the point that the Data Set values are being captured into the capture interview.

Further discussion of this topic is in the articles Make data source information available on all templates and Configuring data sources. Also, search the XpressDox web-site for articles on Data Sources and Data Capture.

Why it matters that it’s XML

Much of the time the fact that the Data Set is XML is probably of no concern to the template author. There are some issues, though, to be born in mind:

• The names of data elements need to follow the XML naming rules. That is, they must start with an alphabetic character (upper or lower case) or an underscore. After that, any alphabetic character, any digit (0-9), underscore, full stop (period) and hyphen are acceptable in a data element name.
  Valid names are:
  • Name
  • _bollyWood
  • Address1
  • conseiller.privilégié
  • προτον
• The following are invalid:
  • 1FlewOver – does not start with an alphabetic or underscore
  • First Names – contains a space
• Not only must the data element names follow the above rules, but they are also case-sensitive. That means that Name and name refer to two different data elements.
• XML processors are very forgiving. Which means that it is legal to refer to a data element which does not exist. A command like «If(name = 'fred')» will not fail if there is no data element called name. The result, though, will probably not be the one that the template author expected.

See the W3 Schools web site for more on the naming of data elements.

For XML cognoscenti, note that even though it is not possible for the XpressDox data capture interview to capture values for XML attributes, it is nonetheless possible to reference them in commands in the template. This has bearing when the XML data set is sourced from somewhere outside of XpressDox itself.