Radio Group Place

A radio group place marks the options of a single-choice question in a document. The recipient selects exactly one option from the group during the signing ceremony.

Unlike a dropdown, each option is a separate mark placed independently on the document. Options that belong to the same group are mutually exclusive: selecting one clears the others.

Options

The options property lists the choices in the group. Each option carries a value, which is the value captured when the recipient selects that option.

{
  //...
  "key": "billing_cycle",
  "options": [
    { "value": "monthly" },
    { "value": "annual" }
  ]
  //...
}

An option value must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

Positioning

You position each option individually, not the group as a whole. Address an option with a group_key:value key, where group_key is the key of the radio group place.

A billing_cycle group with options monthly and annual gives you two keys to position:

• billing_cycle:monthly
• billing_cycle:annual

Use those keys as placeholders in the document:

[[billing_cycle:monthly]]  Monthly
[[billing_cycle:annual]]   Annual

Or as fixed positions:

{
  //...
  "fixed_positions": [
    { "place_key": "billing_cycle:monthly", "page": 1, "top": 300, "left": 40 },
    { "place_key": "billing_cycle:annual", "page": 1, "top": 340, "left": 40 }
  ]
  //...
}

This lets you spread the options of one question across the document, wherever they appear in your layout.

Shape and Symbol

Two properties control how the control is drawn.

shape sets the geometry. Use circle for a round radio button (default), or square for a box that matches documents printing square options.

symbol sets the mark drawn on the selected option. Use fill for a solid mark (default), check for a checkmark, or xmark for an X. A fill symbol takes the shape of the control.

{
  //...
  "shape": "square",
  "symbol": "check"
  //...
}

Default Selection

Use default to preselect an option when the place is displayed. Its value must match the value of one of the options in the group. If no match is found, a validation error is returned.

{
  //...
  "options": [{ "value": "monthly" }, { "value": "annual" }],
  "default": "monthly"
  //...
}

Requirement

Set requirement to required to force the recipient to select an option before completing their action. This is the default.

Set it to optional to let the recipient skip the question. An optional group can also be cleared after the fact: the recipient clicks the selected option again to return the group to no selection.

Capturing Input

Set capture_as to store the selected option in the envelope’s captures object. The captured value is the value of the option the recipient chose, not the group key.

For a billing_cycle group captured as billing_cycle, a recipient who selects the annual option produces:

{
  //...
  "captures": {
    "billing_cycle": "annual"
  }
  //...
}

Size

The height property sets the height of each option in points (1/72 inch). The width equals the height. Must be between 8 and 40. Defaults to 20.

Attributes

"options": [
  { "value": "monthly" },
  { "value": "annual" }
]

Examples

"documents": [
  {
    //...
    "places": [
      {
        "key": "billing_cycle",
        "type": "radio_group",
        "recipient_key": "customer",
        "options": [
          { "value": "monthly" },
          { "value": "annual" }
        ],
        "default": "monthly",
        "capture_as": "billing_cycle",
        "requirement": "required"
      }
    ],
    "fixed_positions": [
      { "place_key": "billing_cycle:monthly", "page": 1, "top": 300, "left": 40 },
      { "place_key": "billing_cycle:annual", "page": 1, "top": 340, "left": 40 }
    ]
    //...
  }
]