[{"name":"Podium","content_type":"podium","derived_from":"rpoll","categories": ["poll","featured"],"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.
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 [ votecloseevent_endnevermanualalways ] 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.
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:
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:
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.
question
An object with values for the question fields.
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.
correct_option
A number representing correct option, starting from 1.
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:
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:
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
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
"Question not set" for empty question
Check if value satisfies a condition
Rating mode
Prediction, trivia, regular poll Element spec can turn on “ratings mode” via rating-mode property.
Rating value is calculated as follows and saved with specified precision.
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:
An example of multi_vote configuration object with all available options and defaults:
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.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 - 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:
To disable certification and hide the control the configuration may look like this:
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
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.
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.
Categories
List of element category keys that specify the categories to which the element belongs.
AI content generator settings
Element level settings for AI generator. To disable AI integration for an element where it is not relevant, the configuration may appear as follows:
