Initialization options

"regions": "horizontal-fixed"

Items only region

Only displays the items region. Useful for building a custom assessment UI that uses events and public methods to drive the application.

"regions": "items-only"

Regions configuration object

When passed as an object the regions configuration requires an attribute for each region being used (except the Items region, which is always rendered). The provided region attributes are expected to be an array of elements and buttons which will be rendered in the specified order.

const assessActivity = {
    /* Activity with a top-right, right and bottom-right regions */
    "regions": {
        "top-right": [ /* Elements */ ],
        "right": [ /* Elements */ ],
        "bottom-right": [ /* Elements */ ]
    },
    ...
};

Each region can have many elements; however care should be taken to ensure there is enough space to display them properly.

An element is an object with a required "type" attribute and some additional, optional attributes. For example, a "position" attribute can be set to override the left/right alignment of the element within its region, as shown below. The "type" name and other optional attributes can be found in the Elements and Buttons tables.

JSON example:

const initializationObject = {
    "config": {
        "regions": {
            "top-right": [
                {
                    "type": "pause_button",
                    "position": "right"
                },
                {
                    "type": "timer_element"
                },
                {
                    "type": "reading_timer_element"
                },
                {
                    "type": "itemcount_element",
                    "position": "right"
                }
            ],
            "right": [
                {
                    "type": "save_button"
                },
                {
                    "type": "fullscreen_button"
                },
                {
                    "type": "separator_element"
                },
                {
                    "type": "accessibility_button"
                },
                {
                    "type": "calculator_button"
                },
                {
                    "type": "verticaltoc_element"
                },
                {
                    "type": "masking_button"
                }
            ],
            "bottom-right": [
                {
                    "type": "next_button"
                },
                {
                    "type": "previous_button"
                }
            ]
        },
        ...
    }
}; 

Backwards compatibility

If an element or button is defined in the regions object or is part of a layout preset then the related navigation.show_* (e.g. show_next) will be overridden.

Region overrides

The region_overrides attribute in the initialization object allows simple overrides (i.e. to add, remove, or edit) for regions, region elements, or region element options. For example:

const initializationObject = { 

    "config": {

        "region_overrides": {

            "top-left": false,

            "bottom": [

                {

                    "type": "horizontaltoc_element"

                }

            ]

        }

    }

};

Note: 

• The overrides are applied to the original configuration before any responsive transformations are performed. 
• The items region is not supported in region_overrides or custom regions of sections. This means that even if you set the items region in your section's region or region_overrides configuration, it will be ignored by the app. The items region is only supported at the top global regions configuration level.

Usage

"region_overrides": {
    "top-left": false
}

Add a region

If the override contains a region that is not defined in the origin object, it will add the region. This example will replace the entire bottom region with the defined elements (horizontal TOC).

"region_overrides": {
    "bottom": [
        {
            "type": "horizontaltoc_element"
        }
    ]
}

Add elements to a preset region

Insert additional elements to the end of a region which will be displayed after the preset elements. In this example, we add two elements to the end of the right region, the horizontal TOC and the accessibility button.

"region_overrides": {
    "right.horizontaltoc_element": true,
    "right.accessibility_button": true
}

Add an element to a preset region with options

Add an element with options to the end of a region. This example adds a calculator with the scientific option.

"region_overrides": {
    "right.calculator_button": {
        "scientific_option": true
    }
}

Remove an element from a region

Remove an element from a region by setting the element override value to false.

"region_overrides": {
    "right.calculator_button": false
}

Here's an example of mixed usage of adding and removing elements from a region:

"region_overrides": {
    "right.horizontaltoc_element": true,
    "right.accessibility_button": false
}

Global regions configuration and regions configuration in sections

Since assessments can be divided into sections, each section can have its own individual regions configuration as well.

Note: the regions settings in combination with sections will function differently depending on the LTS version being used. These differences are explained below.

v2021.2.LTS & v2021.3.LTS 

The global regions configuration will merge the region from the first section, if it has a region configuration then it will become the new global regions configuration. The elements in the region will be rendered accordingly based on the new global regions configuration.

The regions configuration for all following sections will have the same logic as the first section. 

For example: 

