Elements spec

Elements, supported by the App are described in an elements spec.
[
  {
    "name": "Podium",
    "content_type": "podium",
    "derived_from": "rpoll",
    "duration": {
      "mode": "fixed",
      "default": 60
    },
    "rating_mode": {
      "precision": 3
    },
    "icon": "fal fa-star",
    "colour": "rgb(100,100,100)",
    "label": "Podium: {{question.text}} - {{element.competition_id}}",
    "label_question": "{{question.text}}",
    "label_option": "{{option.text}}",
    "options_number": {
      "max": 4,
      "min": 3
    },
    "certification": {
      "default": false,
      "visible": true
    },
    "question": [
      {
        "label": "Text:",
        "key": "text",
        "field": "question_text",
        "mandatory": "question",
        "description": "Text is a ..."
      },
      {
        "label": "Image:",
        "key": "image_url",
        "field": "question_image",
        "mandatory": "question",
        "description": "Text is a ..."
      }
    ],
    "option": [
      {
        "label": "Text:",
        "key": "text",
        "field": "option_text",
        "mandatory": "option",
        "description": "Text is a ..."
      },
      {
        "label": "Image:",
        "key": "image_url",
        "field": "option_image",
        "mandatory": "option",
        "description": "Text is a ..."
      }
    ],
    "custom_fields": [
      {
        "name": "Custom fields",
        "properties": [
          {
            "label": "Podium",
            "key": "podium",
            "mandatory": true,
            "description": "Text is a ..."
          },
          {
            "label": "Strap line",
            "key": "strap",
            "mandatory": false,
            "default": "default value",
            "description": "Text is a ..."
          },
          {
            "label": "Rating",
            "key": "rating",
            "mandatory": true,
            "description": "Text is a ..."
          },
          {
            "label": "Competition",
            "key": "competition_id",
            "mandatory": true,
            "default": 1,
            "description": "Text is a ..."
          },
          {
            "label": "Team colour",
            "key": "team_colour",
            "mandatory": false,
            "description": "Text is a ..."
          }
        ]
      }
    ],
    "prefill": {
      "options": [
        {
          "name": "UK",
          "img": "http://example.com/images/flag/uk.png",
          "hashtag": "#voteuk"
        },
        {
          "name": "Germany",
          "img": "http://example.com/images/flag/de.png",
          "hashtag": "#votede",
          "data": [
            {
              "key": "team",
              "name": "Team",
              "value": "de"
            },
            {
              "key": "goals",
              "name": "Goals",
              "value": "1"
            }
          ]
        }
      ],
      "fields": {
        "text_during_element": "Prefilled text",
        "img": "//example.com/image.png",
        "team_colour": {
          "values": [
            {
              "name": "Pink",
              "value": "__pink"
            },
            {
              "name": "Yellow",
              "value": "__yellow"
            },
            {
              "name": "Black",
              "value": "__black"
            }
          ],
          "selected": "__black"
        }
      }
    }
  },
  {
    "name": "Athlete stats",
    "content_type": "athlete",
    "derived_from": "data",
    "duration": {
      "mode": "fixed",
      "default": 60
    },
    "colour": "#FF0000",
    "custom_fields": [
      {
        "label": "Athlete",
        "key": "athlete",
        "mandatory": true,
        "description": "Text is a ..."
      }
    ]
  }
]
All elements
Properties applicable to all types of elements
​Property
Required
​Description
name
yes
Element name as it will be presented to the Producer in Element creation UI. Must be unique.
content_type
yes
An arbitrary identifier which is passed to the App along with the data. It allows the client to identify Element type. Must be unique within the Elements spec. Must be unique.
derived_from
yes
Type of one of the core Elements which this Element is based upon.
custom_fields
​
A Field set describing extra fields for this Element.
prefill
​
Controls how this Element's data can be automatically pre-populated. Value is source object with POST request.
duration
yes
​Duration object.
label
​
Describes how Element's label should be generated.
icon
​
​Element Icon.
colour
​
Element colour on Timeline. Please see supported formats.​
Poll-like elements
Properties applicable only to poll-like elements
​
​
label_question
Describes how Element's question label should be generated.
label_option
Describes how Element's question option label should be generated.
Does not apply to powerbar.
rating_mode
Rating mode settings.
question
A Field set describing extra fields for the question.
option
A Field set describing extra fields for the option.
options_number
Min/max number of options supported by the app. Min value sets default amount of options on element form.
requires_validated_user
Controls whether user validation enabled by default and visibility of the corresponding flag on the element form.
More details here.
reveal_results
Specifies the options in “Reveal Results” dropdown for poll-like elements. This is an object with modes and default properties, where modes is a subset of [ vote close event_end never manual always ] and default is one of these values.
Note that for vote mode the results are revealed on element close if the user does not vote.
multi_vote
Toggle visibility of multi vote controls. More details here.
certification
​Voting Certification configuration on an element level. More details here. 
Prefill
Prefill allows to fill Element form with data automatically. For example a poll answer options can be populated with a list of team players automatically when a team is selected from a list. Prefill data can be defined dynamically at runtime.‌
Prefill supports additional property called dependencies. It contains references to fields. Prefill will occur if any of these fields changes.
‌Example
"prefill": {
    "url": "/prefill", 
    "service": "prefill_provider", 
    "method": "post", 
    "dependencies": ["search_term"]
}
Fields present in the prefill response will be rewritten in the form as per values in the response. This means that service must either copy values from request into response without changes or leave them out in the response in order not to overwrite changes made by the Producer.‌
Request format
​Attribute
​Description
project_id
​Project UUID.
project.custom_fields
A hash with settings of project.
event_id
Event UUID.
event.custom_fields
A hash with settings of event.
element.content_type
Element Content Type
element.custom_fields
A hash with custom_fields of element.
Example Request
{
  "project_id": "3b5a0922-eb95-401f-b8a8-ab79ec505a5a",
  "project": {
    "custom_fields": {
      "boolean": true,
      "colour": "#ff0080",
      "wysiwyg": "<p>hello<p><p>world<\/p>",
      "prompt_unstarted_event": "This event hasn't started yet",
      "prompt_live_event": "Event live",
      "prompt_finished_event": "This event has now finished",
      "image": "https://monterosa.co.uk/images/avatar.png",
      "float": 3.14159265
    }
  },
  "event_id": "8306b7fe-4ec8-4f1f-92cc-910a14ef5192",
  "event": {
    "custom_fields": {
      "text_noncloneable_default": "text_noncloneable_default",
      "text_cloneable_default": "text_cloneable_default",
      "color2": "rgba(23, 100, 240, 0.2)",
      "wysiwyg1": "<p>hello<p><p>world<\/p>"
    }
  },
  "element": {
    "content_type": "rpoll-custom",
    "custom_fields": {
      "text_during_poll": "Make your decision now...",
      "text_after_poll": "Poll closed",
      "text_after_answering": "Thanks for answering"
    }
  }
}
Response data format
Top level object can contain this optional keys
​
​
options
​
Array of objects with data for each option.
Also supports
hashtag - option filter hashtag for social voting
data - Array with data object made of key,value, name. These will be displayed in the UI under name, and will be available to the App, but will not be editable by the Producer.
fields
An array of objects with data for Element fields. Each object consists of key-value pairs, where key refers to field to be prefilled and value to value it should be prefilled with.
duration
Element duration in seconds.
Example response
{
  "duration": 40,
  "options": [
    {
      "text": "Jack",
      "image_url": "https://monterosa.com/img/jack.png",
      "hashtag": "#vote_jack"
    },
    {
      "text": "Daniel",
      "image_url": "https://monterosa.com/img/daniel.png",
      "hashtag": "#vote_daniel"
    },
    {
      "text": "Alisa",
      "image_url": "https://monterosa.com/img/alisa.png",
      "hashtag": "#vote_alisa"
    },
  ],
  "fields": {
    "text_after_poll": "Prefilled text"
  }
}
Field value format
​
​
freetext, mage, file
String value. Use “\n” for new line for freetext.
number
Integer or float number value.
boolean
true or false
list
See below.
external
Not supported.
List format
{
  "values": [
    {"name": "Pink", "value": "__pink", "preview": {"type": "video", "url": "http://example.com/preview.mp4"}},
    {"name": "Yellow", "value": "__yellow", "preview": {"type": "video", "url": "http://example.com/preview2.mp4"}},
    {"name": "Black", "value": "__black"}
   ],
   "selected": "__black"
}
Labels
Labels can be represented with a string handlebars template. Template maximum length is 1024 characters.‌
Label content is a plain text. If it contains \n then this will be replaced with <br/> when displaying within Studio.‌
There are labels on different levels:
​
​
​
Element
label
This applies to the Element itself. If not specified, label will be created using “ ” template, for example “Vote 123”.
Question
label-question
This applies to questions. For combi-polls this is an array of two elements, which contain label templates for the first and the second question.
Answer option
label-option
This applies to answer options. For combi-polls this is an array of two elements, which contain label templates for answer options for the first and the second question.
Variables interpolation
A label is usually built from values of various Element's fields by including field reference into label template. Not all field types are supported, see a table below. References are created by specifying scope.key. key is the key of the field and scope is one of these:
​
​
element
A scope for accessing top level Element fields.
question
A scope for accessing Element question fields. In case of combi-poll use array element access syntax to specify first or second question.
option
A scope for accessing Element answer option fields. In case of combi-poll use array element access syntax to specify answer options for first or second question. This scope can only be accessed within label-option labels.
When generating a label, field values are not escaped or sanitized in any way.‌
Labels
"label": "Round {{element.round_id}}"
​
"label": "Questions: {{question.text}}, {{question.body}} - {{element.contestant_name}}"
​
"label_question": "{{question.header}} | {{question.content}}"
​
"label_option": "{{question.text}} - {{option.answer}}"
Field types
The way that field value will be inserted in the label depends on its type:
Type
Representation
colour
not supported
freetext
as is, except for new line is converted to space
number
as is
external
path and selected value
image
image file name (not full URL)
file
file name (not full URL)
boolean
"true"/"false"
list
selected value
wysiwyg
not supported
For a localisable field the value in the default language is used.‌
Helpers
Conditional label template can be implemented using #if helper:‌
Check if field value is set
"{{#if element.round_id}}Round {{element.round_id}} {{/if}}{{question.text}}"
"Question not set" for empty question
"{{#if question.text}}{{question.text}} {{else}} Question not set {{/if}}"
Check if value satisfies a condition
"{{#if element.round_number '==' 3}}Last round{{else}}Round{{/if}}"
​
"{{#if element.players_count '>=' 2}}Multiplayer{{else}}Singleplayer{{/if}} game"
​
"{{#if question.score '>' '3.14'}}Winner{{/if}}
Rating mode
Prediction, trivia, regular poll Element spec can turn on “ratings mode” via rating-mode property.
"rating_mode": { "precision": 3 }
Rating value is calculated as follows and saved with specified precision.‌
(option_1_votes * 1 + option_2_votes * 2 + option_3_votes * 3 …) / total_votes‌
When enabled, rating field with latest rating value is added to element data.‌
Multi vote
Configuration of the Multi vote feature. See Multi vote page from the Developer Guide for the feature overview.
To enable multi vote feature for an element, an Element spec must include multi_vote object with optional attributes and defaults.
Core element types that support feature: poll, prediction, rpoll, trivia.
The minimal configuration that enables multi vote for an element:
"multi_vote": {}
An example of multi_vote configuration object with all available options and defaults:
"multi_vote" : {
  "max_per_user" : 5,
  "max_per_option" : 2,
  "options_selection" : {
    "min" : 1,
    "max" : 3,
    "modes" : ["at_least", "at_most", "between", "exactly"],
    "default_mode" : "between"
  }
}
Parameters
multi_vote.max_per_user
The default value for the maximum number of votes for options a user can cast overall in an answer.
Optional.
Default value 1 is used when the property is not provided or value is null.
multi_vote.max_per_option
The default value for a maximum number of votes a user can cast per option.
Optional. The corresponding UI field won't be displayed if this property is omitted.
Default value 1 is used if not specified.
Cannot be greater than multi_vote.max_per_user if it is present in the spec.
multi_vote.options_selection
Contains default values for limits on options selection. To enable limits on options selection, an Element spec must include at least empty multi_vote.options_selection object.
Supported core element types: poll, rpoll.
multi_vote.options_selection.modes
The list of available voting modes.
Optional.
Allowed array values are:
at_least - allows setting a minimum number of options required for the voting. The default value is set by multi_vote.options_selection.min.
at_most - allows setting a maximum number of options allowed for the voting. The default value is set by multi_vote.options_selection.max.
between - allows setting a maximum and a minimum number of options allowed for the voting. The default limits are set by multi_vote.options_selection.min and multi_vote.options_selection.max.
exactly - allows setting an exact number of options required for the voting. The default value is set by multi_vote.options_selection.min.
Cannot be empty or null and has to include at least one mode if specified.
System default is ["at_least", "at_most", "between", "exactly"]. It is used when multi_vote.options_selection.modes is not provided.
multi_vote.options_selection.default_mode
The default voting mode.
Optional.
It has to be one of the modes from multi_vote.options_selection.modes
multi_vote.options_selection.min
The default value for the minimum number of options required for the voting. It is used for at_least, between and exactly voting modes.
Optional.
Cannot be greater than multi_vote.options_selection.max if it is present in the spec.
multi_vote.options_selection.max
The default value for the maximum number of options allowed for the voting. It is used for at_most and between voting modes.
Optional.
App Spec reload
On App reload Studio:
Validates multi_vote block in Elements spec.
Automatically adjusts multi_vote settings for not started elements when multi_vote is added or updated. Result of an adjustment depends on exact changes in the spec.
Resets multi_vote settings for not started elements when multi_vote is removed.
Duration
Required property for all element types.
Duration configuration object has the following properties:
mode - duration mode of the element. Required.
default - default duration. Allowed and required only for "fixed" mode.
editable - defines if element duration is editable in Studio UI. Optional. Allowed values are true or false. Default value is true. Allowed only for "fixed"  mode.
"duration": {
  "mode": "fixed",
  "default": 60,
  "editable": false
}
​
"duration": {
  "mode": "flexible"
}
​
"duration": {
  "mode": "instant"
}
duration.editableaffects prefill and duration input for element's form in Studio UI.
If the value is set to false then the duration input field on the element's form is disabled and prefill is ignored for it.
The Control API doesn't support duration.editable and allows to set element's duration even ifduration.editable is false.
Modes
Following modes are supported:
"instant" - element has no duration, effectively duration zero
"fixed" - element has fixed non-zero duration
"flexible" - element automatically stretches to the end of the event
Duration mode support by element type:
all elements support "fixed" mode
poll-like elements support "fixed" and "flexible" modes
data-like elements support "fixed" and "instant" modes
Automatic adjustments
On app spec reload with updated duration mode all not yet started elements are changed to the new mode.
On element cloning the clone is created with duration mode as set by current app spec.
If duration mode changes from "instant" or "flexible" to "fixed" then element's duration is reset to default value from the app spec if default value is less than the event duration otherwise it is set to the event duration.
User validation
The platform supports a feature where a poll can be set up to only count votes from users who are validated in some way (CAPTCHA, registration, etc). Property requires_validated_user allows app developer to say whether this feature is enabled or disabled and whether it is configurable via Studio.
requires_validated_user is an optional object with two attributes default and visible.
"requires_validated_user": {
    "default": false,
    "visible": true
}
requires_validated_user.default - Boolean field, optional, default value is false.
true - user validation is enabled by default
false - user validation is disabled by default
requires_validated_user.visible - Boolean field, optional, default value is true.
true - user validation checkbox is visible on the element form
false - user validation checkbox is  not visible on the element form 
The old format when requires_validated_user is a string deprecated but still supported. The string values convert to the new format by the next rules:
"always" - requires_validated_user.default is true, requires_validated_user.visible is false
"never" - requires_validated_user.default is false, requires_validated_user.visible is false
"configurable" - requires_validated_user.default is false, requires_validated_user.visible is true
Changes in App Spec does not affect requires_validated_user flag for cloned or not started elements.
Certification
The certification configuration property can be used to configure the visibility of the Certification control on element's form and for setting the default for this field.

