Author API Methods
setWidget()
Set the Widget JSON of the Widget (Question or Feature) being edited in an Item.
You would want to use this method so that you can programmatically set up Questions or Features with particular preset attributes, for example.
This method accepts an object specifying a template_reference key for the template as a second argument. If this is set, the Widget is displayed within the template specified by the argument. Use that approach if you have a custom template (with hidden sections, fields, etc.) set up as reference of QuestionType
inside question_types
.
Examples
var widgetJson = {
"options": [
{ "label": "[Choice A]", "value": "0" },
{ "label": "[Choice B]", "value": "1" },
{ "label": "[Choice C]", "value": "2" }
],
"stimulus": "<p>[This is the stem.]</p>",
"type": "mcq",
"ui_style": {},
"validation": {
"scoring_type": "exactMatch",
"valid_response": {
"score": 1,
"value": [""]
}
}
};
var widgetTemplate = {
"template_reference": "908de244-5c71-4c09-b094-7fb49554f2f9"
};
var hasUpdatedWidget = authorApp.setWidget(widgetJson, widgetTemplate);
console.log(hasUpdatedWidget);
Arguments
-
widgetJson widgetJson
The new Widget JSON to apply.
-
widgetTemplate widgetTemplate
Widget template containing the template reference (case-sensitive)
Return value
Type boolean
Returns true
if successful.
Returns false
if unable to set the Widget JSON, for example, when not Widget editor view.
Type definitions
-
widgetJson object
Properties of the Widget JSON vary depending on the Question type or Feature type. See Question Types and Features Types in Questions API for more information.
-
widgetTemplate object
-
template_reference string
Widget template reference
-
-
QuestionType object
-
defaults object
Change the default values that will be populated when you load the Question Types. (e.g. you could set the default Stimulus for MCQ using this config option). In order to set a default value for new array elements, keys with empty brackets
"[]"
can be used. Extends anything that is defined inbase_question_type.defaults
.-
[key] *
-
-
dependency array
Turns provided array items to become dependent items.
To use, specify the "parent" as the first (odd) array value, then the "dependent" (child) as the next (even) array value. To set up multi-dependency, specify the parent again, with the second dependent after.
For example: if we create an array like
["options", "metadata.distractor_rationale_response_level"]
then"metadata.distractor_rationale_response_level"
is now a dependant node of"options"
. So, if an"options"
item is added or removed, a corresponding"metadata.distractor_rationale_response_level"
item will be added or removed as well.Note The dependent array item should either have no default values set, or have the same number of array entries as the parent (use the
defaults
object to do this). -
description string
Overwrites the default description for the Question Type.
-
exclude_options object
Combination of object key and array value to remove unwanted option(s) from dropdown input.
The key is the attribute path of the property. See here on how to find attribute paths. If the path has an index in it (e.g.
[0]
) then just remove that to affect all indexes.The value must be the value stored in the JSON when selected, not the dropdown text. E.g. you could remove
"xlarge"
, and"xxlarge"
fontsizes from mcq question type - see example below) or Math question type's custom action group.Note: This overrides
base_question_type.exclude_options
."question_types": { "mcq": { "exclude_options": { "ui_style.fontsize": ["xlarge", "xxlarge"] } } }
-
[optionKey] string
-
-
include_options object
Combination of object key and array values to add option(s) to dropdown input.
The key is the attribute path of the property. See here on how to find attribute paths. If the path has an index in it (e.g.
[0]
) then just remove that to affect all indexes.Note: in most cases the dropdowns show all of the specific values which the question renderer supports already, and so adding a new option wouldn't work. E.g. fontsize only supports
"small"
,"normal"
,"large"
,"xlarge"
, and"xxlarge"
, so adding another entry for say"xxxlarge"
wouldn't work as the renderer doesn't know that option.Note:
exclude_options
takes precedence, so an option will not be shown if it's included inexclude_options
too.The main use-case for this is to add a custom keypad for symbols for Math question type (see example below), but it could also be used to add additional properties to custom fields (See example below for both).
Example: Below example adds a new custom keypad for "symbols" option for
clozeformulaV2
question type only, and which adds a new custom_metadata field with 2 options, then adds 1 extra different option for bothmcq
andclozetext
."question_types": { "mcq": { "include_options": { "metadata.my_custom_field": [{ "label": "MCQ Three", "value": "3a" }] } }, "clozetext": { "include_options": { "metadata.my_custom_field": [{ "label": "Cloze Three", "value": "3b" }] } }, "clozeformulaV2": { "include_options": { "symbols": [{ "label": "Custom keypad", "value": { "label": "Custom keypad", "title": "Init option keys", "value": ["M", "\\Lambda", "T", "H", "\\kappa", "\\in", "\\gamma", "\\$", "", "", "", "", "", "", "", "", "", "", "", ""] } }] } } }, "custom_metadata": { "my_custom_field": { "description": "My custom field", "name": "my_custom_field", "type": "select", "options": [ { "label": "One", "value": "1" }, { "label": "Two", "value": "2" } ] } }
-
[optionKey] string
-
-
group_reference string
Changes the tile view group in which this question type will appear. E.g. if you created a new question type group (see the
question_type_groups
config option) called"Spoken"
, you could move the Audio question type to that group. -
hidden array
Define which attributes should be hidden in all question types.
For array type fields like
options
, you can either define a selector for a specific entry, e.g.options[0]
, or you can specify a selector targeting the whole array, e.g.options[*]
. Also use this for children of array type fields, e.g.validation.valid_response.value[*].aria_label
Extends
base_question_type.hidden
. -
hidden_search_terms array
Additional terms which can be used to search for the template in the tile view.
E.g. to get the
hotspot
question type to filter when searching for "map" or "world", set this to["map","world"]
. -
hidden_sections array
This property will extend the setting from
base_question_type
in the specified widget type. -
image string
URI - Changes the image that will appear in the tile view for this question type. If no image is defined a default image for the according question_type will be displayed.
-
image_preview_placeholder string
Define the URL of an image which is displayed as a placeholder in questions which show an image preview. The specified image is shown, if the image source of the question is empty or points to an incorrect url. Overrides
base_question_type.image_preview_placeholder
. -
name string
Changes the display name of the question type in the tile view
-
reference string
A unique reference that identifies the Question Type Template. This attribute is only applicable to
question_type_templates
. -
shown array
Define which previously hidden attributes should be shown. This is useful, if you define hidden attributes in
base_question_type.hidden
, but want to show them for a certain question type only. -
shown_sections array
This property will extend the setting from
base_question_type
in the specified widget type.
-
Related articles
- The
getWidget()
method, which allows you to get the Widget JSON of the current Widget.