Document Template

A document template is used to generate documents in ContactsLaw.

Templates consist of a body (e.g. an ordinary Microsoft Word document) containing content markers, as well as a definition which specifies how content (e.g. data from contacts, matters or other documents) is inserted or manipulated to produce the output.

Templates are designed to be subscriber-independent, making it possible for them to be shared (exported/imported) between different ContactsLaw subscribers without reference to any subscriber-specific resources such as workgroups, document types, roles or fields (which are certain to differ between subscriptions).

To that end, templates have a separate configuration which maps between the abstract resources in the template definition and the specific resources available where the template is used. A given template may have several configurations, either for different workgroups (e.g. utilising specialised roles or fields) or for different purposes (e.g. interactive vs automated). A template cannot be used to generate documents until it has been configured.

Templates in ContactsLaw are available globally or they can be confined to be available only in a particular workgroup.

Properties

Templates have the following properties:

Description - The name of the template, as it appears in the list of templates and for import/export purposes.
Body Format - The file format of the body of the template, which is indicative of the application used to edit it (e.g. Microsoft Word).
Output Format - The file format of the documents generated from the template, if different to the body format. For example, ContactsLaw uses Markdown (.md) templates to generate Email Message (.eml) documents.
Category - Freeform text used to group together logically-similar templates.
Active Indicator - Determines whether the template can be selected during document production. Mark templates as inactive when they are no longer being actively used.
Fragment Indicator - Marks the template as a fragment, which can be inserted into other templates. Fragments are used to define reusable content, such as headers or footers, payment information, etc. Only Markdown (.md) templates can be used as fragments.
History - Describes the changes that have been made to the definition of the template over time, with the ability to revert to an earlier version.
Publisher Information - Specifies the version, author and copyright information if the template is exported.

Template Body

Body Format

When creating a new template, the editor initially starts with an empty body in Markdown (.md) format. ContactsLaw includes a built-in editor for Markdown documents, which can be accessed via the Body tab. Markdown supports a limited set of formatting, including paragraph and font styles, hyperlinks, colours, lists and tables. For more complex formatting, consider using a different file format for the template.

Alternatively, you can set the body of the template using the following ribbon commands:

New - Creates a new, empty body for the template in a particular file format.
Upload - Uploads an existing document to use as the body of the template.

Body Commands

You can use the following commands to manipulate the body of the template:

Open - Opens the body for editing in its associated application (e.g. Microsoft Word).
Check Out - Checks the body out for editing.
Check In - Checks in changes to the body made in an external editor.
Discard Checkout - Discards any changes made to the body since it was checked out.

Style Management

To help with standardisation, some formats (e.g. Microsoft Word) provide the ability to copy styles between templates.

You can either:

Import all of the styles defined in another existing template into the current template; or
Copy some or all of the styles from the current template to other existing templates.

If a style with the same name is already present, it will be overwritten, automatically applying the new style wherever the old style had been used. Otherwise, the new style becomes available to be applied manually. For best practice, you should create styles with generic names (e.g. "XYZ Lawyers Table") instead of using styles that imply specific fonts and colours (e.g. "Purple Table No Border").

Content Markers

The body of a template is the same as any other document, except that it contains markers that instruct ContactsLaw where to insert, remove or repeat content during document generation. The specification for each content marker is defined under the Content tab, but can in some cases be edited simultaneously with the markers themselves (depending on the file format used).

Content markers are usually delimited by curly braces, e.g. {InsertionMarker} or {BEGIN RepeatedBlock}. They must be named, but multiple markers can use the same name if the content specification is also the same. Names must consist of letters, numbers and the underscore (_) character only (no spaces).

The different types of content markers are listed below:

Type	Usual Delimiter	Purpose
Insertion point	`{Example}`	Marks a position in the document where content will be inserted. This can be any combination of text and expressions, including Markdown formatting.
Start of block	`{BEGIN Example}`	Marks the start of a block. Content inside the block (including other markers) can be toggled or repeated according to some condition. If the actual start of the block cannot be represented using text (e.g. the start of a row in a table, a list item, etc) then the specification can describe how to shift its position.
End of block	`{END}`	Marks the end of a block. Start and end markers must be matched, however it is possible to nest blocks inside each other. The same provisions for shifting the position of the marker apply here.

The list of content markers is refreshed after uploading, when checking in changes, or manually via the Refresh command.

Content Outside the Template Body

Some file formats (e.g. email messages) may also allow content specifications for other parts of the document which are outside its body (e.g. from, to, subject, etc). ContactsLaw will automatically create markers for these, as well as display noteworthy message headers on the Body tab.

Assets

Assets are the mechanism through which expressions (as used in content specifications) refer to resources within ContactsLaw. Each asset has a name (which distinguishes it from other assets) and a type (which determines the data that can be accessed through it). The most common asset types are displayed in the dropdown when clicking Add Asset, while less-common types can be browsed separately.

Assets are also hierarchical, e.g. an address asset belongs to a particular contact asset. This avoids the need to separately specify how to obtain the address. Relationships between assets may be mandatory (e.g. between addresses and contacts) or optional (e.g. between contacts and matters). New assets are automatically associated with the selected asset but can be reorganised via drag-and-drop. The tooltip for each asset type lists the possible parent types.

Assets can resolve to multiple resources; for example, if a contact asset maps to a role on a matter, and there are 3 contacts in that role, then the asset will be resolved 3 times. Whenever an expression refers to an asset, it may yield zero, one or multiple values (functions are provided to deal with this). Repetition blocks can be used to manage complex hierarchies of assets that resolve to multiple resources.

The portable nature of templates deliberately separates the definition of assets from their mappings to subscriber-specific resources. The latter occurs during configuration. When designing a template, you should only be concerned with what you need, not where it comes from.

Assets have the following additional properties:

Required Indicator - Marks the asset as mandatory. If unresolved during document creation, this will be treated as an error. This allows the author of the template to avoid making provisions for the asset going unfulfilled.
Multiple Indicator - Allows the asset to be resolved more than once. If this indicator is absent and the asset resolves to multiple resources, this will be treated as an error. This allows the author of the template to avoid making provisions for multiple values.
Requirements - Allows the marking of individual properties of the asset as mandatory. If absent during document creation, this will be treated as an error. This allows the author of the template to avoid making provisions for missing data. For more complex requirements, see Requirements.
Template (fragment assets only) - Indicates that the fragment asset must resolve to a specific template. This allows dependant templates to be exported along with the main template.
Properties (custom assets only) - Specifies the values for each of the properties of the custom asset (since the asset is not resolved during document creation). This allows rates, charges and other variables to be defined in a single place within the template definition.

Authoring a template will be greatly simplified if its assets are defined first; however, you can add or remove assets at any time.

Attachments

Among the available types of assets are documents and images. Adding these assets to a template allows the properties of the document/image (e.g. description, date, etc) to be included in expressions, however it does not cause the content of the document to be included along with them. To achieve this, you must add an attachment. (There are many situations where document properties are used independently of the content, such as when referring to the document that is being generated.)

Attachments are created on existing assets, however there is a shortcut under the Add Attachment command to create both an asset and attachment simultaneously. Any document/image assets that appear in the attachment list will make their content available during document generation. The specific file format determines what to do with that content; for example, adding attachments to an email message or creating hyperlinks in a Markdown document.

Attachments have the following properties:

Inline Indicator - Specifies that the attachment is "inline", i.e. appears in the body of the document, as opposed to the attachments section.
File Format - Requests conversion of the attachment to a particular file format (e.g. PDF). Leave empty to preserve the original format of the document.

Attachments are also used to add images to content specifications.

Content Specifications

Each uniquely-named content marker in the body of the template has a corresponding specification under the Content tab.

The content specification differs depending on the marker type:

