Customizing the Assessment Player experience with User Interface Regions – Learnosity Product & Developer Help

This article explains the concept of regions within the user interface of the Items API.

Overview

Learnosity's Items API user interface (UI) regions configuration allows the creation of a customized, fluid, and extensible assessment UI. All UI elements such as buttons, timers, the pager, etc. are modularized to allow placement in different regions of the assessment player.

The "regions" configuration can be added as a top level attribute of an Items API activity.

Here is an overview of the available user interface regions:

Figure 1: the regions on the screen that can be customized.

Table 1: regions and descriptions

Region name	Description
top	First visible region in the assessment player. Spans the full width of the player.
top-left	Just below the top region on the left side of the assessment player. Usually used for the assessment title.
top-right	Below the top region on the right side of the assessment player. Space permitting it shares a row with the top-left region, otherwise it stacks below. Primarily used to display essential information and controls including test time, item count, and pause. Only a few elements should be included here due to limited available width.
items	Always displayed and does not need to be specified in the initialization of the Items API. May be configured with a `slider_element` or `vertical_element` to customize the layout of the Activity's Items. See the available elements table below for more information on these options.
right	A vertical toolbar or "dock". Ideal for secondary buttons such as fullscreen, calculator, accessibility, etc. Buttons' labels are hidden when the menu is collapsed and tooltips are shown when the user hovers over a button. The verticaltoc_element is placed to the left of the toolbar when added to this region. When space is limited these controls are moved to the main menu to provide more space for the Items region.
bottom-left	On the left side of the assessment player, below the Items and right regions.
bottom-right	On the right side of the assessment player, below the Items and right regions. Space permitting it shares a row with the bottom-left region, otherwise it stacks beneath it. Alternately, if this region contains fewer than 4 elements and a verticaltoc_element is configured in the right region, then it is displayed directly below the right region.
bottom	Last visible region in the assessment player, spanning the full width of the player.

Initialization options

The sections below describe different ways of configuring Items API's regions using simple layout presets and the more flexible regions configuration object.

Layout presets

When passed as a string, the regions attribute is expected to be one of the following available presets:

Note: The "regions" attribute replaces "ui_style".

Main region

Set the regions attribute to "main".

"regions": "main"

Region	Elements
top-left (left to right)	title_element
top-right (left to right)	itemcount_element timer_element reading_timer_element pause_button
items (top to bottom)	progress_element slider_element
right (top to bottom)	save_button fullscreen_button reviewscreen_button resource_button accessibility_button calculator_button flagitem_button verticaltoc_element notepad_button () stickynote_addbutton () stickynote_visibility_button () drawing_mode_button () drawing_visibility_button (*)
bottom-right (left to right)	previous_button next_button

(*) Requires Annotations API.

Horizontal region

Set the regions attribute to "horizontal".

"regions": "horizontal"

Region	Elements
top-left (left to right)	title_element
top-right (left to right)	itemcount_element timer_element reading_timer_element pause_button
items (top to bottom)	progress_element slider_element
right (top to bottom)	save_button fullscreen_button reviewscreen_button resource_button accessibility_button calculator_button flagitem_button notepad_button () stickynote_addbutton () stickynote_visibility_button () drawing_mode_button () drawing_visibility_button (*)
bottom (left to right)	previous_button horizontaltoc_element next_button

(*) Requires Annotations API.

Horizontal fixed region

The same elements configuration as "horizontal" but the assessment player stretches to the available viewport height with a scrollbar on the Items region when necessary.

Adding scrollable_option: true to the Items element (slider_element or vertical_element) in a manual regions configuration or the region overrides achieves the same result.

Set the regions attribute to "horizontal-fixed".

"regions": "horizontal-fixed"

Per horizontal region presets.

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.

Set the regions attribute to "items-only".

"regions": "items-only"

