Templates - User Guide

Template files are used to organize content that is enhanced with logic and data. They use the *.xsl file extension and follow the XSLT open standard.

Files are accessed using the file tree on the left side of the window, which is discussed further in the Tag user guide.

Using the + menu beneath the file tree you can create a new template file by providing a file name. The Templates screen is shown below after selecting an empty demo folder as the current favorite and creating a new file (demo-templates.xsl).

The + menu also contains a Create report from *.docx document... menu item. This provides another way to create a template file. You only need to select a source *.docx file and provide a new file name.

Template files may be runnable, meaning they can be used to generate a *.docx document. In Tag these are called reports which are discussed further in the next section. A template file that is not runnable can be used to share common templates between multiple reports.

Template files contain one or more templates. Only one template can be viewed at a time, which is done by selecting one in the Show template dropdown list. Tools are provided to add, remove or edit template options. This is discussed further below.

Templates can be arbitrarily complex. They can use conditional logic where more than one possible processing path is possible. They can also call other templates or insert the result of expressions. This complexity is handled in part by the Decision Tree (large white area above the toolbars), which is also discussed further below.

The File options / File settings... menu item opens a dialog that controls how a report is run. If the Treat file as runnable report checkbox is selected, the file can be used to generate *.docx documents. Generation starts at the Start on template and runs until that template is complete (perhaps after calling other templates).

The File options / Import content... menu item opens a dialog that lets you import templates from other files. When you add a direct import, the current file now has access to all templates in the imported file, and all templates in files imported by the imported file (these are called indirect imports).

The File options / Import data setup... menu item works in much the same way. Direct imports are added using this dialog, while indirect imports are specified by imported template files. When a data setup file is imported (either direct or indirect), you have access to all its data fields when writing content and logic.

The File options / Form settings... menu item in the Scribe app opens a dialog that customizes how auto-generated forms display and function. On the Form setup tab you can change the order of forms, the tab names used for forms, or make the form conditional.

On the Data mapping tab you can setup the form to import data from a CSV. After selecting a CSV, you can visually map the CSV columns to data fields in the form.

To map a column to a field, click on the column name on the left side, then click on the corresponding field name on the right side. A line will get drawn between them indicating where data from that CSV column will be copied. You can click on the lines and delete them using the Delete key.

Clicking on a line also allows you to make the mapping conditional, or to transform the data while copying. In both cases an expression is used and attaqched to the mapping command.

These mappings are saved to a *.nsmap file that is referenced by the report. When mappings are available, forms will provide options to import data values from CSV files (other sources are possible). More information about mapping is provided in the Scribe forms guide.

When content is generated, each logic bubble is replaced with whatever it represents. When if, choose/when or call-template instructions are used, the flow of generated content can change dramatically.

In other words, a smart content report can generate hundreds or even thousands of different iterations of a document based on the data encountered.

Because there can be multiple iterations for a report, and to keep the display from becoming too confusing, only one fragment of text is viewed at a time. You select which fragment to view using the decision tree graph at the top of the editing area.

The words on the graph are clickable and help with navigating around your report. The blue circles can open and close for ease of viewing.

When you select a conditional instruction, the fragment it protects is displayed in the editor beneath the expression. Clicking the pencil tool to the right of the expression will open the expression editor.

For simple reports, a single start template will suffice. For more complex documents, it makes sense to use multiple templates to keep things organized and promote reuse.

Templates are displayed using the Show template dropdown list. Adjacent tools let you add, remove and edit.

When creating a new template, you start by choosing a unique name. In the Scribe app, you can then choose between creating a Standard or Widget template. If you choose Standard, you are done and the new template will display ready for content. If you choose Widget, you must choose a widget type as discussed below.

Helpful hint about template names: when inserting a call-template instruction you need to specify a template name. This is done using a dialog that lets you view existing templates as a list (see below) or a tree. The tree is created by looking for "." characters in the template name and using them to create parent branches. For example, the following template names:

Will display in a tree of template names like this:

Some templates allow you to pass in data when calling them. These passed-in data values are called parameters. The following screenshot shows a call-template instruction for he-she.

A single parameter called gender can be passed in. Note that it has a default value, which in this case points to the client's gender (assessInfo:gender). This is correct for most of the times you want to use he-she, however you may have another data field that stores a different gender (e.g., caregiver:gender). In that case, you would select Pass in value and use the expression editor to select the desired field.

Global parameters can be defined at the template file level (not within a template). These passed-in data values can be accessed by all templates in the same file. The Automate app allows you to pass-in values for global parameters in the Generation settings tool panel on the right-hand side of the template editor.

The Scribe app includes the concept of widget templates. Note that this feature is not part of the XSLT open standard, and will only work in the Scribe app in Tag.

When creating templates, you can specify a template Mode of Widget. When that is done, you can choose between a Widget type of Combine Strings inline and Bulleted or numbered list.

Both widget types work roughly the same way. You specify a list of strings, each protected by an if expression. When generating, only strings that have an expression that resolves to true will be included.

For the above strings and the Combine strings inline type, the result would look like this:

"vanilla, chocolate and strawberry"

For the above strings and the Bulleted or numbered list type, the result would look like this:

• vanilla
• chocolate
• strawberry

or

1. vanilla
2. chocolate
3. strawberry

More widget template types may be added in a future release.