{
  "sections": [
    {
      "items": [...],
      "config": {
        "regions": {
          "top": [
            {
              "type": "save_button"
            },
            {
              "type": "calculator_button"
            }
          ]
        }
      }
    },
    {
      "items": [...],
      "config": {
        "regions": {
          "right": [
            {
              "type": "save_button"
            },
            {
              "type": "flagitem_button"
            }
          ]
        }
      }
    },
    {
      "items": [...],
      "config": {
        "regions": {
          "top-right": [
            {
              "type": "save_button"
            },
            {
              "type": "next_button"
            }
          ]
        }
      }
    }
  ],
  "config": {
    "regions": {
      "top-right": [
        {
          "type": "fullscreen_button"
        },
        {
          "type": "timer_element"
        }
      ],
      "top-left": [
        {
          "type": "calculator_button"
        },
        {
          "type": "previous_button"
        },
        {
          "type": "next_button"
        }
      ]
    },
    ...
  }
}

In this case, the global regions config will merge with the first section's regions config. This means we'll see the following elements in the first section:

When navigating to the second section, we will see the following elements in section 2:

When navigating to the third section, we will see the following elements in section 3:

v2022.1.LTS and above

The global regions configuration will get replaced by the regions config in a section. If the following section has a regions config, then it will replace the global regions config.

Regions config in section will override the global sections config, if it is using the keyword region_overrides.

Note: do not use regions and region_overrides simultaneously in sections config as they might conflict with each other.

For example:

{
  "sections": [
    {
      "items": [...],
      "config": {
        "regions" : {
          "top-left": [
            {
              "type": "previous_button"
            },
            {
              "type": "next_button"
            }
          ],
          "top-right": [
            {
              "type": "save_button"
            }
          ]
        }
      }
    },
    {
      "items": [...],
      "config": {
        "region_overrides": {
          "top-right": [
            {
              "type": "itemcount_element"
            }
          ]
        }
      }
    },
    {
      "items": [...],
      "config": {
        "region_overrides": {
          "top-left.calculator_button": false,
          "top-right.fullscreen_button": false
        }
      }
    }
  ],
  "config": {
    "regions": {
      "top-right": [
        {
          "type": "fullscreen_button"
        },
        {
          "type": "timer_element"
        }
      ],
      "top-left": [
        {
          "type": "calculator_button"
        },
        {
          "type": "previous_button"
        },
        {
          "type": "next_button"
        }
      ]
    }
  }
}

In this case, the first section is using regions will replace the global regions config. See the elements below with the regions replaced from the global config:

Section 2, which has region_overrides will override the global regions config. See the elements below with the regions overridden from the global config:

Section 3, which has region_overrides will override the global regions config, see the elements below with the regions overridden from the global config:

Elements and buttons

The tables below describe the buttons and elements, along with their common properties, that are available to add to the regions. Additional options and defaults for specific types are also listed.

Elements

{
    "type": "dropdown_element",
    "buttons": [
        { "type": "save_button" },
        { "type": "fullscreen_button" }
    ]
}

Buttons

Custom buttons

Custom buttons can be added to any region and used to call customized functionality. The following options are available:

• name - the button name, determines the event that is triggered upon clicking.
• label - a label bundle reference. If not a default one, it should be specified manually in the label bundle configuration.
• icon_class - the CSS class applied to the button, intended to determine the icon used.

Use a custom button to call a provided function when clicked by listening for the event using the following format:

button:[name]:clicked

For example, clicking on "my_custom_button" will trigger the event button:my_custom_button:clicked. This event can be listened to using the Items app's on() public method.

Expand menu

The expand menu cannot be added manually. It will always appear at the bottom of the right region menu bar when the right hand region has a valid element. To see a detailed explanation of the location, see the regions overview.

When the right menu has more than seven buttons, the expand menu will be rendered as a scrollable menu. Users can use the scrollbar to show more tools.

For display customization, see the labels expandMenu, collapseMenu.

Responsive Behavior

Regions are designed to automatically adjust based on the width of the assessment player, allowing it to be optimized on-the-fly for different device types including desktops, smartphones and tablets.

Note: the breakpoint sizes below do not include the additional 10px margins on both sides of the player. For example, to activate the smallest size for the Medium breakpoint, the container size must be 501px (481px + 10px + 10px).

Demo (animation)

How to Disable Responsive Rendering in Regions

If necessary, the responsive rendering of regions can be disabled by setting the responsive_regions flag to false in the configuration section of the initialization object.

const initializationObject = {

    "config": {

        "regions": "main",
        "configuration": {
            "responsive_regions": false, // disables the responsive rendering behavior
        }

    }
};