# 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 | |
```javascript
[
{
"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](#description). | 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:
| 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:
| 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:
* ``: Bold text
* ``: Italic text
* ``: Strong emphasis
* ``: Emphasis
For example, the following code defines a bold text and an italic text.
```json
"description": "This is bold text and this is italic text"
```
#### Adding Links
The `description` property also facilitates adding clickable links to the field description by supporting the `` HTML tag with the `href` attribute.
For instance,
```json
"description": "For more details, visit here"
```
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.
```javascript
[
{
"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:
```javascript
[
{
"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. |
```javascript
{
"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 ..."
}
]
}
]
}
]
}
```