Input

Inputs are the heart of data collection within your SurveyCompo surveys. They provide the interactive elements where users submit their answers, opinions, and feedback. SurveyCompo offers a wide range of input types to accommodate diverse survey needs.

Key Concepts

• Inputs within Blocks: Blocks act as containers for one or more input controls. SurveyCompo gives you the flexibility to combine different input types within a single Block.

• Labels and Hints: Most inputs can have an optional label (the question or instruction) and a hint (additional guidance for the user). Both support HTML for customization.

• Input Ids: Each input can be assigned an identifier (id). This is useful for implementing piping, validation, and conditional logic. To gather responses, it's crucial to assign an id to inputs. This is because when responses are collected, they are associated with their respective id.

• Input Values: Each input type collects data differently. Some have boolean values (true/false), others text values, numerical values, or selections from a list.

• Input Randomization: You can randomize the order in which inputs appear within a block to prevent response bias.

• Conditional Logic: Use the visibleIf key for inputs to show or hide them based on specific survey responses or variables. Conditional logic creates dynamic surveys that adapt to user input.

• Input Validation: Define validation rules to ensure users provide data in the expected format (e.g., valid email addresses, numeric values within a range). Validation improves data quality and the user experience.

Input IDs

In SurveyCompo, survey response data is collected as key-value pairs. The key is the id assigned to each input, and the value is the user's response to that input. Therefore, it is essential to assign an id to each input that is intended to capture user responses.

Here's an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "name": "Product Satisfaction Survey",
  "startScreens": [
    /* ... */
  ],
  "pages": [
    {
      "blocks": [
        {
          "title": "What is your current employment status?",
          "inputs": [
            {
              "type": "RADIO",
              "id": "employment:employed",
              "label": "Employed"
            },
            {
              "type": "RADIO",
              "id": "employment:retired",
              "label": "Retired"
            },
            {
              "type": "RADIO",
              "id": "employment:other",
              "label": "Other"
            }
          ]
        }
        /* ... other blocks ... */
      ]
    }
    /* ... other pages ... */
  ]
}

In the example above, each radio input has a unique id that includes a prefix (employment:) followed by a specific identifier (employed, retired, other). This naming convention groups related inputs and differentiates them when collecting responses. However, you can use any naming convention that suits your needs.

Since the inputs are radio buttons, the values collected will be boolean (true/false). For example, if the respondent selects the "Employed" option, the value collected will be true for the input id employment:employed. You can then use this value in conditional logic or piping. For instance, to ask a question only applicable to employed respondents, you can use the following condition:

{
  /* ... */
  "visibleIf": "#employment:employed"
}

What if you want to group several inputs together but only need a single value from one of them? In this case, you can assign the same id to multiple inputs. Here's an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

{
  "name": "Product Satisfaction Survey",
  "startScreens": [
    /* ... */
  ],
  "pages": [
    {
      "blocks": [
        {
          "title": "What is your current employment status?",
          "inputs": [
            {
              "type": "RADIO",
              "id": "employment",
              "label": "Employed",
              "checkedValue": "employed"
            },
            {
              "type": "RADIO",
              "id": "employment",
              "label": "Retired",
              "checkedValue": "retired"
            },
            {
              "type": "RADIO",
              "id": "employment",
              "label": "Other",
              "checkedValue": "other"
            }
          ]
        }
        /* ... other blocks ... */
      ]
    }
    /* ... other pages ... */
  ]
}

In this example, the identifier employment is assigned to three radio inputs. However, only the value from the radio button that the respondent last interacted with (i.e., the selected option) will be recorded. The checkedValue key is used to define the value that will be recorded when an input is selected. Without this, the input's recorded value would simply be a boolean (true/false), which may not be meaningful in this context.

If the 'Employ' radio button is selected, the value recorded will be employed. You can also use this value in conditional logic or piping. For example, to ask a question only applicable to employed respondents, you can use the following condition:

{
  "visibleIf": "#employment == employed"
}

Based on your data reporting requirements and survey structure, you can choose the approach that best suits your needs. Grouping related inputs under a common id can be useful when you need to capture a single value from multiple inputs. This works well for most single choice questions and can simplify data analysis. However, allowing each input to have a unique id can provide more granular data and flexibility in data analysis.

Input ID Best Practices

Here are some best practices to consider when assigning IDs to inputs:

• Use Descriptive IDs: Assign IDs that are descriptive and easy to understand. This makes it easier to identify inputs when analyzing survey data.

• Use Prefixes: Use prefixes to group related inputs. This helps organize inputs and differentiate them when collecting responses.

• Avoid Special Characters: Avoid using special characters in IDs. Stick to alphanumeric characters, underscores and colon (:).

• Use CamelCase: If you prefer to use multiple words in an ID, consider using camelCase or underscores to separate words.

• Be Consistent: Maintain a consistent naming convention across your survey to ensure clarity and consistency in your data collection.

• Avoid Spaces: IDs cannot contain spaces. If you need to separate words, use camelCase or underscores.

• Use Meaningful Names: Choose IDs that reflect the purpose of the input. This makes it easier to interpret survey data and perform analysis.

Input Types

Here's a quick overview of the input types currently supported. For more information on each input type, including examples and use cases, refer to the Input Types documentation.

Checkboxes and Radios

• CHECKBOX: Multiple selections from a list (boolean values).
• CHECKBOX_TEXT: A "checkbox + text" combination to capture an 'Other' option.
• RADIO: Single selection from a list (boolean value).
• RADIO_TEXT: A "radio + text" combination for an 'Other' option.

Rating Scales

• STAR_SCALE: Familiar star-based rating (integer value)
• NUMBER_SCALE: Numeric scale rating (integer value)

Text-Based Inputs

• TEXT: Single-line text input (text value).
• TEXTAREA: Multi-line text input (text value).

Specialized Inputs

• LIKERT_SCALE: Opinion scale presented in a visually appealing format (text value of the chosen option).
• TOGGLE: On/off switch (boolean value).
• DROPDOWN: A dropdown list for selecting one option (text value).
• IMAGE: Images as selectable options (text values of selected images).
• MATRIX: A grid-based question format for collecting responses to multiple related questions using a consistent scale.

Input JSON Example

The following code example demonstrates how inputs integrate into the survey JSON data model. view source

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

{
  "name": "My Survey",
  "startScreens": [
    /* ... */
  ],
  "pages": [
    {
      /* ... */
      "blocks": [
        {
          "title": "Gender",
          "layoutColumnCount": 2,
          "layoutColumnWidth": "50%",
          "inputs": [
            {
              "type": "RADIO",
              "label": "Male"
            },
            {
              "type": "RADIO",
              "label": "Female"
            },
            {
              "type": "RADIO",
              "label": "Non-binary"
            },
            {
              "type": "RADIO",
              "label": "Prefer not to say"
            }
          ]
        },
        {
          "title": "Age",
          "inputs": [
            {
              "type": "DROPDOWN",
              "hint": "Please select ...",
              "dropdownInputOptions": [
                "Under 18",
                "18-24",
                "25-34",
                "35-44",
                "45-54",
                "55-64",
                "65 or over"
              ]
            }
          ]
        }
      ]
    }
    /* ... */
  ],
  "completeScreens": [
    /* ... */
  ],
  "abortScreens": [
    /* ... */
  ]
}

Input Data Keys