Tabs deep dive: checkboxes and radio groups

Welcome back to the Tabs deep dive series, where I’m giving you all the information you need to customize your documents with tabs using the eSignature REST API! In a previous post I discussed a few of the most commonly used tab types. In this post I’ll be focusing on two more specific types of tabs: checkboxes and radio groups. 

The image below shows both checkboxes and radio groups in the same document. A radio group contains multiple radio buttons and allows the recipient to choose only one of the buttons. In this example, the recipient will select a radio for “Tin Man,” “Scarecrow,” or “Cowardly Lion” by choosing the circle to the right of the word. Checkboxes are similar in that they allow the recipient to select a button, but with checkboxes it’s possible to select multiple options. In the example below, the recipient can check any or all of the boxes next to “Lions,” “Tigers,” “Bears,” and “Oh my!”

Although radio groups and checkboxes function similarly, you might prefer to use one or the other depending on your use case. If you want your recipient to choose only one option, a radio group is probably the way to go. If your recipient might be choosing multiple options, checkboxes are the way to go. 

Just as when you place other types of tabs in your documents, you can choose to place radio groups and checkboxes with either anchor tagging or by specifying their x and y position. In the document shown in the image above, I used anchor strings to place all of the tabs. To position the radio buttons, you would add this JSON snippet to your envelope definition:

"radioGroupTabs": [
  {
    "documentId": "1",
    "groupName": "Pick a character",
    "radios": [
      {
        "anchorString": "Tin Man",
        "anchorHorizontalAlignment": "right",
        "anchorUnits": "pixels",
        "anchorYOffset": "-5"
      },
      {
        "anchorString": "Scarecrow",
        "anchorHorizontalAlignment": "right",
        "anchorUnits": "pixels",
        "anchorYOffset": "-5"
      },
      {
        "anchorString": "Cowardly Lion",
        "anchorHorizontalAlignment": "right",
        "anchorUnits": "pixels",
        "anchorYOffset": "-5"
      }
    ]
  }
]

The JSON above creates a radio group containing three buttons. Each button has a different string value for the anchorString property, indicating where on the document the button should be placed. The anchorHorizontalAlignment property is set to "right", causing the tab’s left side to align with the last character of the matching anchor word.

To place the checkbox tabs, I also used anchor strings, but set the anchorHorizontalAlignment to "left" and the anchorXOffset to "-22". This causes the tab’s left side to be aligned with the beginning of the first character of the matching anchor word and then offsets it by 22 pixels so that the tab doesn’t overlap with the text. The JSON below demonstrates how to create the four checkbox tabs from the example screenshot.

"checkboxTabs": [
  {
    "tabLabel": "LionTab",
    "anchorString": "Lions",
    "anchorHorizontalAlignment": "left",
    "anchorYOffset": "-5",
    "anchorXOffset": "-22",
    "tabGroupLabels": [
      "checkboxgroup1"
    ]
  },
  {
    "tabLabel": "TigerTab",
    "anchorString": "Tigers",
    "anchorHorizontalAlignment": "left",
    "anchorYOffset": "-5",
    "anchorXOffset": "-22",
    "tabGroupLabels": [
      "checkboxgroup1"
    ]
  },
  {
    "tabLabel": "BearTab",
    "anchorString": "Bears",
    "anchorHorizontalAlignment": "left",
    "anchorYOffset": "-5",
    "anchorXOffset": "-22",
    "tabGroupLabels": [
      "checkboxgroup1"
    ]
  },
  {
    "tabLabel": "OhMyTab",
    "anchorString": "Oh my!",
    "anchorHorizontalAlignment": "left",
    "anchorYOffset": "-5",
    "anchorXOffset": "-22",
    "tabGroupLabels": [
      "checkboxgroup1"
    ],
  }
]

Once you’ve added both of the JSON snippets above to your envelope definition, you will have added three radio buttons and four checkboxes to your document, and it should look like the screenshot at the beginning of this post. The recipient who is assigned the tabs will be able to select one radio button and one or more (or none) of the checkboxes. 

But maybe you want to place some more validation on the checkboxes. Adding your checkbox tabs to a tab group lets you enforce rules around how many checkboxes your recipient should select. You may have noticed that the tabs in the JSON above were given a tabGroupLabel. This property assigns a tab to a tab group. To create a tab group, you can add this JSON to your list of tabs. 

"tabGroups": [
  {
    "groupLabel": "checkboxgroup1",
    "recipientId": "1",
    "validationMessage": "Please check a box",
    "groupRule": "SelectAtLeast",
    "minimumRequired": "1",
    "recipientId": "1",
    "documentId": "1",
    "pageNumber": "1",
    "xPosition": "0",
    "yPosition": "0",
    "tabScope": "Document",
    "tabType": "tabgroup"
  }
]

You can add the JSON above to your envelope definition as if you were adding a new tab type. The most important properties to notice are validationMessage, groupRule, and minimumRequired. The validationMessage string will appear in the tooltip for the checkbox group. The groupRule determines what kind of validation should be used. In this case I set the group rule to SelectAtLeast, which means that I will require the recipient to select at least some number of checkboxes. The value that I choose for minimumRequired further specifies that the recipient must select at least one checkbox. If I set that value to "2", it would mean that the recipient must select at least two checkboxes. Alternatively, I could set the group rule to SelectAtMost, SelectExactly, or SelectARange. The group rule will determine how the minimumRequired and maximumAllowed values will be interpreted. You can find more information about the possible types of validation for checkbox groups in the EnvelopeRecipientTabs : create API reference. This screenshot demonstrates the behavior that a recipient will see when hovering over a checkbox in your document when you are using the tab group in the JSON above.

You can have even more control over how recipients interact with checkboxes and radio buttons by preselecting certain values for them. You can do this by including the selected and locked properties in the JSON definition of your radio button or checkbox. Setting selected to true selects the tab for the recipient before sending. The locked property can be set to false to allow the recipient to unselect the preselected tabs or true to prevent them from doing so. This JSON snippet demonstrates how to do this for one of the checkbox tabs that I created previously.

{
  "tabLabel": "OhMyTab",
  "anchorString": "Oh my!",
  "anchorHorizontalAlignment": "left",
  "anchorYOffset": "-5",
  "anchorXOffset": "-22",
  "selected": "true",
  "locked": "false",
  "tabGroupLabels": [
    "checkboxgroup1"
  ],
}

The following JSON demonstrates how to do the same selection for one of the radio buttons that I created previously as well.

{
  "anchorString": "Tin Man",
  "anchorHorizontalAlignment": "right",
  "anchorUnits": "pixels",
  "anchorYOffset": "-5",
  "selected": "true",
  "locked": "false"
}

Once you have updated your JSON, recipients will see the tabs already selected, as shown here. 

Now that you understand the difference between radio buttons and checkboxes and how to use them, you’ll be able to customize your documents in all kinds of new ways. 

Additional resources

• Tabs deep dive: placing tabs in documents

• Tabs deep dive: anatomy of a tab

• Tabs deep dive: tab types

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter