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.

2. Select the ForEach-placeholder and set its sort-expression to PartNumber.
   * 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.
3. 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.

4. 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.
5. Generate the document to see if it worked.
6. 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).
7. 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:

   

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

8. 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.
   * 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.
9. 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.

10. Select the ValueOf-placeholder for the Total. Its format-property is set to “text” (default). Now set it to “Numeric2”.
    * 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.
11. 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.

12. 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.
13. Generate the document. The total-value should now be displayed as 228,91:

    

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

14. Set the format of all ValueOf-placeholders that display money (UnitPrice and LineTotal) to Numeric2.
15. Generate the document again. The items-table should now look like this:

    

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