Docs Developer Site
Developer Docs Cms Stable Schemas Form Items

Form Items

Contents

Form items are the building blocks of forms. They define structure of your content.

Introduction

A form item optionally produce output based on its type and configuration. Each form item has a UI (front-end) component and server (back-end) component. The UI represents the visual editing interface in Content Studio, where the back-end is solely used for validation purposes.

Appearance (UI)

All form items share a common component structure, with a label, help text and the rendition which is specific to every form item.

Below you see examples of what a form item looks like in Content Studio, based on the TextLine form item.

Minimal form item with label - help text and input field
Figure 1. Basic with label and help text
Form item with error message
Figure 2. With error message
Form item in disabled state
Figure 3. Disabled

Usage

The following configuration is common for for most form items:

- type: "InputTypeName"  (1)
  name: "my_name"
  label:  "My label" (2)
  default: ""  (3)
  help-text: "Help text here" (4)
  occurrences:  (5)
    min: 0
    max: 1
  # config properties are specified directly  (6)
1 type and name are mandatory:
name is used when storing the data in a property, and must be unique on each level.
type refers to one of the many input types which are listed below.
Use snake_case (lowercase with underscores) for all names. Capital letters are flattened during indexing which can cause unexpected query behavior. The snake_case convention also ensures clean field names in the GraphQL API. 
name: "my_field_name"    # Recommended
name: "myFieldName"      # Avoid - capitals are flattened in the index
name: "myfieldname"      # Avoid - hard to read
2 label is another mandatory field that holds the human readable value that will be displayed when listing the input type control in the administrative interface.
3 default is an optional field that lets you specify default values to be used by the input type.
4 help-text is an optional field that lets you specify a text label shown below the input field. Used for explanation of the field’s purpose.
Like label, supports localization via the text/i18n object pattern.
5 occurrences is an optional field used to control the number of values stored by a single input.
min set to zero means the input is not mandatory
max set to zero means there is no upper limit to the number of values.
This element is optional, if omitted the default will be min: 0 and max: 1.
6 Config properties are specified directly on the form item, rather than in a separate config element.

Output

Form items that produce output will generate a property, with a deterministic value type, with zero, 1 or multiple occurences.

For instance, a TextLine will always produce a String value, while the output of an ItemSet is a propertySet (aka object).

The value type dictates how the value is stored and indexed, which also controls how you can query the value.

Form items grouped by output

Each form item produces a value o

String

Reference

Attachment Reference

Long

  • Long — 64-bit integer number

Double

  • Double — 64-bit floating-point number

Boolean

GeoPoint

  • GeoPoint — latitude/longitude coordinate

LocalDate

  • Date — date without time

LocalTime

  • Time — time without date

Instant

  • Instant — date and time without timezone

DateTime

  • DateTime — date and time with timezone

PropertySet (Object)

  • ItemSet — nested group of form items

  • OptionSet — selectable groups of form items

No output

Contents

Contents