Field Types

Boolean

A checkbox. Produces boolean value.

Example

{
"key": "boolean",
"type": "boolean"
}

Collection

Collection allows the creation of lists of objects. It produces an array. Each object is made of fields represented in a fieldset:

Example

{
"key": "collection_field",
"type": "collection",
"item_label": "Item {{media_text}}",
"description": "Contains media items ...",
"fieldset": [
{
"label": "Text",
"description": "Text is a ...",
"key": "media_text"
},
{
"label": "Image",
"description": "Image is a ...",
"key": "media_image"
}
]
}

Collections can contain a collection as a field with only one level of nesting, which also assumes that a collection can't contain itself as a field.

{
"key": "collection_with_nested_collection",
"type": "collection",
"item_label": "Item {{media_text}}",
"description": "Contains media items ...",
"fieldset": [
{
"label": "Text",
"description": "Text is a ...",
"key": "media_text"
},
{
"label": "Nested collection",
"description": "Nested collection is a ...",
"key": "collection_field"
}
]
}

Below are examples of format in which values of collection type are available to a client app:

Empty collection

[]

2 items collection

[
{
"media_text": "First item"
},
{
"media_text": "Second item",
"media_colour": "#a832a2"
}
]

Nested collection

[
{
"media_text": "Item #1",
"collection_field": []
},
{
"media_text": "Item #2",
"collection_field": [
{
"media_text": "Nested Item #1"
},
{
"media_text": "Nested Item #2",
"media_colour": "#a832a2"
}
]
}
]

Item labels

Collection field can have item_label property. If specified, item label will be displayed instead of "Item #" text.

item_label is a handlebars template. Besides static text, field value from the fieldset can be used as a variable.

{
"key": "participants",
"type": "collection",
"item_label": "Participant {{name}} from {{place}}",
"description": "Collection of participants ...",
"fieldset": [
{
"label": "Name",
"key": "name",
"field": "text",
"description": "Participant's name ..."
},
{
"label": "Place",
"key": "place",
"field": "text",
"description": "Participant's place ..."
}
]
}

Same field type restrictions are applied as for element labels.

Limitations

Collections have these limitations:

  • Default values are not supported

  • Prefill is not supported

  • mandatory flag is not supported for the collection itself, although it is supported for fields within collection items. Use items_number instead to specify the minimum and maximum number of items allowed in a collection. See Field set.

  • description optional attribute is supported for adding a tooltip for the corresponding field

Colour

Supported formats

HEX, RGB, RGBA formats are allowed at the moment.

Examples:

  • #000000

  • rgb(red, green, blue)

  • rgba(red, green, blue, alpha)

A colour picker.

Example

{
"key": "colour",
"type": "colour",
"default": "#ff0080"
}

Datetime

A date picker and controls for adding time. Produces datetime as a timestamp.

Example

{
"key": "start_time",
"type": "datetime"
}

External

External type is designed for more complex data structure which might require the Producer to traverse through a categories tree (navigation) in order to narrow down data subset (data). These have the following attributes:

source

An object which specifies the location of the navigation and data feed.

Note that only GET method is supported.

select

An object which controls what data selection mechanism is to be used.

select has these properties:

mode

Defines how data selection mechanism should be implemented. Supported modes:

  • list one or more items from a list selected manually by Producer

  • dropdown one item from a drop down selected manually by Producer

min

Minimum number of items that Producer can select from a list for list mode

max

Minimum and maximum number of items that Producer can select from a list for list mode

filtering

Controls data filtering mechanism. This works over keywords specified for data items and is supported only for list mode. Possible values:

  • off no filtering supported

  • freetext free text entry with autocomplete

  • checkbox a checkbox for each keyword

  • dropdown a dropdown of keywords

Filtering is not yet supported

Example

{
"key": "podium",
"type": "external",
"source": {"url": "https://example.com/feeds/podium.json", "method": "get"},
"select": {
"mode": "list",
"min": 2,
"max": 2,
"filtering": "off"
}
}

Navigation is a hierarchy of categories. At the bottom of the navigation tree there is a layer of data for that navigation tree branch. Hierarchy is optional.

Both hierarchy and data can be split between several feeds. This allows to partition feeds in a flexible way to meet size or architecture restrictions. This is done by providing categories-source or data-items-source attributes.

Navigation object has these properties:

categories-label

Dropdown labels for category selection.

categories

An array of categories entries, used to populate

categories dropdown.

categories-source

Source object with an url pointing to JSON feed

containing categories data array. This is ignored if

categories is specified.

name

Name of a category as to be displayed in a dropdown.

data-items

An array of data entries.

data-items-source

Source object with a URL pointing to JSON feed

containing data entries array. Ignored if data-items

is specified.

Data

id

An arbitrary id which can be used for debug/data tracing purposes.

name

Name of this data item to be presented to the Producer.

data

Actual data

keywords

Array of keywords used for filtering.

Examples

Non-hierarchical data example

[
{
"id": "a1",
"name": "Player 1 name",
"data": "some data here",
"keywords": [ "keyword1", "keyword2"]
},
{
"id": "b2",
"name": "Player 2 name",
"data": "some data",
"keywords": [ "keyword1", "keyword2"]
}
]

Hierarchical structure example

