Docs Developer Site
Developer Docs Cms Stable Schemas Form Items Option Set

Option Set

Contents

An option set is a group of options presented either as a multi-select option set (checkbox style), or as a single-select option set (dropdown style).

Each option may contain an optional form, which also support nested item-sets and option-sets.

Single select mode

Appearance

In single select mode, an option set looks similar to an item set, except that the user picks one option per instance from a list.

Inserting a new optionset (visualized as a card). Available options are listed in a dropdown

When inserting a new optionset, the selected option’s form will automatically be expanded.

The example below shows what it looks like when multiple option set instances are inserted and expanded. Each option set is visualized as a card.

Notice that the Horizontal line option does not have a form.
Showing three expanded cards
Delete, reset or move the option panels using the right hand context menu.

The final example demonstrates the same form as above, with all forms collapsed.

Showing three cards with titles for the respective options used Quote
Easily shuffle the order of the option sets by dragging the cards from the grip zone on the left hand side.

Usage

The schema below demonstrates how you may create blocks of structured content using the single-select mode.

Sample 1: single-select setup with the options hr, text, gallery and quote. 
- type: "OptionSet"
  name: "blocks"
  label: "Content blocks"
  occurrences:  (1)
    min: 0
    max: 0
  help-text: "Create content with optional blocks"
  selection:  (2)
    min: 1
    max: 1
  options:  (3)
    - name: "hr"
      label: "Horizontal line"
      help-text: "Adds a separator between blocks"
    - name: "text"
      label: "Text"
      items:
        - type: "TextArea"
          name: "text"
          label: "Text"
          occurrences:
            min: 1
            max: 1
    - name: "gallery"
      label: "Image gallery"
      items:
        - type: "ImageSelector"
          name: "images"
          label: "Images"
          occurrences:
            min: 1
            max: 0
    - name: "quote"
      label: "Quote"
      items:
        - type: "TextLine"
          name: "quote"
          label: "Quote"
          occurrences:
            min: 1
            max: 1
        - type: "TextLine"
          name: "quotee"
          label: "Quotee"
          occurrences:
            min: 1
            max: 1
1 occurrences — set max: 0 for unlimited option-set (block) instances.
2 selection/max Refers to selectable options per instance. A value of 1 ⇒ single-select mode.
3 options (required) Container of options. Each option may be empty or contain items, just like an item set.

Output

Value type: Set — child properties are indexed individually by their respective types.

An example output of the above form, where the user has created three instances, using three different options: quote, hr and text.

Example output of single-select setup, here with three occurrences.
{
  "blocks": [
    {
      "quote": {
        "quote": "Hi there",
        "quotee": "Mr Enonic"
      },
      "_selected": "quote"
    },
    {
      "hr": {
      },
      "_selected": "hr"
    },
    {
      "text": {
        "text": "A short text"
      },
      "_selected": "text"
    }
  ]
}
The _selected property can be used when searching for selected options for instance.

Multi select mode

Appearance

In multi select mode, the user may select zero to many options within a single option set.

Each option’s form (if it exists) will normally only be visible once the option is selected.

For convenience, a multi-select option set can be configured to have all options expanded by default.

Below: A multi-select option set where all options are expanded by default. Option 2 and 3 do not have any additional form items:

Form showing four options
For multi-select options sets, it is also possible to pre-select options by default.

Usage

The example below demonstrates multi-select mode, with the options Coloring, Wood upgrade, Include curtains and Exclusive wallpaper. Only options 1 and 4 contain form elements. Also, user may maximally select two options.