This configuration is optional and available only for poll-like elements. When it is not provided or when the value is an empty object then the Certification control will be present on the form but no value will be selected by default.
Field
Default
Description
default
false
Default value for certification control. false means certification is switched off. The field is optional.
visible
true
Visibility of certification control on the element form. false means the control will not be visible to the user, and default value will be used. The field is optional.
Example
To show the Certification control enabled by default the configuration may look like this:
"certification": {
  "default": true,
  "visible": true
}
To disable certification and hide the control the configuration may look like this:
"certification": {
  "default": false,
  "visible": false
}
Element icon
An icon that is used for the element on Studio UI.
Can be any Font Awesome 5.14 icon, including pro icons. The icon name must be specified as a full name including style prefix.
Example
...
"icon": "fal fa-star",
...
The default icon is used in the case when an element icon is not specified. Each base element type has its own default icon.
Base Type
Default Icon
rpoll
fal fa-list-ul
poll
fal fa-cogs
dpoll
fal fa-tachometer-alt
emo
fal fa-thumbs-up
powerbar
fal fa-signal
prediction
fal fa-futbol
trivia
fal fa-question-circle
data
fal fa-file

WYSIWYG

Event settings spec

Last modified 8mo ago

Property	Required	Description
name	yes	Element name as it will be presented to the Producer in Element creation UI. Must be unique.
content_type	yes	An arbitrary identifier which is passed to the App along with the data. It allows the client to identify Element type. Must be unique within the Elements spec. Must be unique.
derived_from	yes	Type of one of the core Elements which this Element is based upon.
custom_fields		A Field set describing extra fields for this Element.
prefill		Controls how this Element's data can be automatically pre-populated. Value is `source` object with `POST` request.
duration	yes	Duration object.
label		Describes how Element's label should be generated.
icon		Element Icon.
colour		Element colour on Timeline. Please see supported formats.


