Document Templates

This article is a technical overview on the purpose and capabilities of Digital-Clay Document Templates. It is not a tutorial on how to build Templates.

Document Templates are templates that are used in Digital-Clay to generate documents. The Template may contain static content, as well as instructions for generating dynamic Digital-Clay content which is only filled when the document is generated. In other words, the procedure is:

1. A developer or administrator creates the Document Template typically using the Document Template Builder. This only needs to be done once.
2. The Template is deployed or sent to any end-users that need it (see Sharing & Deploying Templates).
3. The end-user generates a document from the Document Template as many times as necessary (see Generating Documents). Documents can be generated for different records, or using different dynamic filter values.

Some examples of documents that can be generated:

• A printable form containing all the fields in the current record(s).
• Receipts and invoices.
• A report on all related items of the current record(s).
• A letter or newsletter containing mail-merged fields.
• A general multi-page sales analysis report.
• A CSV file with a list of Contacts for scheduled exporting.
• An XML file for automatically sending updated data to an external data source.

Document Templates are typically HTML files (other formats are also supported) that contain Digital-Clay 'tags' with instructions for adding dynamic information to a document. For example:

• Item Fields. When a document is generated for a record, field values such as the Contact's Name, or the Estimated Sales, are inserted/mail-merged into the document.
• Queries: Lists, analysis tables, graphs, charts, etc. These are run when the document is generated, and the results are inserted into the document.
• System fields: E.g. The company logo, a document sequential number, the date filter value, etc.

The document that is generated from the Document Template may be generated in the same format as the template (HTML, TXT, XML, etc), or it can be generated as a Word, Excel or MHTML document.

A Document Template can be edited either in an external editor (e.g. an HTML editor), or by using the Digital-Clay 'Document Template Builder', depending on whether you wish to add static or Digital-Clay content respectively. An existing file can also be converted into a Document Template using the Document Template Builder.

Document Templates, by default, are standard HTML files for all intents and purposes. This means that Document Templates:

• may be edited using any HTML editor, including MS Word.
• may include any standard and advanced HTML features and tags.
• may link to external files and images. See Linked Files.

This only applies to the Document Template format. When a document is generated from a Document Template, the user may choose to automatically convert it to MHTML, Word or Excel.

In addition to HTML as the Document Template format, other text-based formats are supported such as TXT, CSV, XML. For example, a CSV file can be created that contains only a Digital-Clay tag for creating a table of results with custom separators (see below). The rest of this article will refer to Document Templates as HTML templates because this is the format used in the vast majority of cases.

Document Template file-name extensions: A Document Template must contain a double file extension: 'stm', and the original file extension. For example: 'Report.stm.html', or: 'Output.stm.csv'.

Some examples of HTML content that may be included in Document Templates:

• Static text, such as the content of a standard letter.
• Images.
• Styles and external style sheets.
• Floating windows and dynamic content using style sheets.
• Embedded objects like Flash content or Applets and ActiveX components.
• Javascript or VBScript code that can:
  • Calculate values.
  • Display dynamic content.
  • Modify Digital-Clay content after it is generated.
  • Communicate with servers using AJAX.
  • Communicate with embedded objects such as Flash, Applets or ActiveX.
• If the Template is generated as an Excel document, the template may also contain Excel functions which will be run when the Excel Document is opened.

IMPORTANT: The HTML content must be in standard HTML format. This means that when editing Document Templates in MS Word, you must save it as “Web Page (Filtered)”, otherwise Word adds proprietary Microsoft-specific tags to the HTML file.

A Document Template typically contains a basic HTML skeleton and Digital-Clay fields with optional additional HTML content. The Digital-Clay fields are edited using the Document Template Builder, and the HTML content is edited using any HTML editor. The order with which this is done is not important. For example, you can:

• Start a Document Template using the Document Template Builder, then optionally edit it in Dreamweaver when you are done generating the Template (only if HTML content is needed).
• Create an HTML document in Word, then open it in the Document Template Editor to add Digital-Clay content.
• Write a letter using Word, then copy and paste merge fields from the Document Template Builder tool (using the Copy buttons) directly into Word. This allows you to position the Digital-Clay content exactly where you need it amidst the HTML content.

Note that when you open an existing HTML file or Document Template in the Document Template Builder, it maintains the HTML content as is and only displays the Digital-Clay fields for editing.

Also note that HTML files must contain at last one Digital-Clay Tag in order for the HTML file to be recognized as a Document Template. This can be achieved by copying-pasting the tag into an existing document, or by opening and saving the document at least once in the Document Template Builder.

Using the Document Template Builder, Digital-Clay fields can be added to a Template either by:

• Clicking on the buttons inside the Builder to add new fields and queries.
• Building/opening a list, analysis query, graph, or chart as usual in a desktop client, then clicking on Save/'Add to Document Template'. This will send the currently open query to the Document Template Builder window.

All Digital-Clay query fields such as lists, analysis, graphs, charts, gauges and scorecards can be set to use dynamic filters. The user will then be asked for filter values before the document is generated.