Region	Elements
items (top to bottom)	slider_element

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 assessActivity = {
    "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 top level of the Activity initialization object allows simple overrides (i.e. add, remove, and edit) of regions, region elements, or region element options.

Note: The overrides are applied to the original configuration before any responsive transformations are performed.

Usage

Disable a region

This code will disable a region (the top-left region, in this example).

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

Add a region

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

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

Add an element to a region array

Add an element to a region Array (at the end). In this example we add a button to the right region.
Note: you can only specify one custom button using the dot notation shown (right.flagitem_button). To specify multiple custom buttons, use the array notation shown in other examples here.

"region_overrides": { "right.flagitem_button": true }

Add an element to a region array with options

Add an element to a region Array (at the end) with options. This example adds a calculator with the scientific option.

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

Remove an element from a region array

Remove an element from a region Array if the element override value is `false`.

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

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.

Properties:
position	Type: string Set which direction the element or button is floated. Some elements have different default positions in different regions. Possible values: `undefined` `"left"` `"right"` Default: `undefined`
show_label_option	Type: boolean Show the icon and text label in the button. Default: `true`
hide_label_option	Type: boolean Show only the icon in the button. The opposite of `show_label_option`. Default: `false`

Elements

Title / Function	Type name	Options & defaults
Dropdown A dropdown menu containing one or more buttons.	dropdown_element	`buttons: []` An array of button objects to be included in the dropdown. Can be any button below in the Buttons table. Example: `{ type: "dropdown_element", buttons: [ { type: "save_button" }, { type: "fullscreen_button" } ] }` Allowed regions: top, top-right.
Horizontal Table of Contents A horizontal arrangement of the table of contents, as used with pagination.	horizontaltoc_element	Allowed regions: top, top-left, top-right, bottom, bottom-left, bottom-right.
Item Count The current item number of the total. For example, the second item on an assessment with 10 items total would read "2 of 10".	itemcount_element	`start_item_option: 0` The number to start counting the current item number from, 0-indexed. `total_items_option: undefined` The number to display as the total. `question_count_option: false` Count based on the number of questions in each item. `start_question_option: 0` The number to start counting the first question from, 0-indexed. `total_questions_option: undefined` The number to display as the total. Allowed regions: top, top-right, top-left, bottom-right.
Item Slider The default one-Item-at-a-time view, only permitted in the Items region.	slider_element	`vertical_stretch_option: false` Resize the assessment player vertically to fit its parent container. `scrollable_option: false` Resize the assessment player to vertically fill the browser viewport. `warning_on_change_option: false` Show a confirmation dialog when navigating away from an Item that has not been attempted. [DEPRECATED] This option will be deprecated soon. Please use warning_on_change in the navigation of initOptions instead. Allowed regions: items.
Progress Bar A simple progress bar style indicator similar to the Item count, showing the current position in the assessment. Is only available in the Items region.	progress_element	Allowed regions: items.
Reading Timer Displays the current reading time, during which questions can be viewed but not answered. Hides automatically when the reading time ends, or if there is none configured.	reading_timer_element	Allowed regions: top, top-right, top-left, bottom-right.
Separator A horizontal separator that can be added to the right region.	separator_element	Allowed regions: menu, right.
Title The assessment title and subtitle.	title_element	Allowed regions: menu, top, top-left.
Timer A timer for the assessment, counting up or down depending on if the timer countdown option is enabled. Hidden during reading time.	timer_element	Allowed regions: top, top-right, top-left, bottom-right.
Vertical Items The vertical style Items view that shows all Items at once, only permitted in the items region.	vertical_element	`vertical_stretch_option: false` Resize the assessment player vertically to fit its parent container. `scrollable_option: false` Resize the assessment player to vertically fill the browser viewport. Allowed regions: items.
Vertical Table of Contents The vertical table of contents for the right region.	verticaltoc_element	Allowed regions: menu, right.

Buttons

Title / Function	Type name	Options & defaults
Accessibility Button Open the Accessibility options dialog for configuring color scheme, font size, and zoom.	accessibility_button	`colorscheme_option: true` Enable the "Color Scheme" tab of the accessibility dialog. `fontsize_option: true` Enable the "Font Size" tab of the accessibility dialog. `zoom_option: true` Enable the "Zoom" tab of the accessibility dialog. Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Add Sticky Note Button Add one sticky note window to the screen (Annotations API).	stickynote_add_button	Allowed regions: menu, right, top-right.
Calculator Button Toggle the visibility of a simple calculator.	calculator_button	extended_option: false Display the simple calculator extended with square root and percentage. `scientific_option: false` Display a full scientific calculator. Allowed regions: right, top-left, top-right, bottom, bottom-left, bottom-right.
Close Region Button	closeregion_button	Allowed regions: menu.
Custom Button Trigger a custom event as specified by the name in the configuration for this button.	custom_button	`options: {}` `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. Allowed regions: right, top-left, top-right, bottom, bottom-left, bottom-right.
Drawing Mode Button Enable the drawing tools for making annotations on the screen (Annotations API).	drawing_mode_button	Allowed regions: menu, right, top-right.
Flag Item Button Flag the current item for later.	flagitem_button	`show_label_option: false` Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Fullscreen Button Launch the assessment in fullscreen mode.	fullscreen_button	Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Image Tool Button Toggle the visibility of a customized Image Tool.	imagetool_button	`options: {}` `buttonicon: 'icon-generic'` The CSS class applied to the button, intended to determine the icon used. `image: ''` The URL of the image to show when visible. Also supports the Image Tool shorthand images. `label: 'imagetool'` A label bundle reference. If not a default one, it should be specified manually in the label bundle configuration. Allowed regions: right, top-left, top-right, bottom, bottom-left, bottom-right.
Line Reader Button Allow a student to focus onto a section of text.	linereader_button	Allowed regions: right, top-left, top-right, bottom, bottom-left, bottom-right.
Masking Button Toggle the masking tool to cross out response options on Questions.	masking_button	Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Next Button Proceed to the next Item of the assessment. By default when on the last item of the Activity it will display as "Review Screen" when a Review Screen button is configured or "Submit".	next_button	`'enable_basic_next_option': true` Always display as a "Next" button, disables automatically changing to Review Screen or Submit. Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Notepad Button Show and hide the notepad window (Annotations API).	notepad_button	Allowed regions: menu, top-right, right.
Pause Button Pause the assessment timer.	pause_button	`show_label_option: false` Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Previous Button Go back to the previous Item.	previous_button	`show_label_option: false` Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Protractor Button An Image Tool button that is preset for a protractor.	protractor_button	`options: {}` `buttonicon: 'icon-protractor'` The CSS class applied to the button, intended to determine the icon used. `image: 'protractor'` The URL of the image to show when visible. Also supports the Image Tool shorthand images. `label: 'protractor'` A label bundle reference. If not a default one, it should be specified manually in the label bundle configuration. Allowed regions: right, top-left, top-right, bottom, bottom-left, bottom-right.
Resource Button Allow a student to access general resource information like a video, audio, article that will assist him/her during the assessment. For more info: Creating a Resource Item Adding a Resource Item to an Activity	resource_button	Allowed regions: menu, right, top-right.
Review Screen Button Open the review screen dialog.	reviewscreen_button	Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Ruler Button An Image Tool button that is preset for a 15cm ruler.	ruler_button	`options: {}` `buttonicon: 'icon-ruler'` The CSS class applied to the button, intended to determine the icon used. `image: 'ruler-15-cm'` The URL of the image to show when visible. Also supports the Image Tool shorthand images. `label: 'ruler'` A label bundle reference. If not a default one, it should be specified manually in the label bundle configuration. Allowed regions: right, top-left, top-right, bottom, bottom-left, bottom-right.
Save Button Save the assessment without fully quitting or submitting.	save_button	Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Show/Hide Drawings Button Show or hide all of the drawings on the screen (Annotations API).	drawing_visibility_button	Allowed regions: menu, right, top-right.
Show/Hide Sticky Notes Show or hide all of the sticky notes on the screen (Annotations API).	stickynote_visibility_button	Allowed regions: menu, right, top-right.
Submit Button Fully submit and exit the assessment. Note: By default, the label for this button is "Finish".	submit_button	`false` Always display as a "Submit" button, users can submit assessment at any Item. Allowed regions: top-left, top-right, right, bottom, bottom-left, bottom-right.
Try Again Button Allow a student to receive another attempt at the Question in context, with a different stimulus and answer.	try_again_button	Allowed locations: menu, top, top-right, bottom, bottom-left.

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.

Button events

Use the 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.

const initOptions = {
    //initialize the custom button in regions
    "regions": {
        "top-right": [{
            "type": "custom_button",
            "options": {
                name: "my_custom_button", // unique button name, will be used to trigger events
                label: "Name to display", // label bundle reference, specify in config if not included
                icon_class: "test-save" // custom icon font class name
            }
        }]
    }
};

// initialize the Items app
const itemsApp = LearnosityItems.init(initOptions);

itemsApp.assessApp().on("button:my_custom_button:clicked", function () {
    console.log("This is my custom button");
});

Expand menu

The expand menu cannot be added by the user manually. It will appear at the bottom of the right region menu bar, automatically, 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.

Please check the labels expandMenu, collapseMenu, moreTools, and fewerTools.

Responsive Behavior

The regions of Items API are designed to automatically adjust based on the width of the assessment player, allowing Items API 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).

Breakpoint	Behavior
Small In containers of 480px wide or smaller.	The right region's contents are moved into the application menu, accessible using a toggle button that is placed in the top left of the assessment player at this breakpoint. The top (top, top-left, and top right) are replaced with a single top region containing the menu toggle button, item count, timer, reading timer, and pause button if they are configured. If a calculator_button is configured and any math Questions are present in the activity then the calculator button will be appended to the new top region. The bottom regions (bottom-left, bottom-right, and bottom) are replaced with a single bottom region containing only the previous and next buttons if they are configured. All unique buttons removed from other regions are added to the menu.
Medium In containers ranging from 481px to 800px wide.	The right region's contents are moved into the application menu, accessible using a toggle button that is placed in the top left of the assessment player at this breakpoint. If any of the top (top, top-left, and top right) regions contain more than four buttons, all buttons from that region are removed. If a calculator_button is configured and any math questions are present in the activity then the calculator button will be appended to the top-right region. The bottom regions (bottom-left, bottom-right, and bottom) are replaced with a single bottom region containing only the previous and next buttons if they are configured. Any buttons removed from any regions are added to the menu. All unique buttons removed from other regions are added to the menu.
Large In containers of 801px wide or larger.	No changes are made, will behave as described by the regions configuration.

Demo (animation)

How to Disable

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 itemsActivity = {
    ...

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

Behaviour of Questions

To see how Questions behave without the assessment player, see this page: Dynamic Sizing and Responsiveness for Learnosity Questions.