Docati 

Request a trial-version now and see for yourself!
Contact us at [email protected].

Quickstart - Exercise 4: Advanced features

Outline

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.

Setup

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).

Steps

  1. We're continuing our work on the previous template. Open the "Order3.docx"-template you created in the previous exercise.
    * If you skipped exercise 3, you can also download it here: http://static.docati.com/samples/Order4-Starter.docx
  2. Now save the template with a new name “Order4.docx”

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.

  1. Select the ForEach-placeholder and set its sort-expression to PartNumber. Remember to click apply!
    * The partnumber (aka item-nr) is not a number (it contains alphanumeric characters as well). Therefore the datatype for the sort must be set to “text” (default). If it contained only numbers, we had to set it to “number”, to make sure “9” would be listed before “10”, etc.
  2. Generate the document. You will notice that item “872-AA” is now listed first.

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.

* Styling the ValueOf-placeholder this way probably seems a little weird. Word does allow applying styling to the contents of a content-control (the base-element used for placeholders), but doesn't always store this when saving the document, resulting in the loss of the styling.

  1. Change the styling for the LineTotal ValueOf-placeholder (inside the ForEach): make its content bold. Do this by adding a space in front of it and make this space bold.
  2. Generate the document to see if it worked.
  3. Now align the contents of the UnitPrice, Quantity and LineTotal all to the right (not the headers, just the content cells (which are containing the ValueOf-placeholders).
  4. Generate the document again to see if it worked. If not, again just add a space before each ValueOf-placeholder, apply the styling (align right) to the space, save the template and generate the resulting document again. It should now work. The final result should look like this:

    Apply styling to the ValueOf-placeholder

    * Docati’s behavior of copying styling from leading or trailing content can often help resolving strange styling issues of Microsoft Word itself. Maybe these issues will be fixed with future versions of Word, but for now you’ll find yourself using this trick pretty often.

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.

  1. Add a ValueOf-placeholder to the footer-row (LineTotal-column). Set its Name to “Total” and set its query to: sum(fd:setop("/PurchaseOrder/Items/Item","USDPrice*Quantity")). Make sure you enable the 'Use advanced query syntax'-checkbox and remember to click Apply!
    * The custom setop-function provides a list of line-totals. The sum-operator (which is a standard XPath operator) is then used to calculate the sum of all line totals.
  2. Generate the document. The sum of the line-totals should now be displayed.

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.

  1. Select the ValueOf-placeholder for the Total. Its format-property is set to “text” (default). Now set it to “Numeric2”. Remember to click Apply.
    * Several types of formatting are supported. The formatting-type 'Custom' allows you to specify you own formatting specifier. If you need some other kind of formatting, let us know.
  2. Generate the document. The total-value should now be displayed as 228.91.

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.

  1. On the Docati-ribbon click the “Template Settings”-button. Change the target culture to “Dutch (Netherlands)”. Click Save to close the dialog and also save the template.
  2. Generate the document. The total-value should now be displayed as 228,91:

    Effect of the culture of the template

    * The Dutch-culture uses a comma (“,”) as a 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.

  1. Set the format of all ValueOf-placeholders that display money (UnitPrice and LineTotal) to Numeric2. Remember to click apply each time!
  2. Generate the document again. The items-table should now look like this:

    Formatting applied to all money-placeholders

XML Namespaces

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.

Back to the Quickstart Index