The choice Element

The choice element provides a number of options, of which the consumer can choose a specifiable amount.

{
    "type": "choice",
    "tags": array<string>,
    "version": string,
    "key": string,
    "label": ?string,
    "placeholder": ?string,
    "selected": array<string>,
    "allow_selected": ?{
            "min": ?number,
            "max": ?number
    },
    "options": array<{
            "value": string,
            "label": string,
            "description": ?string,
            "badge": ?{
                "type": "image"|"text",
                "content": "string"
            },
            "disabled": boolean
    }>
}

label String, optional, since v1.0.0

The label property represents a caption for the choice element.

placeholder String, optional, since v1.0.0

The placeholder property specifies a short hint that describes the expected value of the choice element.

selected String[], always present, since v1.0.0

The selected array holds the values of the selected options which should be selected at initialisation.

allow_selected Object, optional, since v1.0.0

The optional allow_selected property specifies how many options must be selected at least and at most.

The values for allow_selected could indicate the styling of the choice element:

If the consumer has to select exactly one option ({min: 1, max: 1}), this suggests the usage of either a <select> or <radio>s. An example of how this might look is depicted below:

Example of a possible look of a Choice where the consumer can only select one option

If the consumer does not have to select an option ({min: 0, max: 1}) or can select multiple ({min: >=1, max: >1}), this suggests the usage of either a <select multiple> or <checkbox>es. An example of how this might look is depicted below:

Example of a possible look of a Choice where the consumer can select multiple options

Please not that a radio, select or checkbox attribute in the tags array could also indicate a suggested way of visualizing the choice element.

allow_selected.min Number, optional, since v1.0.0

The optional min property specifies how many options must be selected at least. The default value is 1.

allow_selected.max Number, optional, since v1.0.0

The optional max property specifies how many options can be selected at most. The default value is 1.

options Object[], always present, since v1.0.0

The options array contains the available options as objects.

options[].value String, always present, since v1.0.0

The value property identifies the option.

options[].label String, always present, since v1.0.0

The label property will be shown to the consumer.

options[].badge Object, optional, since v1.1.0

The optional property badge - depending on its type property - either holds a text or an image source.

Possible Option Display

options[].badge.type String, always present, since v1.1.0

The value of the type property has to be either image or text to indicate the type of badge.

options[].badge.content String, always present, since v1.1.0

The value of the content property can be a base64-encoded string or a URL.

options[].description String, optional, since v1.1.0

The optional description property contains text which provides additional information about the option.

options[].disabled Boolean, always present, since v1.0.0

The disabled property marks an option as disabled or unclickable.

Possible Values for tags

  • BOX

Example of a possible look of a choice element with the BOX-tag

Example of a possible look of a choice element with the BOX tag.

  • DROPDOWN

Example of a possible look of a choice element with the DROPDOWN-tag

Example of a possible look of a choice element with the DROPDOWN tag.

  • RADIO

  • CHECKBOX

  • SELECT

  • HORIZONTAL

Example

{
    "type": "choice",
    "key": "choice",
    "tags": [],
    "version": "1.1.0",
    "label": "",
    "placeholder": "",
    "selected": ["0"],
    "allow_selected": {
        "min": 1,
        "max": 1
    },
    "options": [
        {
            "value": "0",
            "label": "example1",
            "description": "First Example",
            "disabled": false
        },
        {
            "value": "1",
            "label": "example2",
            "disabled": false
        },
        {
            "value": "2",
            "label": "example3",
            "disabled": true
        }
    ]
}

Returning the value of the choice Element

The value sent back to the server for the choice element has to be an array of strings with the value(s) of the selected option(s).

The following example first depicts the received form and then two possible unencrypted responses to it:

{
    "form_identifier": "ab12c34d-e45f-6789-0a12-3bc4de567fa",
    "version": "1.0.0",
    "elements": [
        {
            "type": "choice",
            "key": "choice1",
            "tags": [],
            "version": "1.1.0",
            "selected": ["0"],
            "allow_selected": {
                "min": 1,
                "max": 2
            },
            "options": [
                {
                    "value": "0",
                    "label": "example1",
                    "description": "First Example",
                    "disabled": false
                },
                {
                    "value": "1",
                    "label": "example2",
                    "disabled": false
                },
                {
                    "value": "2",
                    "label": "example3",
                    "disabled": true
                }
            ]
        }
    ]
}

For one selected option a response could look like this:

{
    "form_identifier": "ab12c34d-e45f-6789-0a12-3bc4de567fa",
    "data": [
        {
            "key": "choice1",
            "value": ["0"]
        }
    ]
}

For two selected options a response could look like this:

{
    "form_identifier": "ab12c34d-e45f-6789-0a12-3bc4de567fa",
    "data": [
        {
            "key": "choice1",
            "value": ["0", "1"]
        }
    ]
}

Changelog


1.1.0 - 13.05.2019

  • Added option.badge
  • Added option.description

1.0.0 - 01.02.2019

  • initial version

results matching ""

    No results matching ""