Field, Field set, Field section

The Interaction Cloud operates with the following data structures:

Field	Field describes a piece of data of a specific type, how to collect it and how to send it to the client App. For example a field of type colour provides the Creator with a colour picker UI and produces a colour specification string to the client App.
Field set	Field set is an ordered list of references to fields. Field sets link Project settings, Events settings and so on with fields. A number of additional settings are available allowing field customisation for different contexts. For example a field "description" can be referenced in one field set as mandatory to be used for Project settings and in another field set as optional to be used in Event settings.
Field section	Field section is a named field set. It is used to represent the sets of fields to the Creator divided into sections.

Below is a diagram showing different data structures relationships:

• Project and Event settings link to fields via field sections.

• Elements also may have custom fields and these work in the same way as Project and Event settings - via field sections.

• Poll-like Elements describe what a Poll question and answer options are made of in terms of field sets.

• Collection type fields use a field set to describe a collection item.

Fields

Fields can be used with Elements, Events or Projects. Each field can be described using the following attributes:

Name	Description	Mandatory	Default
key	Data is passed to client application under this key. This must be unique for the Project.	yes
type	Defines what UI is used to collect data by the Creator.	yes
localisable	Allows to define values of the field using multiple languages. Only supported for freetext, wysiwyg, image, file types.	no	false
default	The default value for the field.	no

[
  {
    "key": "podium",
    "type": "external",
    "source": {
      "url": "http://example.com/feeds/podium.json",
      "method": "get"
    },
    "select": {
      "mode": "list",
      "min": 2,
      "max": 2,
      "filtering": "off"
    }
  },
  {
    "key": "strap",
    "type": "freetext",
    "default": "Default text",
    "localisable": false
  },
  {
    "key": "availbale",
    "type": "boolean",
    "default": true
  }
]

Field set

A field set is an array of fields. Each field refers to a Field declaration in a fields feed. Each Field can customise the Field declaration it references by specifying extra parameters like "mandatory" flag or default value.

Field sets can be used to describe Project, Event, Element fields.

Name	Description	Mandatory	Default
label	A name for corresponding UI element.	yes
key	Used as property name to communicate this data to the client. It's also used to link to the field declaration in fields feed.	yes
field	If field property is present, then its value is used as a reference to the field declaration instead of key. It allows reusing a field declaration in different field sets.	no
description	Text description of the Field to display in UI. See details here.	no
mandatory	An attribute configuring if it is mandatory to fill data before saving (and publishing in case of an Element) content with which this field is associated. Applied only to the default locale. Posible values: true/false string - for mandatory group boolean expression (beta)	no	false
default	The default value for the field. This value overrides default in the field declaration.	no
public	Controls whether the field value will be exposed to the client App.	no	true
cloneable	A boolean flag which determines whether the value of the field is copied at the time of exporting or cloning operations. See details here.	no	true
visible (beta)	Allows to specify if a field is visible in UI. Invisible fields still can be accessed via API, and they are available to the client app. Posible values: true/false boolean expression	no	true
items_number	Min/max number of collection items. Allowed only for fields with collection type.	no

Description

The description property allows to setup a textual representation of the field. This provides a way to explain the field's purpose and enhance user experience by offering clear and comprehensive descriptions directly in the user interface.

It supports a subset of HTML tags for formatting the text. Supported tags are:

• <b>: Bold text

• <i>: Italic text

• <strong>: Strong emphasis

• <em>: Emphasis

For example, the following code defines a bold text and an italic text.

"description": "<b>This is bold text</b> and <i>this is italic text</i>"

Adding Links

The description property also facilitates adding clickable links to the field description by supporting the <a> HTML tag with the href attribute.

For instance,

"description": "For more details, visit <a href='https://www.example.com'>here</a>"

On rendering, this will create a hyperlink in the field description, which on click, opens the specified web page in a new browser tab/window.

Cloneable

The cloneable is a boolean flag, with default value set to true.

Cloneable fields have their current value copied during any of these operations:

• Event export

• App settings export

• Event cloning

• Event template creation from an event

• Element cloning

In some cases the value is specific to event/element and must not be cloned. For such fields cloneable should be set to false. In this case new field is set to default value if such value is specified or empty value otherwise, not the original value.

The following operations are not affected by cloneable flag. They treat all fields as cloneable.

• Event import

• App settings import

• Event creation from a template

Updates of cloneable attribute via App Spec update do not affect the current values but only future operations.

cloneable attribute is taken from the destination App Spec, not source one. For example, given the source App Spec has cloneable set to true and destination one has it set to false the value will not be cloned. This is applicable only to Event and Element cloning, but not to import/export operations.

[
   {
       "label": "Podium",
       "key": "podium",
       "mandatory": true,
       "description": "Podium field description"
   },
   {
       "label": "Strap line",
       "key": "strap",
       "mandatory": false,
       "default": "Hello",
       "cloneable": false,
       "description": "Strap line field description"
   },
   {
       "label": "Rating",
       "key": "rating",
       "mandatory": "group1",
       "public": false,
       "description": "Rating field description"
   },
   {
       "label": "Competition",
       "description": "Competition is a ...",
       "key": "competition_id",
       "mandatory": "group1",
       "field": "comp_id",
       "description": "Competition field description"
   },
   {
       "label": "Slides",
       "key": "carousel",
       "items_number": { "min": 1, "max": 2 },
       "description": "Slides field description"
   }
]

Mandatory groups

When the value of the mandatory property is a string, this field belongs to the correspondingly named mandatory group. At least one field of the mandatory group must be filled with data in order to save data:

[
   {
       "label": "Question text",
       "key": "question_text",
       "mandatory": "question_content",
       "field": "text"
   },
   {
       "label": "Question image",
       "key": "question_image",
       "mandatory": "question_content",
       "field": "img"
   }
]

Field section

Field section is a named field set.

Name	Description
name	Used to present a set of fields as a group of related fields in the UI.
properties	Describes the field set.

{
  "sections": [
    {
      "name": "Appearance",
      "description": "Appearance section is a ...",
      "properties": [
        {
          "label": "Background color",
          "key": "appearance_background_color",
          "mandatory": false,
          "description": "Background color is a ..."
        }
      ],
      "subsections": [
        {
          "name": "Foreground",
          "description": "Foreground section is a ...",
          "properties": [
            {
              "label": "Foreground color",
              "key": "appearance_foreground_color",
              "mandatory": false,
              "description": "Foreground color is a ..."
            }
          ]
        }
      ]
    }
  ]
}