Multi-select option set with the coloring option selected by default.
- type: "OptionSet"
  name: "styling"
  label: "Room styling"
  expanded: true  (1)
  occurrences:  (2)
    min: 1
    max: 1
  help-text: "Select up to 2 options"
  selection:  (3) (4)
    min: 1
    max: 2
  options:
    - name: "coloring"  (5)
      label: "Coloring"
      help-text: "Select a color palette for the room"
      selected: true  (6)
      items:
        - type: "ComboBox"
          name: "palette"
          label: "Palette"
          occurrences:
            min: 1
            max: 1
          options:
            - value: "spring"
              label: "Spring"
            - value: "summer"
              label: "Summer"
            - value: "autumn"
              label: "Autumn"
            - value: "winter"
              label: "Winter"
          default: "spring"
    - name: "wood"
      label: "Wood upgrade"
      help-text: "Wooden floor and doors"
    - name: "curtains"
      label: "Include curtains"
      help-text: "Adds curtains to all windows"
    - name: "wallpaper"
      label: "Exclusive wallpaper"
      items:
        - type: "ContentSelector"
          name: "product"
          label: "Wallpaper"
          occurrences:
            min: 1
            max: 1
1 expanded Set to true to expand all of the options by default
2 occurrences Allow zero, one or more instances of the whole option-set.
3 selection/min (required) Minimum number of options that must be selected in this option set.
4 selection/max (required) Maximum number of options to create. > 1 ⇒ multi-select mode. 1 ⇒ single-select mode.
5 option name (required) Must be unique within the option set.
6 selected Set to true to pre-select one of the options.

Output

Value type: Set — child properties are indexed individually by their respective types.

The output from the example above may look like this:

Example output from multi-select form, with a single occurrence.
{
  "styling": {
    "_selected": [
      "coloring",
      "wood"
    ],
    "coloring": {
      "palette": "spring"
    },
    "wood": {
    }
  }
}
The _selected property contains information about which options were selected.

Querying via GraphQL

Guillotine generates a typed object for each option set with the same naming pattern as item sets — the parent content type name plus the option-set name, e.g. com_example_myproject_Article_Blocks. The generated type has a _selected field plus one nullable field per declared option; only the selected option(s) carry data, the rest are null.

_selected is a single string in single-select mode and a list of strings in multi-select mode. It is the dispatch key the client reads to know which option’s data is present.

Selecting an option-set’s data

Use a typed inline fragment on the parent content type, then select _selected alongside the fields of each option you want to handle:

{
  guillotine {
    get(key: "/articles/hello-world") {
      displayName
      ... on com_example_myproject_Article {
        data {
          blocks {
            _selected
            quote {
              quote
              quotee
            }
            text {
              text
            }
          }
        }
      }
    }
  }
}
Response
{
  "data": {
    "guillotine": {
      "get": {
        "displayName": "Hello world",
        "data": {
          "blocks": [
            {
              "_selected": "quote",
              "quote": { "quote": "Hi there", "quotee": "Mr Enonic" },
              "text": null
            },
            {
              "_selected": "text",
              "quote": null,
              "text": { "text": "A short text" }
            }
          ]
        }
      }
    }
  }
}

The data shape mirrors the stored property structure above. The option fields you don’t select in the query simply don’t appear in the response; unselected options in the data come back as null on the fields you do select.

Dispatching on _selected

A client typically branches on _selected to render the right block. For single-select mode it’s a string; for multi-select it’s an array, and the data fields for each entry in the array are populated:

for (const block of data.blocks) {
  switch (block._selected) {
    case "quote": renderQuote(block.quote); break;
    case "text":  renderText(block.text);  break;
    case "hr":    renderHr();              break;
  }
}

Filtering content by selected option

Because _selected is indexed like any other field, you can find content whose option set contains a given option using a term query against its dotted path:

{
  guillotine {
    queryDsl(
      query: {
        term: {
          field: "data.blocks._selected",
          value: { string: "quote" }
        }
      }
    ) {
      _id
      displayName
    }
  }
}

For multi-select option sets the same query works — _selected is a multi-valued field on each instance, and a term match succeeds if any value matches.

Nested option sets and item sets

Option sets may contain item sets or further option sets. The typed-access pattern compounds: each nesting level becomes its own generated type, and field paths for filtering extend with additional dotted segments (e.g. data.blocks.gallery.images._references).

Contents

Contents