For insertion points, the content specification is a sequence of formatted text and expressions. The expressions are evaluated during document production and merged with the text before being inserted into the document (overwriting the original marker). Expressions are shown in a monospaced font with a grey background to help differentiate them from other text.
For blocks (bounded by start/end markers), the content specification consists of a block type and a single expression (along with any modifiers that shift the marker position). The block type can be one of the following:
- Conditional - The expression evaluates to either Yes or No, in the latter case the entire block is removed from the final document. For example, the expression may use the IsNotEmpty() function to test whether a contact has an email address (and remove the block if not).
- Repeated - The expression refers to an asset or list of values that are used as the basis for repeating the entire block. For example, the block may repeat once for each contact that a particular asset resolves to.

You can preview the result of the content specification for an insertion point by toggling between the Content specification and Preview radio buttons. Any asset properties will resolve to example data for the purposes of the preview.

Expressions

Expressions are used extensively in content specifications to refer to data within ContactsLaw. For example, listing the names of the parties on a matter, inserting an address or telephone number, or building the subject line of an email.

The template editor treats expressions differently than other formatted text, therefore you must indicate when an expression is being typed by toggling the Expression command (or pressing Ctrl+E). Expressions appear in a monospace font and are decorated with a grey background. Toggle the command again to return to ordinary text.

While editing an expression, suggestions for the names of assets, functions and other elements are displayed in a popup. The list narrows as you type more of the name. You can manually toggle the suggestion popup by pressing Ctrl+J. Clicking a suggestion displays more information about the element, double-clicking (or pressing the Tab key) auto-completes its name in the editor. You can also hover the mouse over individual parts of an expression for more information.

In some cases, it is desirable to include formatted text within an expression, such as when specifying the results of the If() function. You can enclose text containing Markdown in double-quotes (e.g. "Includes **bold** text"). For more complex formatting, consider using conditional blocks.

Marker Positions

In the case of blocks, it may not always be possible to specify the exact start/end positions using markers alone. For example, text cannot be inserted before the start of a row in a table, so the marker would have to appear in the first cell. Similarly, when the start marker appears at the start of a paragraph, it may be the author’s intention for the block to start before the preceding paragraph break.

To provider finer control over the marker position, you can specify a modifier that shifts the start/end markers in one of the following ways:

Exact - No change in position.
Entire Paragraph - Markers are shifted to surround the entire paragraph in which they appear; if the start and end markers are in different paragraphs then multiple paragraphs are included in the block.
Entire Table - Markers are shifted to surround the entire table in which they appear.
Entire Row (in table) - Markers are shifted to surround the entire row of the table in which they appear. They are typically placed in the first and last cells of the row.
Entire Column (in table) - Markers are shifted to surround the entire column of the table in which they appear. They are typically placed in the top and bottom cells in the column.
Entire Page - Markers are shifted to surround the page (as determined by page breaks) in which they appear. Note: Pages added when text overflows are ignored.

When used outside of a table, or in a file format that does not support them, some modifiers may have no effect.

Images and Fragments

The editor provides dedicated commands for inserting images and fragments into the content specification. Images prompt for the attachment that describes their content (with a shortcut for defining a new attachment) and insert a placeholder, while fragments simply insert the appropriate expression (a reference to the fragment's Body property).

Requirements

Templates can also specify requirements which must be satisfied in order to generate a document. Any asset properties which are marked as mandatory will appear in the list, however you can also add complex requirements.

Complex requirements take the form of a single expression which evaluates to either Yes or No depending on whether the requirement has been met.

During document production, the failure of any requirement defined in the template will result in an error message. This promotes good design and allows template authors to warn users if data is missing or not in the expected form.

Template Configuration

Once created, a template must be configured before it can be used to generate documents. A template configuration instructs ContactsLaw how to resolve assets to subscriber-specific resources (roles, fields, workgroups, etc), as well as specifying the document type used to catalogue newly-generated documents.