Smart Content Templates Manual

Template files are used to organize content that is enhanced with logic and data. They use the *.xsl file extension and follow the W3C-backed 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 manual.

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). Several examples of how this works are provided in the step-by-step guides on our website.

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

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 Forms manual and the CSV Import step-by-step guide.

The main editing space simulates a word processor. Common tasks are supported by toolbars which are above the main editing space.

This screenshot shows the start template is still selected. That means when the *.docx document is generated, it will start with the content specified here. The following sections discuss toolbars which can help you edit this content.

Document toolbar

The top tool on the Doc toolbar opens a header/footer editing space.

When the header/footer editing space is showing it adds a new toolbar as wide as the page, just above the typing space. The Show menu lets you swap between different headers and footers.

Because the Different page 1 header/footer checkbox is selected, there are four different objects that can be edited as shown in the open menu above. Each object is optional. If the checkbox is not selected, the editing choices are Header or Footer.

The Insert menu lets you insert page number or page count values. Note that these values aren't used while editing in Tag, however they get converted to page number and total number of page fields in generated *.docx documents.

The header/footer editing space is closed by clicking the X (right of the Show dropdown list), or by clicking the header/footer tool once again to toggle it off.

The bottom tool on the Doc toolbar opens a Default format settings dialog with multiple tabs. The This document tab lets you set the default font, font size and paragraph alignment for the current document.

The All documents tab provides access to global preferences that work on all template documents.

The Bottom margin is picked up whenever you create a new paragraph using the Enter key. The Font size multiplier is used to change the appearance of fonts within Tag without changing the specified font size that ends up in generated content.

The Remove empty paragraphs in output checkbox is helpful because sometimes when you use conditional logic, you end up with an empty paragraph. If this checkbox is true (recommended), empty paragraphs are removed during generation.

The Block style updates tab creates custom named styles. More precisely, it creates named bundles of format properties that you can apply to blocks (paragraphs) with a simple menu selection.

You can modify font-related, alignment and margin format properties, and save them as a group using any name you want. You can then apply them to blocks while typing using a tool on the Block toolbar as discussed below.

Editing toolbar

The Editing toolbar contains familiar editing tools including cut/copy/paste. It also has placeholders for undo and redo commands.

The find/replace menu has two options.

The Find/replace in displayed content... menu item opens a Find and replace dialog. It works much like other find/replace dialogs with one important difference. If you select the Use templates checkbox, the replace-with part of the command will insert a call-template instruction instead of typed characters.

An example of how this works is provided in the DOCX Import step-by-step guide. It shows how to replace all occurrences of "She" with calls to the He-She template, which will insert "He" or "She" according to the current gender value when generating content.

The Search all templates within document... menu item opens a Search dialog with a wider scope than find/replace. It searches through all templates in a document rather than just the displayed content. It can also search multiple files in a folder, or search for expression fragments instead of text.

Inline toolbar

The Inline toolbar contains familiar inline text tools including font, font size, bold, italic and text color.

It also has a more menu (three vertical dots) which has a Force a space menu item. This is sometimes needed when you have two adjacent logic instructions, and want to ensure a space is inserted between them in generated content.

The more menu also has an Inline properties... menu item which provides a way to modify inherited properties for inline spans of text. For example, if you bold a few words and select some of the bold characters, you are selecting an inline span of text. This inline span can also be used to change inherited format properties for all characters in that span. This is shown below.

The Inherited value (Normal) is shown read-only for reference. You can change the Current value and it will only affect the selected inline span of characters. You can also change font, font size, italic and text color properties which are all inherited.

While inherited properties may not be commonly used on inline spans of text, the same mechanism works on blocks and tables as discussed below.

Block toolbar

The Block toolbar contains familiar editing tools for block (paragraph level) content including ordered/unordered lists, margins and text alignment. It also has a block style update tool (pen tip) that lets you apply block style updates to selected text as discussed earlier.

The more menu has several items including Block properties..., which works just like Inline properties... above except these inherited properties are applied to selected blocks instead of inline spans. The same list of inherited properties are supported (font, font size, bold, italic and text color).

The Clear inline formatting menu item does what you would expect, and removes all formatting instructions from the selected blocks.

The next two menu items require a bit of explanation. Blocks are used to group lines of text, just like paragraphs in a word processor. Sometime you want this, and sometimes you want to work with text that is buried within a block (e.g., create a dynamic phrase, or insert a name). If your report contains a mix of block and inline level templates, then you may get unexpected results in the generated *.docx file (e.g., vertical spacing that is too large or too small).

These menu items let you fix this issue. If the selected text already has blocks, the Change blocks to plain text menu item will be available, otherwise the Change plain text to block menu item will be.

Finally, the Add space before and Remove space after menu items are shortcuts for changing the space before/after of selected blocks. When space is added, the default Bottom margin setting discussed above is used as a space value.

Image toolbar

The Image toolbar allows you to insert images using the image (top) tool.

If you select an image that is already in text, you can open the Image properties dialog using the properties tool (bottom, three horizontal dots).

The Image properties dialog lets you change height, width or both of the selected image. If the Preserve aspect ratio checkbox is selected, the original width-height proportion will be maintained as image size changes.

