In the previous exercises you learned how to create a template for Docati. The template looks pretty good, but it’s not finished. In this exercise you’ll learn how to finalize it.
The prerequisites for these exercises are listed on the Quick-Start introduction-page.
This exercise uses the same data-file as the previous exercise. You can download it here: http://static.docati.com/samples/order-basic.xml (you must save it to a local folder on your computer, you need it later).
The ForEach-placeholder, added in a previous exercise, allowed us to add a table/list to the document. However, the items are not sorted: item-nr “926-AA” was the first item in the list, while it should have been last.
You can apply styling to certain placeholders. You already did so with the ImageOf-placeholder, but its also possible with the ValueOf-placeholder. Docati will copy the styling of the text before or after the placeholder is copied. If only the content rendered by the ValueOf-placeholder needs to be styled, just apply the styling to a space you place before or after it.
In a previous exercise we used the ForEach-placeholder to create the list of items. The LineTotal-placeholder did not directly render a specific data-value, but it used a formula to calculate the value. Using formulas requires the use of advanced query syntax. Advanced queries are basically XPath-queries. XPath is very powerfull, yet also limited. Docati provides several custom functions to enhance the possibilities of XPath and therefore take away some of its limitations.
The ‘footer-row’ of the items table contains a cell that is supposed to contain the total price. This value can be calculated by taking the sum of all line totals. However, the line totals did not exist in the data. They had to be calculated as well, for each separate row/item in the set. Calculating the total is not possible with basic XPath. Therefore we are going to use Docati’s custom function ‘setop’ (set-operation). It takes a query that results in a set and a query that provides the operation to apply to the set. The result must be a list of nodes/results.
Because of rounding-issues, caused by XPath’s sum-operator, the result is displayed with too many decimals: 228.90999999999997. We need to apply formatting to the ValueOf-placeholder using the Format-property.
Format-specifier Numeric2 means its value should be treated as a number and should be rounded and displayed with 2 decimals. It’s not possible to specify a decimal- or thousands-separator. Instead, you can specify a culture for the whole template. When the template was created, the Docati Word Add-In set the culture based on the culture of the Windows-installation it was running on. The starter-templates for these exercises have the culture set to “English (United States)”. This means it uses dots (“.”) as decimal separator.
You may also notice that the other values did not change. This is because we never specified a format, so they as displayed exactly as they appeared in the data.
If the data-XML uses XML-namespaces, regular queries are a big help since they ignore those namespaces, allowing queries to be as simple as possble. When namespaces happen to change over time, regular queries will keep working fine.
Advanced queries however do not ignore namespaces. If the data XML does not use namespaces (like the sample used in these exercises), even advanced queries remain pretty simple, but if they do, advanced queries MUST specify the namespace to match. Since XPath is the technique behind advanced queries, namespaces can be specified using prefixes. These prefixes must be registered with the template ("Template Settings"-button on the Docati-ribbon). A query using namespace prefixes could look like: /er:Exam-Results/er:Score
While generating a document, Docati auto-registers the namespace of the root-element in the data-XML with the prefix 'd' (default). If only this namespace is used, you can simply use the 'd' prefix and omit registering namespaces manually. Using the default prefix, the query mentioned before would look like this: /d:Exam-Results/d:Score.
This was the last exercise of the Quick-Start Manual. You should now be able to create your own templates. If you get in trouble and need some help, just drop us a message and we’ll see what we can do. If you don’t feel like creating templates yourself, we can also do this for you. Contact our sales team for more information.