The CaptureDataElement command was originally called DefineDataElement, which can still be used, for backward compatibility.
The background to this command probably needs a bit of experience in authoring more complex templates. Because XpressDox uses XSLT technology to format the documents, it is possible to use XSLT and XPath expressions to control some of the processing.
In particular, this is the situation with the If and When commands, which, because of their potential complexity, XpressDox does not analyse for data elements to be captured.
In some situations, the nature of the If/When condition will be such that one or more of the data elements in the If/When condition will not actually appear in the template to be inserted into the document. In other words, the data element values are only used to evaluate whether some other data element(s) should be included in the document.
If the data elements only appear in the condition, then they will not be presented to the user in the data capture form, and they will be missing from the data and the If/When condition will always evaluate to false.
So, to ensure that the data element is presented to the user for capture in the data capture form, XpressDox provides the CaptureDataElement command.
An example might be:
The following books are priced below R400:
<<ForEach(book)>>Title:
<<If(price<400)>><<Title>>
<<CaptureDataElement(price)>>
Author: <<Author>>
Date Published: <<FormatDate(datepublished,yyyy-MM-dd)>>
<<End( ForEach)>>
Note that the CaptureDataElement appears in a paragraph all on its own. XpressDox will remove the entire paragraph from the resulting document.
The above could have been written as follows for even better readability:
The following books are priced below R400:
<<CaptureDataElement(book/price)>>Title:
<<ForEach(book)>>
<<If(price<400)>><<Title>>
Author: <<Author>>
Date Published: <<FormatDate(datepublished,yyyy-MM-dd)>>
<<End( ForEach)>>
The book/price syntax is XPath syntax and means ‘the price element which is a child of the book element’. XPath and XSLT are huge subjects on their own, and are not described here. However, because these two technologies are used within XpressDox, one of the results is that there are many situations where the CaptureDataElement might come in useful.
There is a second parameter to the CaptureDataElement command, being the type of the required data. For example
<<CaptureDataElement(DateOfBirth,date)>>will cause a calendar control to appear on the interview, and<<CaptureDataElement(Price,Decimal)>>will automatically include a Rule that the captured amount must be a valid number.
This article was written very early in the life of XpressDox, before the Choose… commands were designed. It would now often be more appropriate to use <<ChooseFromList()>> or <<ChooseFromRDBList()>> or similar commands rather than <<CaptureDataElement()>>.
