Elements spec

Elements spec describes the Elements supported by the App.

[
  {
    "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": {
      "url": "/prefill",
      "service": "prefill_provider",
      "method": "post",
    }
  },
  {
    "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.

Quiz-like elements

Properties applicable only to quiz-like elements

Property	Required	Description
reveal_answer_on_vote	no	Reveal answer on vote configuration.

Prefill

Prefill allows to fill Element form with data automatically based on data provided at runtime.

For example, poll answer options can be populated with a list of team players automatically when a team is selected from a list.

Prefill is automatically triggered when the form is opened. Additionally, when dependencies property is specified with the field keys, it will occur on change of any of these fields.

Configuration

An example configuration:

"prefill": {
    "url": "/prefill", 
    "service": "prefill_provider", 
    "method": "post", 
    "dependencies": ["search_term"]
}

• url - A URL where the prefill request is sent to. Must be relative to the extension root endpoint when service is specified. Required.

• service - An extension type. Optional, when provided will be used to build a URL for the prefill request.

• method - Only "post" is currently supported. Required.

• dependencies - An optional array of field keys. When it is not empty, prefill will occur not only on the initial form loading but on every change of the specified fields.

Values of all fields present in the prefill response will overwrite the form data. It means that prefill back-end should either copy values from the request into the response without changes or leave them out in the response in order not to overwrite changes made by the Creator.‌

Request

The request is sent from Studio to the prefill back-end. It contains the following body in JSON 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:

{
  "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

The response from the prefill back-end is expected to be a JSON of the format described below. All top-level object properties are optional.

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

Each field should be represented in the response JSON according to its type.

freetext - string value. Use \n escape character to insert a new line.

image, file - string value of a URL.

number - Integer or float number value.

boolean - true or false literals.

list - an object of the following structure:

{
  "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"
}

external - not supported.

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

Reveal answer on vote

Configuration of the Reveal answer on vote feature. See Reveal answer on vote page from the Developer Guide for the feature overview.

Configuration

The feature can be enabled and configured by adding reveal_answer_on_vote to elements spec.

"reveal_answer_on_vote": {
  "default": false,
  "editable": true,
  "visible": true,
}

default - optional attribute, false by default. If it is set to true, then the Reveal answer on vote feature will be enabled for the element by default. visible - optional attribute, false by default. When set to true, the Reveal answer on vote checkbox is displayed on the element form in the UI.

editable - optional attribute, false by default. If it set to true, the feature can be enabled or disabled for an element via Control API, and if visible is true, via the element form in the UI.