Handlebars - Basic Question References

Available on all tiers:

Digital
Intelligent
Elite
?

About

Handlebars is a templating language that can be used to reference answers from a form submission. These references can be embedded within HTML, or whatever language you are using to define how a document should be structured.

It is used with the following features:

This topic describes how to reference single answers to questions, wherever they are in the form.

Read about Handlebars: Advanced Question References if you are interested in building more dynamic document templates that don't require you to reference every question individually.

Referencing the Answer to a Question

A basic reference can be used in most cases where you are mapping a single answer from a form into a document. In these cases, you do not need to understand the full structure of a form, and you move the questions to different pages or sections in the form without affecting the document.

If you are building a custom PDF, Word, or HTML Document using Handlebars, the first part under Reference Data in the document editor screen will show you which questions you can reference.

Example Form

This is a sample describing the basic data structure of a form. (Highlighting added for the purposes of documentation).

  • All questions in the form are wrapped in the "Answers" node (shown here in orange).

  • The parts highlighted in blue here are the questions, followed by a sample answer.

    The question reference shown here is based on the Unique ID, with any spaces or special characters removed.

Example Handlebars Reference

You can have the answer to "AccountName" printed in your document using the following reference:

{{answers.AccountName.[0]}} 

Result

ABC Construction

How does it work?

The final part of the reference (after the last ".") is what will get printed in the document; everything before it tells the document what path to follow through the data structure in order to find it.

The reference above tells the document to:

  • Look for the "answers" node
  • Look for "AccountName" inside of it
  • Look inside of AccountName, for the first value wrapped in square brackets

Referencing Many Questions Efficiently (using "#with")

If you are referencing many questions, you can save yourself a bit of typing. You can do this by using the Handlebars "with" helper.

Example Reference

Instead of referencing multiple questions like:

{{answers.AccountName}}<br/>
{{answers.Contact}}<br/>
{{answers.City}}<br/>
{{answers.State}}<br/>

You can do this:

{{#with answers}}
{{Contact.[0]}}<br/>
{{City.[0]}}<br/>
{{State.[0]}}<br/>
{{/with}}

Result

Jane Doe
123 Avenue Street
New York

How does it work?

The #with helper tells the document to look inside of "answers" for every reference that comes after it, until it hits the closing /with.

Questions with Multiple Properties

Answers with certain data types have multiple properties. The properties either combine together to provide a full answer to a question, or the properties contain multiple ways to reference the same answer (for example, a date/time question will contain the same date/time shifted into different timezones).

When an answer has multiple properties, you can choose which of these properties you want to be used in your document.

Example Form

This form has two questions. 

  • The first is a Date, which only has one answer. 
  • The second is a Duration, which has two properties (in this case, they display the same answer, but in different units - milliseconds, or hours/minutes/seconds).

Example Handlebars Reference  

{{answers.Hoursworked.[0].display}} 

Result

00:1:00

Image, Sketch Pad, and Signature questions

Image, Sketch Pad, and Signature questions all have multiple properties. Because they can be a little difficult to reference, it's easiest to use our custom Handlebars helper for images.

Questions that allow a single image, sketch or signature

For Signature questions, or for Image and Sketch Pad questions set up to allow only one image, you can get the image to print out with the following reference. Specify the height or width in pixels, and images will auto-scale to maintain proportions, whether they were taken portrait or landscape.

Info:We’re now TrueContext.

  • To support existing integrations, some items will continue to use “prontoforms” or “pf” in the domain or code.

{{pf:img answers.PhotoUniqueID.[0] height=200}}

Questions that allow multiple images or sketches

Image or Sketch Pad questions can be set up to allow multiple images. To print all collected images, use the following reference. 

{{#each answers.PhotoUniqueID}}
 {{pf:img this height=200}}
 {{/each}} 

Other types of attachment-based questions

Tip:If you want to reference or display uploaded images, set up your form with Image, Sketch Pad, or Signature questions.

Rich text-enabled Questions

When a Text Area question has Rich Text formattingClosed Rich Text formatting makes a Text Area question support rich text. Mobile users see a formatting toolbar on device, and the question renders markdown content as styled text. Available on Text Area questions and on Additional Comments that use a Text Area. turned on, the server converts the markdown content to HTML before the template runs. The data record carries the raw markdown alongside HTML companion properties. Templates that need styled text reference the HTML properties; templates that need the raw markdown reference the existing answer value.

Use the triple-stash syntax for HTML properties

By default, Handlebars escapes HTML characters in {{ ... }} interpolations. This makes <strong>bold</strong> render as literal text rather than as styled text. Reference the HTML companion properties with the triple-stash syntax {{{ ... }}} instead. Triple-stash tells Handlebars to render the value as HTML.

Warning:Use {{{ ... }}} only for the HTML companion properties listed below. Keep {{ ... }} for plain text values such as values.[0], display, and question. Using {{{ ... }}} on plain text values lets characters such as <, >, and & from mobile user input pass through unescaped, which can break your document or introduce security issues.

HTML companion properties

Content Reference
Pre-converted HTML for a rich text-enabled answer value

{{{answers.uniqueID.[0].valuesMetadata.[0].html}}}

Returns the converted HTML. Use this when the Text Area question has Rich Text formatting turned on.
Pre-converted HTML for a rich text-enabled comment value

{{{answers.uniqueID.[0].commentHtml}}}

Returns the converted HTML for the question comment. Use this when the Additional Comments has Rich Text formatting turned on.
Pre-converted HTML for the question text

{{{answers.uniqueID.[0].questionHtml}}}

Returns the converted HTML for markdown-authored question text. This property predates Rich Text formatting and is not RTS-specific.
Pre-converted HTML for a webhookClosed A Webhook is an HTTP endpoint that an external system exposes to receive data automatically. You can configure an HTTP Data Destination to send form submission data or Documents to a third-party system's Webhook URL, such as posting a notification to Slack when a user submits a form. answer's display value

{{{answers.uniqueID.[0].values.[0].displayHtml}}}

Returns the converted HTML for a webhook answer's display value.

Reading the raw markdown

Templates that need the raw markdown source instead of the converted HTML continue to reference the answer value the same way as plain text answers. Use the regular double-stash syntax.

Content Reference
Raw markdown answer value

{{answers.uniqueID.[0]}}

Returns the raw markdown for the answer. For example, **bold**.
Raw markdown comment value

{{answers.uniqueID.[0].comment}}

Returns the raw markdown for the question comment.

Info:For the full breakdown of how rich text renders across all outputs, go to Where Rich Text formatting renders in the Rich Text Formatting and AI Text Transformation in Text Areas topic.