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 installations).
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.
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. Specifically, 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 creation. 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
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.
Once set, 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.
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.
Purposes
Templates can be configured so that ContactsLaw will use them for a specific purpose:
- Fax
- Letter
- Invoice - Generated when an invoice is finalised.
- Receipt - Can be generated on-demand from a transaction of the appropriate type.
- Report - Can be generated on-demand from any built-in report.