Handlebars: Advanced Question References

Available on the Advanced and Enterprise tiers:

• About
• Referencing Questions in Regular Sections
• Referencing Questions in Repeatable Sections

This article is about using Handlebars to reference questions in custom PDF, Word, and HTML documents. We recommend reading about Basic Question References before trying this.

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:

• Building custom documents as PDF, Word, or HTML
• Building Handlebars Documents to create a different document type

This topic covers more advanced question references. Read about Basic Question References first.

What can I use this for?

Using Advanced question references, you can create more dynamic documents. Here are some things that you can accomplish:

• Print out all questions/answers in a regular section
• Print all Repeatable Section Entries in a table
• Conditionally Include Answers
• Apply Conditional Formatting

These things require you to understand more of the data structure of a form submission. 

If you are building a custom PDF, Word, or HTML Document using Handlebars, scroll past the "answers" node until you get to "dataRecord" under Reference Data in the document editor screen. This will show you which questions you can reference.

Reference Questions in Regular Sections

Example Form

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

Remember that a form is structured like the following:

• A form can have one or many pages
• Each page can contain one or many sections
• Each section can contain one or many questions

The form submission data is structured in the same way: 

• (Not pictured) The dataRecord container wraps the entire form structure.
• This is followed by a "pages" container, which wraps all pages in the form.

• The pages container includes a node for each of the pages in the form, with the node name being the page's Unique ID A Unique ID refers to the specific identifier of a question, form page, form section, or Data Destination. Unique IDs are used as reference points when pulling data for conditional logic, Analytics projects, Data Destinations, and Documents. (with spaces and special characters stripped).

  Each page has a "sections" container, which wraps all sections in the page.

• The sections container includes a node for each of the sections on the page, with the node name being the section's Unique ID (with spaces and special characters stripped).

  Each section has an "answers" container, which wraps all questions in the section.

• The answers container includes a node for each of the questions on the page, with the node name being the question's Unique ID (with spaces and special characters stripped).

Example Handlebars Reference

You could have the answer to "CustomerName" printed in your document using the following reference:

{{dataRecord.pages.HoursWorked.sections.WorkOrder.answers.CustomerName.values.[0]}}

Result

Jane

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 "dataRecord" container
• Look for the "pages" container inside of it
• Look for the specific "HoursWorked" page 
• Look for the "sections" container inside of that page
• Look for the specific "WorkOrder" section
• Look for the "answers" container inside of that section
• Look for the specific "CustomerName" question
• Look for the "values" property inside of that question
• Look for the first thing wrapped in square brackets inside of "values"

Referencing Questions in Repeatable Sections

Repeatable sections allow you to add multiple entries for the same set of questions, as many times as a user needs to. Because of this, Repeatable Sections have some extra containers in their data structure.

Example Form

This is a sample describing the basic data structure of a form with a Repeatable Section A Repeatable Section is a subform that contains a set of related questions. The data captured is “repeating”, because the field user can complete the same subform more than once, which creates multiple entries., "type": "Repeat". (Highlighting added for the purposes of documentation).

A form submission with Repeatable sections is structured like the following:

• A form can have one or many pages
• Each page can contain one or many sections
• Every Repeatable Section can have multiple rows (entries)

• Each row contains the structure of the Repeatable section

  • The single page

  • The sections within that page

  • The answers within that page

Example Handlebars Reference

You could have the answer to "TodaysDate" from the first entry in your Repeatable section printed in your document using the following reference:

{{dataRecord.pages.HoursWorked.sections.Timesheet.rows.[0].pages.Timesheet.sections.TimesheetSection.answers.TodaysDate.values.[0]}}

Result

2018-2-22

Typically, you wouldn't use this exact reference -- you would be better off using a basic reference if you're referencing the answer to a single question. But, understanding this structure is useful for the following tasks:

• Display all entries in a Repeatable Section as a table