Configure a Boolean Checkbox

Goal

Configure a checkbox component with a single checkbox that saves a boolean (true/false) value, and validate that the user selects the checkbox before submitting a form.

Expression

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
a!localVariables(
  local!userAgreed,
  a!formLayout(
    titleBar:"Example: Configure a Boolean Checkbox",
    contents:{
      a!checkboxField(
        label: "Acknowledge",
        choiceLabels: {"I agree to the terms and conditions."},
        choiceValues: {true},
        /* If local!userAgreed is false, set the value      */
        /* to null so that the checkbox is unchecked        */
        value: if(local!userAgreed, true, null),
        /* We want to save a false value when the checkbox  */
        /* is unchecked, so we need to check whether        */
        /* save!value is null and update the variable if so */
        saveInto: a!save(
          local!userAgreed,
          if(isnull(save!value), false, true)
        ),
        required: true,
        requiredMessage: "Accept the terms and conditions to continue"
      )
    },
    buttons:a!buttonLayout(
      primaryButtons:{
        a!buttonWidget(
          label:"Submit",
          submit: true
        )
      }
    )
  )
)

Test it out

1. Click Submit without selecting the checkbox. Notice that the custom message shows up. Without a custom message, the default "A value is required" message would be confusing.
2. Select the checkbox and click Submit.

Notable Implementation Details

• Unchecking the checkbox saves a value of false. However, the initial value of local!userAgreed is null, which also results in the box being unchecked. Therefore, you may need to account for values of both false and null in your interface. Alternatively, you can set the initial value of local!userAgreed to false to avoid null values entirely.
• In this recipe, we had to modify the value of the component in addition to the saveInto. We had to do that in order to save a value of false, which is not a valid option in our checkbox component that only has one option. This design pattern works because both the value and saveInto parameters are set using the same variable, so the component responds to the user's interactions.

Feedback