Config files reference
This section is a reference on FormComposer's standard configuration files and object attributes.
Config files structure
You will need to provide FormComposer with a JSON configuration of your form fields,
and place it in generators/form_composer/data
directory.
- The task config file should be named
task_data.json
, and contain a list of JSON objects, each one with one keyform
. - If you want to slightly vary your form within a Task (by inserting different values into its text), you need to add two files (that will be used to auto-generate
task_data.json
file):token_sets_values_config.json
containing a JSON array of objects (each with one keytokens_values
and value representing name-value pairs for a set of text tokens to be used in one form version).unit_config.json
containing a single JSON object with one keyform
.- For more details, read on about dynamic form configs.
- If you want to insert code (HTML or JS) into your form config, you need to create
insertions
directory in the form config directory, and place these files there- For more details, read on about insertions.
Working config examples are provided in examples/form_composer_demo/data
directory:
- task data config:
simple/task_data.json
- form config:
dynamic/unit_config.json
- token sets values config:
dynamic/token_sets_values_config.json
- separate tokens values:
dynamic/separate_token_values_config.json
to createtoken_sets_values_config.json
- resulting extrapolated config:
dynamic/task_data.json
To understand what the concept of "tokens" means, see Using multiple form versions section.
Config file: task_data.json
Task data config file task_data.json
specifies layout of all form versions that are completed by workers. Here's an abbreviated example of such config:
[
{
"form": {
"title": "Form example",
"instruction": "Please answer all questions to the best of your ability as part of our study.",
"show_instructions_as_modal": false,
"sections": [
// Two sections
{
"name": "section_about",
"title": "About you",
"instruction": "Please introduce yourself. We would like to know more about your background, personal information, etc.",
"fieldsets": [
// Two fieldsets
{
"title": "Personal information",
"instruction": "insertions/personal_info_instruction.html",
"rows": [
// Two rows
{
"fields": [
{
"help": "",
"id": "id_name_first",
"label": "First name",
"name": "name_first",
"placeholder": "Type first name",
"tooltip": "Your first name",
"type": "input",
"validators": {
"required": true,
"minLength": 2,
"maxLength": 20
},
"value": ""
}
],
"help": "Please use your legal name"
},
{ ... }
]
},
{
"title": "Cultural background",
"instruction": "Please tell us about your cultural affiliations and values that you use in your daily life.",
"rows": [
// One row
{
"fields": [
{
...
"multiple": false,
"options": [
...
{
"label": "United States of America",
"value": "USA"
},
...
],
"type": "select",
...
}
]
}
],
"help": "This information will help us compile study statistics"
}
],
"triggers": {
"onClick": ["onClickSectionHeader", "FIRST"]
}
},
{ ... }
],
"submit_button": {
"text": "Submit",
"tooltip": "Submit form"
}
}
},
...
]
Unit config levels
Form UI layout consists of the following layers of UI object hierarchy:
- Form
- Section
- Fieldset
- Fields Row
- Field
Form objects attributes
Each of the form hierarchy levels appears as an object in form's JSON config, with certain attributes.
While attributes values are limited to numbers and text, these fields (at any hierarchy level) also accept raw HTML values:
help
instruction
title
Note that, due to limitations of JSON format, HTML content needs to be converted into a single long string of text.
You can style fields with HTML-classes in classes
attribute. You can use any bootstrap classes or our built-in classes:
hidden
- if you need to hide element and show it later with custom trigger, but you do not need it be a fully hidden field ("type": "hidden"
)centered
- centered horizontally
TBD: Other classes and styles insertions
Config level: form
form
is a top-level config object with the following attributes:
id
- Unique HTML id of the form, in case we need to refer to it from custom handlers code (String, Optional)classes
- Custom classes that you can use to restyle element or refer to it from custom handlers code (String, Optional)instruction
- HTML content describing this form; it is located before all contained sections (String, Optional)show_instructions_as_modal
- Enables showinginstruction
content as a modal (opened by clicking a sticky button in top-right corner); this make lengthy task instructions available from any place of a lengthy form without scrolling the page (Boolean, Optional, Default: false)title
- HTML header of the form (String)submit_button
- Button to submit the whole form and thus finish a task (Object)id
- Unique HTML id of the button, in case we need to refer to it from custom handlers code (String, Optional)instruction
- Text shown above the "Submit" button (String, Optional)text
- Label shown on the button (String)tooltip
- Browser tooltip shown on mouseover (String, Optional)triggers
- Functions that are being called on available React-events (onClick
, see JS trigger insertion)
sections
- List of containers into which form content is divided, for convenience; each section has its own validation messages, and is collapsible (Array[Object])
Config level: section
Each item of sections
list is an object with the following attributes:
id
- Unique HTML id of the section, in case we need to refer to it from custom handlers code (String, Optional)classes
= Custom classes that you can use to restyle element or refer to it from custom handlers code (String, Optional)collapsable
- Whether the section will toggle when its title is clicked (Boolean, Optional, Default: true)initially_collapsed
- Whether the section display will initially be collapsed (Boolean, Optional, Default: false)instruction
- HTML content describing this section; it is located before all contained fieldsets (String, Optional)name
- Unique string that serves as object reference when using dynamic form config (String)title
- Header of the section (String)fieldsets
- List of containers into which form fields are grouped by meaning (Array[Object])triggers
- Functions that are being called on available React-events (onClick
on header, see JS trigger insertion)
Config level: fieldset
Each item of fieldsets
list is an object with the following attributes:
id
- Unique HTML id of the fieldset, in case we need to refer to it from custom handlers code (String, Optional)classes
= Custom classes that you can use to restyle element or refer to it from custom handlers code (String, Optional)instruction
- HTML content describing this fieldset; it is located before all contained field rows (String, Optional)title
- Header of the section (String)rows
- List of horizontal lines into which section's form fields are organized (Array[Object])
Config level: row
Each item of rows
list is an object with the following attributes:
id
- Unique HTML id of the row, in case we need to refer to it from custom handlers code (String, Optional)classes
= Custom classes that you can use to restyle element or refer to it from custom handlers code (String, Optional)fields
- List of fields that will be lined up into one horizontal line
Config level: field
Each item of fields
list is an object that corresponds to the actual form field displayed in the resulting Task UI page.
Here's example of a single field config:
{
"id": "id_name_first",
"label": "First name",
"name": "name_first",
"placeholder": "Type first name",
"title": "First name of a person",
"type": "input",
"validators": {
"required": true,
"minLength": 2,
"maxLength": 20,
"regexp": ["^[a-z\.\-']+$", "ig"]
// or can use this --> "regexp": "^[a-z\.\-']+$"
},
"value": ""
}
Attributes for "field" config level
value
attribute
The value
attribute specifies initial value of a field, and has the following format:
- String for
input
,textarea
,email
,hidden
,number
,password
,radio
, andselect
with"multiple": false
field types- For
radio
andselect
fields, it must be one of the input options' values
- For
- Object for
checkbox
- The object should consist of all checkbox options with their Boolean value, e.g.
{"react": true, "python": true, "sql": false}
- The object should consist of all checkbox options with their Boolean value, e.g.
- Array<String> for
select
with"multiple": true
- All array items must be input options' values, e.g.
["python", "sql"]
- All array items must be input options' values, e.g.
Attributes - all fields
The most important attributes are: label
, name
, type
, validators
help
- HTML explanation of the field/fieldset displayed in small font below the field (String, Optional)id
- Unique HTML id of the field, in case we need to refer to it from custom handlers code (String, Optional)classes
= Custom classes that you can use to restyle element or refer to it from custom handlers code (String, Optional)label
- Field name displayed above the field (String)name
- Unique name under which this field's data will be sent to the server (String)placeholder
- Text faintly displayed in the field before user provides a value (String, Optional)tooltip
- Text shown in browser tooltip on mouseover (String, Optional)type
- Type of the field (input
,email
,select
,textarea
,checkbox
,radio
,file
,hidden
) (String)validators
- Validators preventing incorrect data from being submitted (Object[<String>: String|Boolean|Number], Optional). Supported key-value pairs for thevalidators
object:required
: Ensure field is not left empty (Boolean)minLength
: Ensure minimal number of typed characters or selected choices (Number)maxLength
: Ensure maximum number of typed characters or selected choices (Number)regexp
: Ensure provided value confirms to a Javascript regular expression. It can be:- (String): a regexp string (e.g.
"^[a-zA-Z0-9._-]+$"
) in which case default matching flags areigm
are used - (2-item Array[String, String]): a regexp string followed by matching flags (e.g.
["^[a-zA-Z0-9._-]+$", "ig"]
)
- (String): a regexp string (e.g.
fileExtension
: Ensure uploaded file has specified extension(s) (e.g.["doc", "pdf"]
) (Array<String>)
value
- Initial value of the field (String, Optional)triggers
- Functions that are being called on available React-events (onClick
,onChange
,onBlur
,onFocus
, see JS trigger insertion)
Attributes - file field
show_preview
- Show preview of selected file before the form is submitted (Boolean, Optional)
Attributes - select field
multiple
- Support selection of multiple provided options, not just one (Boolean. Default: false)options
- list of available options to select from. Each option is an object with these attributes:label
: displayed text (String)value
: value sent to the server (String|Number|Boolean)
Attributes - checkbox and radio fields
options
- list of available options to select from. Each option is an object with these attributes:label
: displayed text (String)value
: value sent to the server (String|Number|Boolean)checked
: initial state of selection (Boolean, default: false)
Config file: unit_config.json
Unit config file unit_config.json
specifies layout of a form in the same way as task_data.json
, but with a few notable differences:
- It contains a single JSON object (not a JSON array of objects)
- Some of its form attributes definitions must contain dynamic tokens (whose values will be extrapolated, i.e. substituted with variable chunks of text) - see further below.
Config file: token_sets_values_config.json
Sets of token values are specified as a JSON array of objects, where each object has one key "tokens_values"
. Under that key there's a key-value definition of all tokens in that set.
Example:
[
{
"tokens_values": {
"model": "Volkswagen",
"make": "Beetle",
"review_criteria": "insertions/review_criteria.html"
}
},
{
"tokens_values": {
"model": "Nissan",
"make": "Murano",
"review_criteria": "insertions/review_criteria.html"
}
}
]
Config file: separate_token_values_config.json
Lists of separate tokens values are specified as JSON object with key-value pairs, where keys are token names, and values are JSON arrays of their values.
Example:
{
"actor": ["Carrie Fisher", "Keanu Reeves"],
"genre": ["Sci-Fi"],
"movie_name": ["Star Wars", "The Matrix"]
}