For extra settings (e.g. dynamic filters, table settings, totals, groupings) related to Digital-Clay content inside Document Templates click on the Properties button in the Document Template Builder.

All Digital-Clay content in a Document Template is contained in %Clay…% tags (and their corresponding data in the <ClayData></ClayData> section). These are not HTML tags and will therefore appear in all HTML editors as normal text so that they can be positioned and treated just like text.

An example of a merge field: “Dear %Clay Last Name%,”

A Digital-Clay tag/field may be used anywhere in HTML content, this includes:

• As part of a sentence.
• The results of an analysis query can also be inserted as part of a sentence instead of being displayed as a table by using the “Use Table” and “Single Value” settings.
• Inside an HTML table.
• As a value inside an HTML form input tag.
• Inside javascript code so that the code can process the results of Digital-Clay values and perform calculations with them or change how they are displayed.

Another proprietary tag used by Digital-Clay is the %StartClayHeader%…%EndClayHeader% set of tags. Anything contained within this set is treated as a Document Template header. This is relevant when a document is being generated on multiple items: The header will appear only once, or repeatedly before every item, depending on whether the user selected to start a New Page before each item or not.

HTML Styles

Styles can be applied to Digital-Clay content either by:

• containing the %Clay..% fields inside HTML elements that specify HTML styles.
• applying global style sheets to all HTML elements like 'table' or 'td'
• applying style sheets to specific Digital-Clay tables using style sheet overrides (e.g. wrap the %Clay…% field inside a <div class=“special”>…</div>, then create a style sheet for “.special table {…}”).
• applying styles to Digital-Clay classes (e.g. “table.data {…}”). The Digital-Clay classes are:
  • 'header' for the header section (optional).
  • 'data' and 'data2' for Digital-Clay tables (this includes the tags: TABLE/TH/TD/TR). 'data2' is used for alternate lines.
  • 'document' for the separation between documents when generating documents on multiple items (this includes the tags: TABLE/TH/TD/TR).
  • 'filters' for the filter values section when “Show filter values” is on for a query.
  • 'group' for group headers, and 'grouptotal' for group sub-totals.

Document Templates are always stored on a hard drive as files (not in a database) where a Digital-Clay client can access them. This is also so that templates can be edited using any HTML editor, and also in order for the templates to work even while a client is offline.

The location of these templates must be defined so that Digital-Clay clients can scan the folder for templates when the user wants to generate a document.

• The default location is C:\DigitalClay\Templates\ under the subfolder for the current interface language (e.g. EN\). This folder is shared by all users/clients on that machine and therefore has different subfolders per language.
• The default location can be overriden per Digital-Clay user in Tools/Options.
• The Template Location can also be set to point to a mapped network drive so that users on multiple machines all share the same Template folder.

For information on how to get the Document Templates into this folder, see Sharing & Deploying Templates.

Note that Digital-Clay also supports sub-folders under this root Template folder. I.e. Templates can be organized under sub-folders and then the user can select which sub-folder to scan for Templates before generating a document.

One disadvantage of using HTML files, is that external files such as images are stored often as local files. This means that when a Document Template is shared, all local files must also be copied along with the HTML file. Digital-Clay addresses this in version 9.0 by sharing Document Templates as 'template archives', or zip files. When a user sends or shares the Document Template from inside Digital-Clay, the internal procedure is completely transparent and works as follows:

1. The HTML file is scanned for all links to external files.
2. All files that are stored as local files only (not http links) are copied to a single subfolder along with the HTML file.
3. A zip file is created that includes all of these files and this archive is sent instead of the HTML file.
4. At the receiving end, the zip file is unzipped into the user's Template folder.

One exception is HTML frames. Digital-Clay does not currently support HTML frames since this involves several HTML files.

Note that this is only relevant to the Document Template itself. When a document is generated from a Document Template, the user may choose to automatically convert it to MHTML, Word or Excel all of which embed the external files inside a single document.

If the document is generated in HTML format, then:

• If the file is viewed or printed locally on the same machine, then obviously there is no problem.
• If the document is sent as an e-mail by Digital-Clay, all local external files are automatically attached to the e-mail.
• If the file is saved and then copied, external files must be copied manually along with the generated HTML document.

Tables inside Document Templates are, by default, generated as HTML tables. This includes lists (browser queries), and analysis queries displayed as tables.

Using the 'Properties' button inside the Document Template Builder, this behaviour can be changed:

• Table headers can be switched on and off.
• The table total row can be switched on and off for browser queries.
• Groupings: A new table can be started for each column value with nested groupings and sub-totals.
• Other values that can be displayed: Row numbering and row counts.

In addition, the table itself can be customized:

• The table can be removed so that all the values are displayed as a simple flat list separated by semi-colons.
• The table tags or separators can be completely customized (see the screenshot on the right) in order to support other formats or styles (for example, a CSV list, an HTML table with custom styles, or an XML structure):
  • The table start/end tags (e.g. <TABLE> & </TABLE>).
  • The row start/end tags (e.g. <ROW> & </ROW> or a '\r\n' new-line mark for CSV files).
  • In order to support alternate row styles (e.g. a different color for every second row), the 'alternate row' tags can be set. If these are not set, the default row tags are used for all rows.
  • Header cell start/end tags (e.g. <TH> & </TH>). Note that this is ignored if the headers are switched off, and this is only relevant for browser queries.
  • Cell tags, either globally for all columns (e.g. <VALUE> & </VALUE> or per column (e.g. different tags per column for XML structures).
  • The default buttons provide shortcuts for some standard formats, but the tags can be fully customized even for external programs requiring specific tags.

The most important concept in a Document Template is its topic. The topic is either 'General', or a table like 'User', or 'House'.

When the topic is 'General', this means that the Document Template is not generated based on specific records; it is not dependent on records and is generated without selecting any records first. This means that:

• Mail-merge fields are not allowed. Since a 'General' Template is not created for a specific record, there can be no fields to fill, only queries to run.
• Filters inside queries cannot be replaced dynamically based on which record is currently selected (but dynamic filters still work).
• 'General' documents can only be generated in the Documents tool, or from a customized item in the Toolbar, or in a Scheduled Automation that is also not based on any table.

To help you decide which topic to choose, here are some examples:

• If you want the user to be able to pick Product(s) from a browser list and generate a report that contains information relevant to that Product, then you must select Product as the topic.
• Similarly, to generate documents from inside data forms, the topic cannot be 'General'.
• If you want to create a mail-merge document, you need to select a topic other than 'General', based on which table you want to display fields from. For example, if you want to send a standard letter to Contacts, you must choose Contact as the topic.
• If you want to create a manager's report on all items in a table (for example, a sales report for all users), then you need the 'General' topic. Note that General reports can still contain dynamic filters but this is optional.

As explained above, Document Templates are stored locally per client. In order to share or send the Document Templates to other end-user machines, the following options are available:

• Profile Management. A Document Template may be shared via Profile Management either from the Profile Management tool, or from the Document Template Builder itself using the “Assigned To” button when generating the Template. This is the easiest and most recommended method.

• 'Menus for Template Actions' feature (9.0 and up): This feature stores the Template in the database, and when a user runs this action for the first time, the Template is retrieved and copied locally.

• Messaging: Open a Document Template in the Documents tool and select “Send To..” to send the Template to other user(s).

• Sharing: Same as the above but select “Share…” to store the Document Template in a public folder. Users can then browse through the Document Repository and double-click on the Templates they need in order to retrieve them.

• Shared network folders: If all users have access to the same network drive and need the same Document Templates, they can all be configured (Tools/Options) to save and retrieve templates from the same mapped network folder, thus allowing one user to manage Templates for all the rest.

Also see above regarding Linked Files.

An end-user can generate a document from a Document Template using any of the following options:

• Select an item or several items from a list, and click on “Print/Save Document” from the context menu.
• Open an item and click on the “Save Document” or “Print Document” buttons in the toolbar.
• Running the Documents tool from either the toolbar or ClayStudio.
• Launching Document Templates from the toolbar. Add them to the toolbar using the Tools/Customize function.
• The 'Menus for Template Actions' feature (version 9.0 and up): This works in lists and in forms, and displays a customizable menu of pre-defined actions that generate documents.
• Creating an Automation with a “Create Document” action, and then triggering the Automation Event.

When selecting multiple items to generate a document on, there are several options:

• 'Combine all items into one document': This generates a single document, and every field or query will contain values for all of the selected items combined. For example, if Contacts A and B are selected, the Contact Name field will display “A,B” and a list will contain records related to both A and B.

• 'Start every item in a new page': A single document is created, the document template is repeated once for each item with page breaks in between them. Note that the page breaks will only be visible if the document is opened in Word, or if the document is printed. If a header exists, it will be displayed before each item.

• 'Continuous items': Same as the previous except no page breaks are inserted and the header is displayed only once at the beginning of the document.

• 'Labels': Same as the previous except each item is inserted into a table cell. The Rows setting defines how many table rows are displayed per page, and the Columns setting defines how many items are displayed per row. For example, if 6 items are selected and the settings are 1×2, then the document will contain 3 pages, each page split vertically showing two items side by side. This option is also useful for printing labels with dozens of items printed on one page.

• 'Mail merge': This creates one document/file/email per item depending on the output option selected. This is the setting to choose when mail-merging a letter with several items, or when you want to generate several separate files, one per selected record.

Note on grouping vs. selecting multiple items: Another option for displaying one table per item is via the Grouping setting. E.g. a list can be generated containing all Tasks and their assigned Users, and then it can be grouped by User, thus creating a separate table of Tasks per User. The differences between the two features are:

• Grouping does not allow displaying multiple items, tables, graphs, static text, etc per item. It only splits a single table.
• Grouping cannot insert headers and page breaks between items.
• Grouping can split a table for any type of field, whereas generating a document on multiple items can only 'split' a table based on linked fields/records.

See also Auto-Attaching Documents and E-Mails and Document Types.