Handlebars: Advanced Question References
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: