Escape Special Characters and Line Breaks for Template-driven Text Documents
DREL 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]
|
|
|
XML | %a[CustomerName][#escapeXml]
|
|
|
HTML | %q[InspectLabel][#escapeHtml]
|
|
|
CSV | %g[address][#escapeCsv]
|
|
|
URL | %u[name][#escapeUrl]
|
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 REST 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 Destination 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
To support existing integrations, some items will continue to use “prontoforms” or “pf” in the domain or code.
For more detailed information about what’s changing, visit https://support.truecontext.com/hc/en-us/articles/19516168513556
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 |
|
|
|
CSV |
|
|
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