A template is a Microsoft Word document with bookmarks for the application to insert data into when generating correspondence. The properties that matter when creating a template are:
- File name
- Location
- Bookmarks
File Name:
The file name for a correspondence template has to match the Template Code for its associated application record. If the application record already exists, make sure you save the template with the correct file name, or at least rename it to match. Otherwise, you won't be able to map the bookmarks later.
Location:
When the application generates a correspondence, it retrieves the template file from a pre-defined location. If you don't save your correspondence template in this exact location, the application won't be able to generate it. The template location depends on two factors:
- Base Directory: This is a system management property that tells the application the first part of any address for all your system files.
- System Path: This is a relative path for any given category of file.
For example: If your Base Directory is C:\Solution\Code\Files\, and your System Path for correspondence templates is Correspondence\Templates\, then all your templates must be placed in the following location: C:\Solution\Code\Files\Correspondence\Templates. Any template in any other location will not generate.
It's not included in the system paths, but any master templates you want to use will be located in a folder named MasterTemplates. This folder will be in the same relative path as your individual correspondence templates.
Bookmarks:
S3 uses Word bookmarks to indicate to the application that it must insert some data. As long as you correctly enter a bookmark, you can create a template entirely in Word. Once it's in the correct location, S3 will be able to open it for mapping later.
The bookmarks that S3 supports are:
- Field: A field bookmark maps to a database column value. A field bookmark has no annotation: it's just a normal bookmark. A field bookmark can map to text, an image as byte array, the path of an image, or HTML text.
- Conditional Field: This checks the field for a defined value and if it finds that value, it includes the text that follows the bookmark. To make a conditional field bookmark, just create a field bookmark and write in the If condition. Best practice is to use x if, which ignores the following body if the If statement is false.
- Conditional Field with Else: This is a conditional field with an Else clause. If the conditional field evaluates to false, the application goes to the Else statement and includes that text instead. Best practice is to use x else, which ignores the following body if the Else statement is false.
- Query: A query bookmark will be populated by whatever the user enters in the associated parameter prior to generating the correspondence. The annotation for a query bookmark is qu.
- Conditional Query: This checks whether what the user enters into the query's parameter meets a condition. If the condition is met, the following text is included. To make a conditional query bookmark, just create a query bookmark and write in the If condition. Best practice is to use x if, which ignores the following line if the If statement is false.
- Conditional Query with Else: This a Conditional Query with an Else clause. If the conditional query evaluates to false, the application goes to the Else statement and includes that text instead. Best practice is to use x else, which ignores the following body if the Else statement is false.
- Standard Bookmark: A standard bookmark is defined in S3 project settings. The annotation for a standard bookmark is std.
- Table: A table bookmark inserts a table of database column values. A column in a table can have text, an image as byte array, the path of an image, or HTML text. The annotation for a table bookmark is tb.
- Visible Rule: This checks the rule for a defined value and if it finds that value, it includes the text that follows the bookmark. If the rule evaluates to false, the application goes to the Else statement and includes that text instead. Best practice is to use x else, which ignores the following body if the Else statement is false. The annotation for a visible rule bookmark is r.
- Repeater Control: A repeater control bookmark inserts a table of database column values. It displays the records just like a grid, but individually in a list view. A column in a table can have text, an image as byte array, the path of an image, or HTML text.
- Template: A template bookmark inserts another template. It's common for organizations to have a master template that is basically a header with address bookmarks configured for their window envelopes. They can take this master template and insert a template for a totally different letter, so they don't have to define the same bookmarks over and over again. The annotation for a template bookmark is tmp.
- Exclusive: This ignores the particular bookmark for which the column value does not exist. The annotation is preceded by x. Example: {x Bookmark Name}.
This post is part of the Correspondence topic. Click here to open the Correspondence Overview.