label_question	Describes how Element's question label should be generated.
label_option	Describes how Element's question option label should be generated. Does not apply to `powerbar`.
rating_mode	Rating mode settings.
question	A Field set describing extra fields for the question.
option	A Field set describing extra fields for the option.
options_number	Min/max number of options supported by the app. Min value sets default amount of options on element form.
requires_validated_user	Controls whether user validation enabled by default and visibility of the corresponding flag on the element form. More details here.
reveal_results	Specifies the options in “Reveal Results” dropdown for poll-like elements. This is an object with `modes` and `default` properties, where `modes` is a subset of [ `vote` `close` `event_end` `never` `manual` `always` ] and `default` is one of these values. Note that for `vote` mode the results are revealed on element close if the user does not vote.
multi_vote	Toggle visibility of multi vote controls. More details here.
certification	Voting Certification configuration on an element level. More details here.

Attribute	Description
project_id	Project UUID.
project.custom_fields	A hash with settings of project.
event_id	Event UUID.
event.custom_fields	A hash with settings of event.
element.content_type	Element Content Type
element.custom_fields	A hash with custom_fields of element.


options	Array of objects with data for each option. Also supports `hashtag` - option filter hashtag for social voting `data` - Array with data object made of `key`,`value`, `name`. These will be displayed in the UI under `name`, and will be available to the App, but will not be editable by the Producer.
fields	An array of objects with data for Element fields. Each object consists of `key`-`value` pairs, where `key` refers to field to be prefilled and `value` to value it should be prefilled with.
duration	Element duration in seconds.


