Document Template Syntax Guide
This page contains examples of syntax that can be used for configuration of various data merge scenarios within Document Templates.
Document template merging is performed by the third-party product Aspose Words.
Full official template syntax documentation can be found online here.
The functions and formatting strings listed in this page are case sensitive
Basic Objects Insertion
Document template data source objects may be inserted into a document template using either of the following methods:
Double-clicking the object in the data source list to the left of the document
Entering the field tag into the document using the proper format
The following example substitutes <<[siteOwnerName]>> with the site owner name at the time of document generation, a list of available objects in the data source can be found in Standard Document Template Fields:
Site Owner: <<[siteOwnerName]>>
Note: when selecting a field by double-clicking in the data source list, the selected field will be inserted into the document at the current location of the cursor.
Signature Images
Two options are available for insertion of signature images into document templates:
at the time of document generation, or
at the time of document finalization.
Signatures are inserted into document templates using the signatureImage
merge field in the currentUser
data source.
Prerequisite: Adding Signature Images to User Accounts
The current user's signature image must have been added to their user profile for this function to work. Support for signature images, and who can manage them, is configurable and available options will vary based on implementation. Signatures can either be added using the Upload Image button on the internal user’s User Details page in Admin > Users, or on the User Profile screen for self-service management by an internal user.
Inserting a Signature Image at Time of Document Generation
To insert a signature image from the user profile at the time of document generation:
Insert a Textbox into the document at the location where the signature is to appear.
Within the textbox, insert the following code block:
<<image [IMAGETAG] -fitSizeLim>>
Insert for current user
The signature image for the current user (person generating the document) can be inserted into the document at the time of document generation.
<<image [currentUser.signatureImage] -fitSizeLim>>
Insert for Submission Staff
The same steps can be used to add the signature image for submission staff (available in the submission data source):
The signature image from the user profile of the processor of an application will be inserted into the document at the time of document generation.
Inserting a Signature Image at Time of Document Finalization
Alternatively, the user profile signature image can be added at the time of document finalization. This method adds the image to the PDF version of the document [but not to the Word version] and can be used as a form of ‘electronic signature’ by the person who finalizes the document.
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.
Within the textbox insert the following code block:
QR Code Generation
As of release 2023.1, a QR code can be generated within document template, a custom text is processed and is displayed in a form of QR image.
To generate a QR image at the time of document generation:
Insert a Textbox into the document at the location where the QR code is to appear.
Within the textbox, insert the following code block:
To create a complex text string such as a URL with data from the document, use variables to build out the string which will be passed into the StringToQRImageBytes() function. To create a variable use the following and insert it at the beginning of the document template:
Then follow the steps above to create a text box and within the text box the text will look as follow:
Loops
Loops can be used to find information pertaining to a contact with a particular affiliation type/role code, it can also be used to return the list of violation associated with an evaluation. It is possible to limit the returned values based on certain criteria.
A foreach loop is inserted automatically into the template if an object name (Bold fields name) is double-clicked. Foreach loops are in the following format:
Lists returned by loops may be included in the document body or in tables as desired. Lists may also be filtered to select specific records or to sort / order by specific fields.
For more details on how loops are used check Using Loops in Document Templates.
Logical Operators
The following logical operators can be used to combine or modify Boolean (true/false) expressions, such as those used in <<if>> statements:
Operator | Meaning | Description | Syntax Example |
&& | And | Returns True (or returns value) if both statements are true | <<if[responded == "Yes" && rsvp == "1"]>> |
|| | Or | Returns True (or returns value) if either statement is true | <<if[responded == "Yes" || rsvp =="1"]>> |
! | Not | Returns True (or returns value) if the statement is false | <<if[!string.IsNullOrEmpty(comment)]>> |
Checking for Null Values
In some situations, code in a document template might reference objects that don't exist, causing the template to fail with an error. This can often be prevented by surrounding the code by an if statement that performs a check to make sure that the object in question exists.
For example, the following statement:
can be read as "if violations is not equal to null..." (or in other words, "if a violation exists..."). This prevents the code within the if statement from running if there are no violations.
You can see this statement in action in the example code that appears in the "Breaking Out of a Loop" section. In that code, this statement is used to check for the existence of violations, and the following statement is used to check for the existence of the regulationReference object:
Note that, as with all if statements, both of these statements need to have a corresponding close tag (<</if>>
).
Another way to check for Null or empty fields is a function IsNullOrEmpty
which checks for null
or an empty string (""). or IsNullOrWhiteSpace which checks for null
, empty, or consists only of white-space characters. To use the function use the following syntax:
The above code will check the existence of the regulationReference object and return True if the regulationReference object is not null
or does not contain empty string ("")
Warning message if data is missing
This example displays a warning message if the organization for the agency contact (Submission Staff Organization) is missing:
This example displays a warning message if the organization for the agency contact (Submission Staff Organization) is missing:
Preventing blank lines caused by missing data
When checking for null values, it's important to account for the display of text when data actually is missing. For example, when displaying the site address, if the line that checks for the presence of siteAddress2 adds in a new line, the address block will contain a blank line between siteAddress1 and the fields below it (such as siteCity, siteState, siteZip), as shown here:
To prevent this, make sure that a new line added by a null-check statement appears before the closing <</if>> tag. This is most easily accomplished by showing paragraph marks in Word (Ctrl+Shift+8) and manually moving the paragraph mark so that it appears before the closing <</if>> tag, as shown in the following image. Note that, in each null-check statement, the paragraph mark indicated by the red arrow appears before the closing <</if>> tag (underlined in blue):
Format Objects
Aceoffix allows users to format objects to better control the document outcome and maintain consistency. Date, Text, and Numbers can be formatted. Formatting fields can be done by using a colon ":" after the object closing bracket "]" as follows:
Formatting Dates
Dates can be formatted in a variety of ways. The example below shows a few different date-formatting options.
Note that month formatting should always be capitalized (e.g., "M", "MM", or "MMMM") and the year should always be small caps (eg., "yy", or "yyyy").
Below are some predefined date and time format which can be used within document template.
Format | Date Output |
---|---|
<<[DateTime.Now]:"d">> | 12/31/2019 |
<<[DateTime.Now]:"D">> | Tuesday, December 31, 2019 |
<<[DateTime.Now]:"F">> | Tuesday, December 31, 2019 1:45 PM |
<<[DateTime.Now]:"M">> or <<[DateTime.Now]:"M">> | December 31 |
<<[DateTime.Now]:"Y">> or <<[DateTime.Now]:"y">> | December 2019 |
In addition to the predefined date and time a custom formatting can be created using a combination of the Date and Time strings listed below:
Date and Time Format String | Date Output |
---|---|
dd | Day: 31 |
ddd or dddd | Day: Tue or → Tuesday |
MM | Month: 12 |
MMM or MMMM | Month: Dec or → December |
yy or yyyy | Year: 19 or → 2019 |
HH | Military Hour: 14 |
hh | Hour: 1 |
mm | Minutes: 45 |
ss | Seconds: 55 |
tt | AM or PM |
An example using a combination of the above formats would be <<[DateTime.Now]:"MMMM dd, yyyy">>, which would result in the format December 31, 2020.
If a date isn't formatting using the above DateTime formatting then it might be stored as a different character type. In order to convert it into a correct DateTime format try the below Convert.ToDateTime() function:
Formatting Text
Texts can be formatted to be displayed as, upper, lower, first letter caps, or first letter of each word caps.
Available formatting strings are shown in the table below:
Text Format String | Text Output |
---|---|
lower | all lower case text |
upper | ALL UPPER CASE TEXT |
caps | Only First Letter Of Each Word |
firstCap | Only first letter of sentence |
In addition to using formatting strings, a function can be used to format texts, .ToUpper(), .ToLower().
The .ToUpper()
method can be used to display the value of a field in all capital letters. For example, "John Doe" would be displayed as "JOHN DOE".
Formatting Numbers & Currency
The table below shows a list of ways to format numbers:
Number Format String | Example | Number Input → Output |
---|---|---|
c or C |
| 300129 → $300,129.00 |
e or E |
| 1052.0329112756 → 1.052033E+003 |
n or N |
| 1234.567 → 1,234.57 |
| 1234 → 1,234.0 | |
| 1234.56 → 1,234.560 | |
| 1234 → 1,234 | |
p or P |
| 1 → 100.00% |
| -0.39678 → -39.7% |
Numbers can also be formatted to be displayed in a different form, such as First, Second Third, etc., below is a list of possible numbering formats:
Number Format String | Example | Output |
---|---|---|
alphabetic |
| Formats an integer number as an upper-case letter (A, B, C, ...) |
roman |
| Formats an integer number as an upper-case Roman numeral (I, II, III, ...) |
ordinal |
| Appends an ordinal suffix to an integer number (1st, 2nd, 3rd, ...) |
ordinalText |
| Converts an integer number to its ordinal text representation (First, Second, Third, ...) |
cardinal |
| Converts an integer number to its text representation (One, Two, Three, ...) |
hex |
| Formats an integer number as hexadecimal (8, 9, A, B, C, D, E, F, 10, 11, ...) |
arabicDash |
| Encloses an integer number with dashes (- 1 -, - 2 -, - 3 -, ...) |
Below is an example of how to add a date in the format of "2nd day of January, 2020" using numbers formatting:
If using a date field, the following code could be used
When formating numbers which are stored in a string format such as data coming from a program component or a submission, the data type should be converted to numbers before applying formatting strings.
The following code displays a number which stored as a string in currency format.
Formatting Text as a Hyperlink
The syntax to format text as a hyperlink is as follows:
The following example formats a merge field as a hyperlink:
The following example implements the display text portion of the link:
Building a link using merge fields and text
If the merge fields available don’t work for a specific link, there is a possibility to build links using variables.
Address formatting with check for missing data
In the following example, if the Site Owner Name field is blank, the Site Owner Organization Name is displayed instead.
Also, if there is an Address Line 2, it is displayed; otherwise, Address Line 2 is omitted. (This also prevents a blank line from being displayed where the Address Line 2 field would be.)
Accepted System Variables and Functions
Assigning Variables
On occasion you may wish to save a variable in the document. Examples of this may be to print the variable only when the value changes, or to filter records based on the variable.
Examples of variable assignment:
Dates and Times Functions and Calculations
This example gives the current date plus the number of days specified, and returns the date in the format given.
More examples of ways to use DateTime
can be found here: here.
Performing Date Calculations
To use DateTime
methods or functions use.GetValueOrDefault()
followed by the method name. For example, to return the Year portion of a DateTime value, perform the following:
The example shown below determines whether there is a date or null value in the field (in this case, the permit expiration date field). If the field is null, then the ‘missing’ message displays. If the field is not null, then a date of 180 days prior to the value in the field is displayed.
To calculate the difference between two dates, .Subtract()
can be used as follows:
The above code will return the difference between PermiteExpireDate and PermitIssueDate in days.
In addition to AddDays()
method the list below shows more methods that can be used to calculate a date:
Method | Discription |
---|---|
| Returns a new DateTime that adds the specified number of days to the value of this instance. |
| Returns a new DateTime that adds the specified number of hours to the value of this instance. |
| Returns a new DateTime that adds the specified number of milliseconds to the value of this instance. |
| Returns a new DateTime that adds the specified number of minutes to the value of this instance. |
| Returns a new DateTime that adds the specified number of months to the value of this instance. |
| Returns a new DateTime that adds the specified number of seconds to the value of this instance. |
| Returns a new DateTime that adds the specified number of years to the value of this instance. |
String and Texts
Objects which their data type is string can be manipulated using functions or methods a list of methods can be found here, note that not all methods can be used within the document templates.
Return the length of a string
The .Length
method returns the length of a string:
Warning! A null reference exception will be generated if you attempt to call a method on a null field. See the "Checking for NULL Values" topic above to ensure your template will work under all situations.
Trim characters from end of a string
To remove a specified number of characters from the end of a string, use the .Remove()
method as shown below:
In this case, x is the zero-based index of the first character you want to remove. For example, if your string is “ABCDEF” and you want to return “ABC”, x would be 3. (“A” is index 0, “B” is index 1, etc.). This example only works if the length of the string is static. If it is variable, syntax like the following can be used.
To removes all the trailing occurrences of a set of characters specified in an array from the current string, use the .TrimEnd()
method as shown below:
To remove all leading and trailing white space from a string use .Trim()
method
Trim characters from beginning of a string
To remove all the leading occurrences of a set of characters specified in an array from the current string, use the .TrimStart()
method as shown below and replace "char to remove" with the character to remove:
When the data in the beginning of a string is variable and you can't predetermine the characters then you can remove variable data from the beginning/end of a string like this, as long as it will always be the same amount of characters to remove:
Or you can use functions like IndexOf() and Length shown in this example that acts as a Left() function (leaving behind only the characters left of the "char to find"):
Or you can use functions like IndexOf() and Length shown in this example that acts as a Right() function (leaving behind only the characters right of the "char to find"):
Otherwise you might look into doing an Substring and finding the IndexOf() say a dash or something similar.
Comparing two strings
To compare two strings and return a value if they are a match, use the following:
To account for case difference between two fields such as PERMITTEE and permittee we can use .ToUpper
method as follows:
Comparing the start of a string to a pattern
To compare the start of a string to a pattern, use the StartsWith() method. This example evaluates the first character of coWqc.coWqcCoe. If it is "M", display "Mobile", else "Nashville":
More methods for strings:
Method | Discription |
---|---|
| Returns a value indicating whether a specified substring occurs within this string. |
| Return 0 for exact match |
| Determines whether the end of this string instance matches the specified string. |
| Determines whether this instance and another specified String object have the same value. (case sensitive) |
| Reports the zero-based index of the first occurrence of the specified string in this instance. |
| Returns a new string that right-aligns the characters in this instance by padding them with spaces on the left, for a specified total length. |
| Returns a new string that left-aligns the characters in this string by padding them with spaces on the right, for a specified total length. |
| Returns a new string in which all occurrences of a specified string in the current instance are replaced with another specified string. |
| Determines whether the beginning of this string instance matches the specified string. |
| Removes all leading and trailing white-space characters from the current string. |
| Removes all the leading occurrences of a set of characters specified in an array from the current string. |
| Removes all the trailing occurrences of a set of characters specified in an array from the current string. |
Additional if/else Statement Examples
The following example displays Phone and Email contact information if those fields are populated, or placeholder text if one or both of the fields are empty:
In the following example, a different contact type is displayed if the first isn't available. The code checks the count of affiliations with a type code of "IWBILL". If the count = 0 then it instead displays the first affiliation [using .Take(1)] for the type code of "PERMCT":
In the following example, an "Unspecified Due Date" message is displayed if the permit due date field is blank:
This example uses an if/else statement to display data based on a specified region:
Performing if/else statement on a value that may be null
When needing to evaluate a value in an if/else statement that may be null, the following will not work, as both if/else statements appear to be evaluated even though the nested if/else should be ignored:
This will return an error:
There was an error generating the document from the data source:Tag 'if' is not well-formed. A conditional expression should return a Boolean value.
One solution is to create a local variable that will always have a value, even if its source is null:
When setting this variable, only allow it to be set to the value from the data source if that value is not null or empty:
Now, since v_coe will never be null, the null check is no longer necessary:
Note that variables are only recognized within a doc template section. If for example you wanted to include this block in the header of the document, you would need to define a new variable for this (e.g., "coe2").
Permit Conditions
Permit Conditions allow for conditional text to be dynamically inserted into permit template documents. For more information, please refer to Permit Conditions.
Additional Methods and Functions
Document template accepts other C# methods which can be used for data manipulation, a list of methods that could possibly be used within a document template can be found here.
Data type restrict the use of some methods and might not work correctly, to check the data type of a field use GetTypeCode() function then use the method available to that data type. Check the available methods for some data type by visiting the links below:
On this page