The following feed describes this hierarchy:

  1. First layer - discipline selection of “Hockey” and “Figure Skating”, labelled “Discipline”

  2. Second layer for Hockey - event selection of “Men’s tournament” and “Women’s tournament”, labelled “Events”

  3. Third layer for “Men’s tournament” - match selection of “Men’s Gold Medal Game” and “Men’s Bronze Medal Game”, labelled “Match”

  4. Fourth layer for “Men’s Gold Medal Game” is the data layer. It lists two items of data.

{
"categories-label": "Discipline",
"categories": [
{
"name": "Hockey",
"categories-label": "Event",
"categories": [
{
"name": "Men's tournament",
"categories-label": "Match",
"categories": [
{
"name": "Men's Gold Medal Game",
"data-items": [
{
"id": "a1",
"name": "Player 1 name",
"data": "some data here",
"keywords": [ "keyword1", "keyword2"]
},
{
"id": "b2",
"name": "Player 2 name",
"data": "some data",
"keywords": [ "keyword1", "keyword2"]
}
]
},
{
"name": "Men's Bronze Medal Game",
"data-items-source": {"url": "http://example.com/feeds/mbmg.json", "method": "get"}
}
]
},
{
"name": "Women's tournament",
"categories-label": "Event",
"categories-source": {"url": "http://example.com/feeds/wt.json", "method": "get"}
}
]
},
{
"name": "Figure Skating",
"label": "Events",
"categories": {"url": "http://example.com/feeds/fs.json", "method": "get"}
}
]
}

The categories data feed (http://example.com/feeds/wt.json) might look like this:

[
{
"name": "Women's Gold Medal Game",
"data-items": [
{
"id": "a1",
"name": "Player 1 name",
"data": "some data here",
"keywords": [ "keyword1", "keyword2"]
},
{
"id": "b2",
"name": "Player 2 name",
"data": "some data",
"keywords": [ "keyword1", "keyword2"]
}
]
},
{
"name": "Women's Bronze Medal Game",
"data-items-source": {"url": "http://example.com/feeds/wbmg.json", "method": "get"}
}
]

The data feed (http://example.com/feeds/mbmg.json) might look like this:

[
{
"id": "a1",
"name": "Player 1 name",
"data": "some data here",
"keywords": [ "keyword1", "keyword2"]
},
{
"id": "b2",
"name": "Player 2 name",
"data": "some data",
"keywords": [ "keyword1", "keyword2"]
}
]

File

A file uploader / file URL field. Produces URL string.

Maximum file size is 32Mb

Example

{
"key": "file",
"type": "file"
}

Freetext

A free text field with auto-adjusting height. Produces string value.

Example

{
"key": "text_during_poll",
"type": "freetext",
"default": "Make your decision now...",
"localisable": false
}

Image

An image uploader / image URL field. Produces URL string.

The following attributes are allowed for an image field:

Name

Mandatory

Description

width

true

An array of two positive integers [left_bound, right_bound], provides the range of allowed pixel values for the width of an image.

height

height

true

An array of two positive integers [left_bound, right_bound], provides the range of allowed pixel values for the height of an image.

aspect_ratio

file_size

true

An positive integer provides the maximum allowed file size in kilobytes.

aspect_ratio

false

An array of two positive integers [width, height], provides the allowed value for aspect ratio.

Maximum file size is 32Mb

Example

{
"key": "square_image",
"type": "image",
"localisable": "true",
"aspect_ratio": [1, 1],
"width": [20, 1000],
"height": [20, 1000],
"file_size": 2048
}

List

A dropdown. Produces a string.

This type requires an extra data attribute, which describes an array of objects used to create the dropdown content. Each object supports these properties:

name

Specifies how the option is called in the dropdown.

value

This is sent to the client app, can be any string, for example stringified JSON. LViS passes this through as is.

preview

Optional object which provides data for value preview. Has two properties:

  • type - preview type. Only "video" type is supported now.

  • url - video preview URL.

Note that if the default value is specified then it must be one of the value defined by the data attribute.

Example

{
"key": "position",
"type": "list",
"data": [{
"name": "At the top",
"value": "top",
"preview": {
"type": "video",
"url": "http://example.com/preview.mp4"
}
}, {
"name": "At the bottom",
"value": "bottom",
"preview": {
"type": "video",
"url": "http://example.com/preview2.mp4"
}
}]
}

Number

An input field. Produces integer or float number.

Example

{
"key": "number_field",
"type": "number",
"default": 123
}

WYSIWYG

A rich-text editor. Produces HTML string with following tags:

Formatting

Tag names

headings

<h1>, <h2>, <h3>, <h4>, <h5>, <h6>

paragraph

<p>

lists

<ol>, <ul>

bold

<strong

italic

<em>

subscript

<sub>

superscript

<sup>

underline

<u>

link

<a>

code block

<pre>, <code>

Some of the typography formatting is implemented with custom classes:

Formatting

Class name

font size

.ql-size-small, .ql-size-large, .ql-size-huge

block indent

.ql-indent-1, .ql-indent-2, ..., .ql-indent-<N>

right to left direction

.ql-direction-rtl

font family

.ql-font-serif, .ql-font-monospace

Example

{
"key": "wysiwyg",
"type": "wysiwyg",
"default": "<p>hello<p><p>world</p>"
}