freetext, mage, file	String value. Use “\n” for new line for `freetext`.
number	Integer or float number value.
boolean	`true` or `false`
list	See below.
external	Not supported.


Element	`label`	This applies to the Element itself. If not specified, label will be created using “ ” template, for example “Vote 123”.
Question	`label-question`	This applies to questions. For combi-polls this is an array of two elements, which contain label templates for the first and the second question.
Answer option	`label-option`	This applies to answer options. For combi-polls this is an array of two elements, which contain label templates for answer options for the first and the second question.


element	A scope for accessing top level Element fields.
question	A scope for accessing Element question fields. In case of combi-poll use array element access syntax to specify first or second question.
option	A scope for accessing Element answer option fields. In case of combi-poll use array element access syntax to specify answer options for first or second question. This scope can only be accessed within `label-option` labels.

Type	Representation
colour	not supported
freetext	as is, except for new line is converted to space
number	as is
external	path and selected value
image	image file name (not full URL)
file	file name (not full URL)
boolean	"true"/"false"
list	selected value
wysiwyg	not supported

Field	Default	Description
default	false	Default value for certification control. `false` means certification is switched off. The field is optional.
visible	true	Visibility of certification control on the element form. `false` means the control will not be visible to the user, and default value will be used. The field is optional.

Base Type	Default Icon
rpoll	fal fa-list-ul
poll	fal fa-cogs
dpoll	fal fa-tachometer-alt
emo	fal fa-thumbs-up
powerbar	fal fa-signal
prediction	fal fa-futbol
trivia	fal fa-question-circle
data	fal fa-file