setWidget - Methods - Author API

Author API Methods


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 programatically 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.


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);


  • 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 in base_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 in exclude_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 both mcq and clozetext.

      "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.
Was this article helpful?

Did you arrive here by accident? If so, learn more about Learnosity.