Overview

This page provides examples of syntax that can be used to merge data into document templates.

Basic Objects

Data source objects can be inserted into a document template by either:

• Double-clicking the object in the data source list to the left of the template

• Entering the field tag into the template using the proper format

The following example substitutes “<<[siteOwnerName]>>” with the site owner name when the document is generated:

For more information on inserting data source objects into document templates, see the Viewing and Editing Document Templates page.

Signature Images

Signature images can be inserted into document templates either when the document is generated or finalized, using the signatureImage merge field in the currentUser data source.

Inserting a Signature Image During Document Generation

To insert a signature image at the time of document generation:

• Insert a textbox into the document at the location where the signature is to appear.

• Add the following code block to the textbox:

Inserting the Current User’s Signature

To insert the signature image of the current user (the person generating the document), use:

Inserting the Submission Processor’s Signature

To insert the signature image of the submission processor (available in the submission data source), use:

Inserting a Signature Image During Document Finalization

To insert a signature image at the time of document finalization:

• Insert a textbox into the document at the location where the signature is to appear.

• Add the following code block to the textbox:

Site Images

A site image can be displayed in a document template when the template is generated.

To insert a site image at the time of document generation:

• Insert a textbox into the document at the location where the image is to appear.

• Add the following code block to the textbox:

  <<image [siteImage] -fitSizeLim>>

QR Codes

A QR code can be generated in a document template by processing a custom text string and displaying it as a QR image. QR codes are inserted into documents when they are generated.

To insert a QR code into a document template:

• Insert a textbox into the document at the location where the QR code is to appear.

• Add the following code block to the textbox:

To create a complex text string, such as a URL, using data from the document, build the string using variables and pass it into the .StringToQRImageBytes() function. To define a variable, customize and insert the following at the beginning of the document template:

Then, follow the steps above to insert a QR code. The code block in the text box should be in the following format:

For more information on variables, see the Assigning Variables section below.

Loops

Loops can be used to find information related to a contact with a particular affiliation type or role code, or to return a list of violations associated with an evaluation. Returned values can be limited based on certain criteria and be added to the document body or tables.

Loops appear in bold in the data source list to the left of the document template during configuration and follow this format:

For more information on using loops, see the Using Loops in Document Templates page.

Logical Operators

The following logical operators can be used to combine or modify Boolean (true/false) expressions, such as those used in <<if>> statements.

Checking for Null Values

Occasionally, code in a document template may reference objects that don’t exist, resulting in an error. This can often be avoided by wrapping the code in an <<if>> statement that checks whether the object exists.

This type of <<if>> statement appears in the example code in the Breaking Out of a Loop section of the Using Loops in Document Templates page. In that example, the following statement is used to check whether any violations exist:

This can be read as “if violations is not equal to null” (in other words, “if a violation exists”). This ensures that the code within the <<if>> statement is only executed when violations are present.

A similar check is used for regulationReference:

As with all <<if>> statements, a corresponding close tag (<</if>>) must be included.

Another way to check for null or empty fields is to use the .IsNullOrEmpty function, which checks whether the string is null or empty (""), or .IsNullOrWhiteSpace, which checks whether the string is null, empty (""), or consists only of white-space characters.

The following example uses .IsNullOrEmpty to evaluate regulationReference:

This code ensures regulationReference exists and is not null or empty (""). If the condition returns true, the enclosed text is included in the generated document.

Displaying a Warning Message If Data Is Missing

A document template can also be configured to display a warning message when an expected object or data is missing. For example, the following code displays a warning if the organization for the agency contact (“Submission Staff Organization”) does not exist:

Preventing Blank Lines Caused by Missing Data

When checking for null values, it’s important to consider how missing data affects the layout of the document. For example, when displaying a site address, if the code that checks for siteAddress2 includes a line break, the address block may contain an unintended blank line between siteAddress1 and the fields below it (such as siteCity, siteState, and siteZip) when no data exists in siteAddress2.

Open

An example site address with a blank line

To prevent this, ensure that any new line added by a null-check statement appears before the closing <</if>> tag. This is most easily done by enabling paragraph marks in Microsoft Word (Ctrl+Shift+8) and moving the paragraph mark so that it appears before the closing <</if>> tag.

Open

Example null-check statements with paragraph marks (red arrows) before the closing tags (blue underlines)

Displaying Alternative Information If Data Is Missing

A document template can also be configured to display alternative information if data is missing.

For example, the following code checks if a site’s Owner Name field is blank; if so, it displays the Owner Organization Name instead. It also prevents a blank line from appearing if no data exists in siteOwnerAddr2, as explained in the previous section.

Formatting Objects 

Aceoffix, the web-based control used to edit document templates, allows users to format dates, text, and numbers to better control the final document and maintain consistency. To format fields, use a colon after the object’s closing bracket, as in the following example:

Syntax for different formatting strings is provided in the following sections.

Formatting Dates and Times

Dates and times can be formatted in various ways. The following example shows a few different options:

The following predefined formats have been configured to support common formats used in document templates.

Custom formats can also be created by combining the following strings.

For example, the following syntax would produce a date with a full month name, day of the month, and four-digit year (such as “December 31, 2024”):

Formatting Text

Text can be formatted to display in uppercase, lowercase, title case (first letter of each word capitalized), or sentence case (only first letter capitalized).

Text formatting uses the following basic syntax:

The table below describes the available string options for configuring different text formats.

For example, the following syntax displays the siteName in title case:

Another method to format text is to use the .ToUpper() or .ToLower() functions. The .ToUpper() function displays the value of a field in uppercase letters. For example, the following syntax would display John Doe’s name as “JOHN DOE”:

Formatting Numbers

Numbers can be formatted to display as currency (U.S. dollar), exponential notation, or percentages. Formatting options include adding thousands separators and rounding to a specified number of decimal places. When decimal places are specified, trailing zeros may be added.

Number formatting uses the following basic syntax:

The table below describes the available string options for configuring different number formats.

Numbers can also be formatted as ordered labels in various styles, including ordinal words (such as “first,” “second,” and “third”), alphabetic sequences (such as “A,” “B,” and “C”), or Roman numerals (such as “I,” “II,” and “III”).

For example, the following syntax displays the current day of the month in ordinal format (such as “2nd day of January, 2024”):

Or, if using a date field, the following could be used:

When formatting numbers stored in a string format—such as data from a program component or a submission—the data type must be converted to numbers before formatting can be applied. For example, the following syntax displays a number stored in a string format as currency:

Formatting Text as a Hyperlink

The following syntax can be used to format text as a hyperlink:

For example, the following code creates a hyperlink using environmentSettings.productName as the display text and environmentSettings.applicationUrl as the link target:

The [display text] portion is optional—omitting it will display the active URL itself, as in the following example:

Building a Link Using Variables

If a specific link cannot be generated using available merge fields, it can often be constructed using variables.

For example, the following code builds a URL by combining a base application URL with additional path parts and an identifier, then creates a hyperlink using that URL with custom display text (“View Document Set”):

For more information about variables, see the Accepted System Variables and Functions section below.

Accepted System Variables and Functions

Variables and functions provide dynamic content and logic within document templates, allowing data to be inserted, manipulated, or conditionally displayed. This section describes the accepted system variables and functions available for use.

Assigning Variables

Occasionally, it may be useful to assign a variable within a document template—for example, to print the variable only when its value changes or to filter records based on the variable. Assigning a variable involves storing a value in a named placeholder for later use within the template.

The following are examples of variable assignment:

(Example output: “Current Year: 2024”)

(Example output: “Current Date: 12/31/2024 1:45:55 PM”)

Date and Time Functions

Some simple dynamic dates and times can be configured using prebuilt Microsoft add-ins, while others require coding.

Using the Microsoft Word Date Control

To include a date that updates automatically each time the document is created, saved, or printed, use the built-in Microsoft Word date control. To add the control:

• Open the Insert tab on the Aceoffix Word ribbon.

• Navigate to the the Text group and click the Quick Parts button.

• Select the Field... option from the dropdown menu. This opens the Field dialog.

• In the Field dialog, select the following values:

  • Categories: Date and Time

  • Field names: Create Date, SaveDate, or PrintDate

  • Date formats: Desired date format

Performing Date Calculations

To use DateTime methods or functions, enter .GetValueOrDefault(), followed by the method name. For example, the following syntax retrieves the year portion of a DateTime value:

To calculate the difference between two dates, use the .Subtract() function. For example, the following syntax returns the difference between permitExpireDate and permitIssueDate in days:

Additional methods that can be used to calculate a date are described below. When using each method, int must be replaced with an integer value that specifies the number of units to add (or subtract, if negative) to the DateTime value.