Creating templates
Creating templates requires basic knowledge of Microsoft Word ® and a little knowledge of Docati. For the latter, all you need is this section of our site.
Quickstart Manual
The Quick-Start Manual is a MUST-READ! It consists of a set of exercises that will teach you step-by-step how to create Docati templates.
Even if you haven’t decided to use Docati, these exercises can give you a great impression of how Docati works and what scenarios are possible!
Open the Quickstart-Manual!
Placeholders
Available placeholders are:
-
ValueOf: inserts data
Does what document generation is all about: insert data. By default data is inserted as-is (text). However it’s also possible to specify formatting options, which allows for formatting as a number with a certain amount of digits, a date/time and even allows you to provide a custom formatting string.
-
ForEach: repeats its contents for each data-item
A very powerfull placeholder which allows for iterating over a set/list of data and will create for each item a table row, list-item (eg: for a bullet list), chapters/paragraphs, etc. Items in the list can also be sorted first.
-
ImageOf: insert an image
Just like ValueOf/Value this placeholder inserts content into the document. Instead of just text, this placeholder inserts an image. The image can be provided within the data (base64-encoded)
or referred to using an URL. Image width and height can be manually set, but it's also possible to keep the aspect ratio correct, by locking it to either the width or the height of the placeholder.
-
NEW: BarcodeOf: insert an EAN or QR (bar)code
The data is transformed into a barcode (EAN) or a QR-code image, which is then inserted into the document. Please note that only the barcode/QR-code itself in inserted. If you need the data it represents also to be inserted into the document,
your must add an additional ValueOf-placeholder to do so.
-
If: only renders its content if the condition is met
Allows for conditional parts of the document, eg: a specific chapter only appears if the data contains a specific element.
When using a regular query, you can only check if an element is available in the data and has a value. If you need more complex logic, you need to use an advanced query. For example when you need a 'Score'-element somewhere in the data to have
a numeric value equal or greater than 5.5, you could use this advanced query: //Score >= 5.5
-
UseContext: specifies the data-context
For more experienced users (with xpath-knowledge): when processing its contents, the data-context is set in advance. This allows for shorter/easier data-queries for its child placeholders, thus resulting in better maintainability of the template.
-
ImportTemplate: imports a (sub)-template
A powerfull placeholder that allows you to create templates templates that you can reuse (like sub-templates), for example: a standard header template, a address-block template, etc. Templates can be imported in the main document, header and footer. The ImportTemplate-placeholder can also be used inside a ForEach- or If-placeholder.
Queries
Placeholders that work with data need to be told what part of the dataset to use. This is done by specifying a 'query'. To make it more concrete: the dataset is provided as an XML-structure (json is internally converted to XML) and the query specifies which part of that XML-structure is relevant for the placeholder.
Docati supports queries in two variants:
-
Regular: Only the name of the desired node is specified. Docati will search for any elements or attributes which match that name. The search is case-insensitive and ignores namespaces.
Regular queries are so easy to use that these can be used without support of IT-personnel.
-
Advanced: XPath-query. XPath is a complex XML query-language, yet very powerfull. If you know XPath, you probably prefer advanced queries. Advanced queries are slightly faster than regular queries. Advanced queries are required when using custom functions (like setop(…), current(…), etc).
Docati supports the XPath 1.0 specification.
Both type of queries search within the complete XML, unless a context-node is active (eg by using the UseContext or the ForEach placeholder).
For example, take this data-XML::
If you need the name of the examinee, these are the queries you would specify:
- Regular: Name
-
Advanced: /exam-result/name
(or when namespaces are specified in the XML: /d:exam-result/d:name)
Regular and advanced queries can be combined. This means it is fine to use regular queries most of the time and use advanced queries for more complex situations only.
Namespaces (advanced queries only)
When the data-XML contains namespaces, querying becomes slightly harder. Regular queries still work great, but advanced queries require the use of namespace prefixes (even if the namespace is defined as the default namespace (xmlns="...")).
The namespaces that are used in the queries, must be registered in the template ("Template Settings" on the Docati-ribbon of the Word add-in): for each namespace a prefix is specified which can then be used in the queries. This prefix does not need to be the same as the one used in the data XML, but it usually more clear to use the same prefixes.
When generating a document, Docati automatically registers the namespace of the root-element of the data-XML with the prefix d (which stands for 'default'). If that is the only namespace used in the data XML, there's no need to explicitly register the namespace.
This also means the template will keep working fine when the namespace of the data XML changes after some time.
Namespaces are complex stuff, so lets put all situations together:
-
Data XML uses NO namespaces:
Don't use prefixes in your queries.
Eg: /exam-result/name
-
Data XML uses a SINGLE namespace:
Use the prefix 'd' that is auto-registered by Docati during document generation.
Eg: /d:exam-result/d:name
-
Data XML uses MULTIPLE namespaces:
Register each namespace and supply a prefix for each. Use these prefixes in the queries.
If the prefix 'd' is not explicitly registered in the template, Docati will still register it itself. So the 'd' prefix can still be used.
Eg: /d:exam-result/e:name
When the data was provided in json-format, Docati will internally convert it to XML. This XML does not use namespaces.
Example code
