Variants are an advanced template configuration that enable authors to generate conditional content in documents based on variable values selected during end user input, by aligning those values with their corresponding variant outputs in the template.
These inline conditional variants go beyond basic placeholders by enabling dynamic content changes directly within the template, streamlining document creation and simplifying module maintenance. They replace the traditional approach of variable updating combined with regular placeholders, enhancing clarity and ease of use.
If you need to conditionally display entire paragraphs, consider using conditional blocks, as variants are designed for inline use only (though they can span multiple lines without line breaks).
Why to use inline conditional variants?
Variants are useful when a document contains sections with two or more versions that depend on dynamic variables, such as end user input.
With traditional variable updating and placeholders, the content is typically managed outside the template via value nodes in the module editor, requiring additional steps to update or expand options.
Variants simplify this by allowing authors to define content changes directly within the template, streamlining the process and making it easier to adjust and review the document's dynamic content.
Use Cases for Variants
Variants can be used in scenarios like handling gender-specific content, such as titles or pronouns (as covered in the "How to" section below). Beyond that, here are a few other practical applications:
For employment agreements, you might differentiate between salaried employees, hourly workers, and freelancers:
- Input: Variable EmploymentType with values Full-Time, Part-Time, Freelancer.
-
Variant
{{\variants EmploymentType [a fixed salary paid monthly|an hourly wage based on the number of hours worked|a project fee]}}
-
Example:
Eligible employees will receive {{\variants EmploymentType [a fixed salary paid monthly|an hourly wage based on the number of hours worked|a project fee]}} during the employment term.
Based on the selected employment type, the corresponding phrase (a fixed salary paid monthly, an hourly wage... or a project fee would automatically be inserted into the generated document.
A multinational company may need to adjust legal clauses based on jurisdiction:
- Input: Variable Jurisdiction with values US, UK, EU.
-
Variant:
{{\variants Jurisdiction [US regulations|UK Data Protection Act|GDPR]}}
-
Example:
All data processing must comply with {{\variants Jurisdiction [US regulations|UK Data Protection Act|GDPR]}}.
Based on the selected jurisdiction, the text will reflect different data protection laws. If EU is selected, the clause will reference GDPR; if US is selected, it will say US regulations.
How to Set Up Inline Conditional Variants
-
Define the variable in your module:
Start by defining a variable to capture user input. For example, create an input node forGender
that offers options such asMr. (He/Him)
,Ms. (She/Her
), andMx. (They/Them)
. The corresponding variable will take on the selected value. -
Create the variants in your document:
Use the {{\variants}} command to define text options:{{\variants Gender [Mr.|Ms.|Mx.]}}
Incorporate it inline within your document:Dear {{\variants Gender [Mr.|Ms.|Mx.]}},
This setup automatically adjusts the title based on the user’s selection. IfMs. (She/Her)
is chosen, the document will read "Dear Ms." -
Mapping conditional placeholders in the module:
When uploading your document template in a Create document action, you will be prompted to map your conditional placeholders.
For ourGender
example:
- Variable (from input node): Gender
-
Values (from input node): Mr. (He/Him), Ms. (She/Her), Mx. (They/Them)
Resulting in the configuration (in create document action):Mr. (He/Him|Ms. (She/Her)|Mx. (They/Them)
Mr.|Ms.|Mx.
This mapping ensures the document references the correct title based on the user's selection. The configuration aligns the variable values with the order of the variant values in the template.