Escape Special Characters and Line Breaks for Template-driven Text Documents

DRELClosed Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms., Handlebars, and FreeMarker documents reference data in submitted forms, including question answers and metadata. Special characters or line breaks in the data could cause the system to generate a document that’s not valid. To ensure the system generates valid documents in the specified format, you must escape the data. This is especially important when you use these documents to integrate with a third-party system.

This topic describes how to escape data for DREL, Handlebars, and FreeMarker Template-driven Text Documents in JSON, XML, HTML, and CSV formats.

Contents

DREL

Escape data for a single DREL expression

To escape the data referenced by a DREL expression, include a property with the following syntax:

[#escapeDocumentFormat]

where DocumentFormat is either Json, Xml, Html, Csv, or Url.

When the DREL expressions reference data with special characters or line breaks, the system escapes them in the specified format.

The following table includes examples of how to escape different types of DREL expressions in different document formats.

Format DREL expression Example
JSON %a[CustomerFeedback][#escapeJson]
Input
Excellent service.
Thanks for the speed and attention to detail.
Result
Excellent service.\nThanks for the speed and attention to detail.
XML %a[CustomerName][#escapeXml]
Input
Gatwell & Bowman
Result
Gatwell & Bowman
HTML %q[InspectLabel][#escapeHtml]
Input
Locate the section "Equipment Information" on the label and take a picture.
Result
Locate the section "Equipment Information" on the label and take a picture.
CSV %g[address][#escapeCsv]
Input
95 Walnut Street, Ottawa, ON K1A 2B3, Canada
Result
"95 Walnut Street, Ottawa, ON K1A 2B3, Canada"
URL %u[name][#escapeUrl]
Input
Harold Petrov
Result
Harold%20Petrov

Tip:You can URL encode data from DREL expressions that you want to use as part of a URL. For example, the endpoint for a Salesforce Apex RESTClosed The Salesforce Apex REST is a type of Salesforce Data Destination that enables TrueContext to interact with Salesforce by means of an Apex REST API endpoint. If using an Apex REST API endpoint, developers can write APEX code to send custom messages that pull specific data from submitted forms. Data DestinationClosed A Data Destination specifies where to send data from a submitted form. You can use Data Destinations to automate data sharing and storage, routing data to a specific service (such as email or cloud storage) in several different formats., or the URL Suffix in an HTTP Data Destination.

Escape data globally in a DREL document

To escape the data referenced by all DREL expressions in a document, include an expression with the following syntax:

#c[escapeDocumentFormat]

where DocumentFormat is either Json, Xml, Html, or Csv.

The system automatically escapes all DREL expressions included after this expression.

To override the global escape, include the following property as part of a DREL expression:

[#escapeNone]

In the following example:

  • The expression #c[escapeJson] sets the output format to JSON. The system escapes the data referenced by all following DREL expressions to generate valid JSON output.

  • Because the document is escaped globally, the system automatically escapes the data referenced by the DREL expression %a[Message].

  • The system overrides the global escaping for the expression %a[recordID][#escapeNone].

#c[escapeJson]
{
    "body": {
        "messageSegments": [{
            "type": "Text",
            "text": "%a[Message] - Posted from TrueContext"
        }]
    },
    "feedElementType": "FeedItem",
    "subjectId": "%a[recordID][#escapeNone]"
}

Handlebars

Info:We’re now TrueContext.

To escape the data referenced by a Handlebars expression, include one of the following expressions:

  • {{pf:outputFormat “DOCUMENTFORMAT”}}

  • {{#pf:outputFormat “DOCUMENTFORMAT”}}...{{/pf:outputFormat}}

The following table includes examples of how to escape different types of Handlebars expressions in different document formats.

Format Handlebars expression Example
JSON

{{pf:outputFormat “JSON”}}

{{answers.CustomerFeedback.[0]}}

Input
Excellent service.
Thanks for the speed and attention to detail.
Result
Excellent service.\nThanks for the speed and attention to detail.
CSV

{{#pf:outputFormat “DOCUMENTFORMAT”}}

{{dataRecord.geoStamp.address}}

{{/pf:outputFormat}}

Input
95 Walnut Street, Ottawa, ON K1A 2B3, Canada
Result
"95 Walnut Street, Ottawa, ON K1A 2B3, Canada"

Note:Handlebars automatically escapes values for HTML and XML. If you don’t want to escape output for HTML or XML, use the expression {{pf:outputFormat "NONE"}}.

FreeMarker

To escape data for a FreeMarker document, include the output format in the ftl header. The following example shows how to escape the output for a JSON document:

<#ftl output_format=”JSON”>

TrueContext supports escaping data with FreeMarker in the following formats:

  • JSON

  • XML

  • HTML

  • CSV