Table toolbar

The Table toolbar handles all table editing commands. It allows you to insert tables using the table (top) tool. When inserting a table, you specify the number of columns/rows, table width, table style, columns widths and inherited properties.

The more menu (three vertical dots) is enabled if you select any text within a table. It contains several options for modifying a table.

The Table/Row/Cell properties... menu items all work the same. They open a properties dialog that focuses on only one part of the table's structure (table, row or cell level). Inherited properties can be assigned at all three levels, allowing you to easily create some nice table formatting effects.

The Insert and Delete menus will add or remove columns and rows based on the current selection. For example, if three columns are selected and you select Insert / Column to right, three new columns will be inserted instead of one. The Delete / Table menu item will delete the entire table.

The Select table and Copy table menu items are convenience items to save you some mouse actions.

Logic toolbar

The Logic toolbar is where things stop working like a normal word processor. It supports four kinds of logic instruction:

• call-template (insert content from a named template)
• value-of (insert the value of an expression, which may include or combine data field values)
• if (only insert fragment if an expression resolves to true)
• choose/when/otherwise (insert the first when fragment with an expression that resolves to true; if none do, insert the optional otherwise fragment)

All of these instructions look the same when inserted within text - we call them logic bubbles. They behave just like small images and flow within text as you type.

When a document is generated, each logic bubble is replaced by the content it represents. Instructions can be nested and combined in many ways.

When a logic bubble is clicked, action buttons display to provide more options.

Much of the power of logic instructions comes from expressions which are discussed in the next section.

When several logic instructions are combined together, it can be tricky to keep track of all the possible processing paths. The Decision Tree graph provides a visual representation of logical flow as described below.

When calling named templates, it is possible to pass additional data (parameters) to the template using expressions. This is explained in the Templates section below.

Each tool on the Logic toolbar remembers the last 10 ways that you used it, and includes them as convenience menu items as follows.

The Samples app includes several examples that use templates like his-her and he-she. The same technique is easily adapted for other, different data setup files.

Expressions are a critical smart content mechanism. They are used to calculate values, make decisions and manipulate text. Expressions are based on XPath, which is a W3C-backed open standard that is widely used.

To make it easy to work with expressions, Tag offers three different point and click editing panels. These are described below along with a raw syntax panel.

When most logic instructions are inserted or edited, an expression editor dialog is opened. You can move between editing panels using radios buttons at the top. The term expression editor is used to refer to the expression editor dialog in this document.

Sometimes, moving to a different panel may cause part of an expression to be lost. When that happens Tag prevents you from selecting the other panel. You  need to delete the existing expression before selecting an incompatible editing panel.

Quick values panel

The Quick values panel displays all visible data fields in a tree. You select the field you want, optionally choose a format, and click Insert. This creates a simple expression that copies a data value.

If the data type supports formatting, additional branches are added to the tree to select common formats. This is shown above under the Date of birth branch.

Basic panel

The Basic panel is ideal for creating true/false expressions used to control if and choose/when instructions. It creates conditions, which have left and right parts joined by a comparison. An expression in this panel consists of one or more conditions (joined by and/or).

Each of the words shown above are touch-sensitive and will display a popup menu when clicked.

The left and right words represent data fields or literal (manually entered) values. The center word displays a list of comparisons that are appropriate for the type of data being compared.

• true/false - equals, does not equal
• numeric - equals, does not equal, <, <=, >, >=
• characters - equals, does not equal, contains, starts-with, ends-with, matches-pattern

This is how two conditions look. If you click on the 'and' you can change it to 'or'.

The above example shows data fields using names that contain a colon (e.g., assessInfo:program). The part before the colon is called a namespace prefix, and usually corresponds to a data setup file where the prefix matches the base file name (e.g., assessInfo:program refers to the program data field defined in the assessInfo.rng data setup file). Using prefixes makes it possible to use multiple data setup files together in one report.

Advanced panel

The Advanced panel is similar to the Basic panel, but with much more functionality. It is a full-featured touch-sensitive expression editing panel that can handle most, but not all, XPath syntax.

Each part of the expression in the advanced expression editing panel is clickable and presents a popup menu with available options. Expression parts can be nested and grouped within brackets.

The Function... menu item opens a dialog with dozens of functions to choose from. This is described further in the next section.

Functions

The functions dialog displays a tree of all available functions. Most are defined by the open XPath standard. These are supplemented with 1-2 dozen that are only supported in nSymbol Tag.

Each function accepts zero or more arguments. In the Advanced panel, each argument is edited using its own specific popup menu. Links to more information about each XPath function are provided in the functions dialog.

The following screenshot shows how a format-date function looks in the Advanced panel.

Raw syntax panel

The Raw syntax panel is a text area that accepts raw XPath syntax. In rare cases where the Advanced panel does not support what you need, this panel can handle 100% of XPath syntax.

If errors are detected, a message is displayed beneath the text area to describe the issue.

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. You 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:

Parameters

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.

Widget templates

Tag includes the concept of widget templates. Note that this feature is not part of the XSLT open standard, and will only work 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.