•••
 
Documentation   /   Reference: templates   /   Template field directives
 
 

Template field directives

 

Fields are defined as blocks of directives. Each block starts with --#: on its own line, and each directive is on its own line after it.

--#:
---name:{variable_name}
---type:{field_type}
---appears_on:{counterparty|signatory|dates|extras|settings}
---mini_label:{label}
---start_text:{placeholder}
---small_msg:{hint}
---required:{true|false}

The same format is used for template fields (the Variables panel) and workflow launch forms (Settings → Extra fields).

Directives

Directive Required Applies to Description
---name Yes All The variable name, used as {{name}}. Letters, numbers and underscores.
---type Yes All The field type (see below).
---appears_on Yes All The section of the creation form: counterparty, signatory, dates or extras. Launch forms use settings.
---mini_label No Most The field's label.
---start_text No text, textarea Placeholder text in the empty field.
---small_msg No All A hint shown under the label.
---required No All true makes the field compulsory on the creation form.
---default_value No text, checkbox, hidden The value used if nothing is entered. Also used as the output when the variable is blank.
---string_format No text, textarea, amount Validates the input. See String formats.
---format No date, text Output format. For dates, a date format. For text, ucfirst or lcfirst.
---rows No textarea Height of the box, in rows.
---options Yes for dropdowns dropdown, select_multiple, toggle The choices: "Option 1","Option 2". Use "value[:]Label" to save a value different from the label, or an https:// URL returning JSON.
---selected_dd No dropdown The option selected to begin with.
---checkbox_msg No checkbox The text next to the box.
---currency No amount The currency symbol. Default £.
---minimum, ---maximum No amount, number Limits on the value.
---hide_if No All Hides the field when a condition is met: {variable}({MATCH_TYPE} {value}).
---collect_data No All true shows the field inside the document, for the recipient to complete.
---required_on_collect No All true makes a collect_data field compulsory for the recipient.

Field types

---type Description
text One line of text
textarea Several lines of text
amount An amount of money
date A date
dropdown One choice from a list
select_multiple Several choices from a list. Output as a bulleted list.
checkbox A tick box
toggle An on/off switch
attach_file A file upload
section A heading for the fields that follow
hidden Not shown. Holds a passed-in or default value.

Comments

Text between /* and */ is ignored, so you can annotate field definitions:

/* Fields for the employment section */
--#:
---name:job_title
---type:text
---appears_on:extras

Example

--#:
---name:employment_section
---type:section
---appears_on:extras
---mini_label:Employment details

--#:
---name:contract_type
---type:dropdown
---appears_on:extras
---mini_label:Contract type
---options:"Permanent","Fixed term"
---required:true

--#:
---name:fixed_term_months
---type:text
---appears_on:extras
---mini_label:Length of fixed term (months)
---string_format:number
---hide_if:contract_type(NOT_EQUALS Fixed term)

--#:
---name:probation
---type:checkbox
---appears_on:extras
---checkbox_msg:Include a probation period