Placeholders are used to pass data from submitted forms to output files, these include:

• external files (any file with a placeholder that is not embedded into the form)
• places in a CSV, PDF or other document/file templates (embedded files)
• form fragments
• response metadata

Templates generate output documents from your form and utilize placeholders extensively; they are therefore a key tool for form automation.

🚧

Placeholders are not Variables

Placeholders do not act the same as variables and cannot transfer in default data or pre-fill information into a form. Placeholders only transfer data out of the answer question input, to the various other locations such as template placeholders or form fragments.

Usage

A placeholder named 'here' can be added to a word document using two curly brackets, known as a 'Tag', surrounding the name e.g. {{here}}. The placeholder name is limited to 100 characters in length. The Tag for this placeholder will be available when the word document Template has been uploaded. Simply drag the Tag to the Answer question with the desired data, it will populate the documents placeholder.

Placeholders can be thought of as cell reference coordinates (e.g. A1), a file path, or an arrow, in that a placeholder is a unique mapping from an input placeholder to an output placeholder, both with the same name in a {{}} 'Tag', e.g. {{name}}

The formatting for placeholder tags depends on the type of placeholder and how you are using it.

An Answer question with a placeholder is an input placeholder, which sends data to a template file where a correspondingly named output placeholder is located. While there is no strict difference between input and output placeholder, this distinction is simply to describe where the placeholder retrieves its data from and where it sends it to.

You can't usually use a placeholder as an input more than once but you can use it to output its data multiple times. This placeholder behaviour can change depending on the question type and use case.

Inactive Placeholders

Placeholders can be made inactive to not render in the final document. Thus multiple placeholders can be stacked together and only the answer for the active one(s) will be displayed.

Best Practices

In some cases, there may be thousands of placeholders. As the number of placeholders in your document increases, it becomes more critical to follow a naming convention to make it easier to find placeholders in 'Design', and work out the purpose of the placeholders without needing to jump back to the document. If you plan and follow a convention right from the beginning, it becomes easier to manage your documents even if they grow larger than they start out. There is no harm in having long and descriptive placeholder names.

While MS Word bookmarks are still supported as to support backwards comparability, as placeholders we strongly suggest not using them. This is because a single Tag placeholder can be used multiple times throughout a document whereas bookmarks can be used only once, among other technical complications.

Placeholder Types and Behaviors

Although {{}} Tags are universal, there are a few nuances in how to define a placeholder depending on the template document/file and use case.

🚧

If placeholder data appears formatted incorrectly in your documents, it is suggested that your placeholders are used within rich text questions instead of a label or input question.

External Placeholders - </> and {}

These placeholders aren't explicitly linked to any one document, so can allow users filling in the form to select a document/file from a content list, and if that document has placeholders with the same names the document will be filled with the placeholder data.

Document/file Template Placeholders

The formatting method of the placeholders and available behaviour of placeholders changes depending on the file type of the template.

Document Template Placeholders on Project Fragment Outputs

Template placeholders placed on project fragment outputs will transfer the fragment output through the placeholder to the generated document. However, template placeholders placed on outputs from Repeating Pages and Sections, that are within a project fragment, will only be able to retrieve the first record from the repeater contained within the fragment. The template placeholder won't be able to retrieve any subsequent records from the repeater contained within the fragment.

Response Metadata Placeholders

These are metadata that you can attach to a submission (usually a workflow task) and the system will return the custom values when you query tasks.

If you wanted to track a user's favourite colour (for instance), you map a Response Metadata placeholder to the question inside the form, and when the user submits the task we record the value into the IQ data base, and pull it back for queries about tasks (extra column/s along with the regular workflow information).

the response metadata is for feeding additional data (that were answers to questions by a user) into the admin data base along with the rest of the default user workflow data viewable in Manage

🚧

Response Metadata doesn't perform well with lots of Response Metadata fields or lots of tasks

Gap and Repeat Range Placeholders

Gap and repeat placeholders are a unique tool for dynamically overriding other placeholders or inserting Repeating Pages and Sections into files containing start and end 'Range Tags', formatted {{#name}} {{/name}}, instead of the usual {{name}} Tag.

Range tags will treat anything between the start and end Tags as part of the repeat or gap placeholder.

The best practice for Gap and Repeat placeholders is to add _RPT or _GAP to the range tags to differentiate between gap {{#name_GAP}} and repeat {{#name_RPT}} range tags.

Any range placeholders without a valid start {{#}} and end {{/}} pair will be marked as an invalid placeholder in Design.

Currently there is no known way to make external placeholders act like range placeholders.

Repeat Placeholder Behaviour

Repeat placeholders are used exclusively to surround other placeholder tags so content from Repeating Pages and Sections content can be read.

Any normal placeholders within the repeat placeholder will act slightly differently to how they normally would. Instead of not being able to take multiple answer inputs and duplicating the same data repeatedly, a placeholder within a repeating placeholder acts as if its a separate new placeholder for each repeat. This allows a repeating section to transfer different answer data using the same input placeholders to a template without having to make multiple new placeholders within the template for each possible repeat.

Repeat placeholders will insert anything between the start and end tags, this includes spaces, returns/newlines, table rows and columns, etc. (e.g. for a word doc table of 1 row and 3 columns, if a start tag is placed in the first column and an end tag in the third, every repeat will generate a new row with three columns.)

Repeat placeholders are Range Placeholders, formatted with # and / to flag the start and end, e.g. start {{#name}} and an end {{/name}} tags. The repeating page or section will be inserted in the template between the start and end tags.

Gap Placeholder Behaviour

Gap placeholders are placeholders that will override any other placeholders an answer has, if the linked question has been given no value. This is useful for clearing irrelevant text before generating a template if an answer is not provided. If no answer is provided to a question with a Gap Placeholder selected withing the properties panel, the default answer result will get input to the Gap Placeholder instead of any of the content between the Range Tags, even if some of that content is valid.

Gap placeholders are Range Placeholders, formatted with # and / to flag the start and end, e.g. start {{#name}} and an end {{/name}} tags. The gap placeholder will be inserted in the template replacing all content between the start and end tags if the answer it is linked to has been provided no input.

Gap placeholders with the best practice formatting name_GAP will allow the arrow button to automatically identify and assign a gap placeholder.

📘

Gap placeholders are not designed to be used to handle empty rows in repeated output, use a filter on the output data source instead.

At the first detection of an empty answer the gap placeholder all the contents are removed from the template being processed, so subsequent non-empty rows will have no placeholders to fill.

Choice Question and Logic Question Placeholders Behaviour

Placeholders in Choice Questions and Logic Questions have access to unique behaviors.

Content Preserve/Remove (Choice & Logic)

The placeholder is retained or removed from the document based on answer selection. This is the default behavior.

Apply Style (Choice & Logic)

Applies a Word style on the text within the placeholder. The style options are the custom styles defined in the Word template for the project.

Insert Checkbox (Choice & Logic)

Inserts a checked or unchecked box character depending on answer selection. If the answer is not selected, a blank check box will be inserted. If the answer is selected, a “ticked” checkbox will be inserted.

Insert Answer Value (Choice Only)

This option inserts the text contained within the “value” field. In the example below, the value field is Short term”. When the project is generated, if this option is selected, then the placeholder will insert “Short term” into the generated document.

Insert Display Text (Choice Only)

This option inserts the text contained within the “Display text” field. In the example below, the Display Text is set to “Medium-term duration”. When the project is generated, if this option is selected, then the placeholder will insert “Medium-term duration” into the generated document.

Document Fragment Placeholders

When you add a document fragment to a question set, it becomes available in the Placeholders tab for you to use any placeholders the fragment may contain in your question set. The fragment name is added to the Document Fragments element, with a list of its placeholders.

You may locate a document fragment in the question set from the Placeholders tab by right-clicking on the fragment and choosing Find in Question Set from the pop-up menu. This will return a list of all instances of the selected fragment in the Find Results window.