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) |
|
top-right (left to right) |
|
items (top to bottom) |
|
right (top to bottom) |
|
bottom-right (left to right) |
|
(*) Requires Annotations API.
Horizontal region
Set the regions attribute to "horizontal"
.
"regions": "horizontal"
Region | Elements |
---|---|
top-left (left to right) |
|
top-right (left to right) |
|
items (top to bottom) |
|
right (top to bottom) |
|
bottom (left to right) |
|
(*) 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.
"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) |
|
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
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:
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 |
Example:
Allowed regions:
|
Horizontal Table of Contents A horizontal arrangement of the table of contents, as used with pagination. |
horizontaltoc_element |
Allowed regions:
|
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 |
Allowed regions:
|
Item Slider The default one-Item-at-a-time view, only permitted in the Items region. |
slider_element |
Allowed regions:
|
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:
|
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:
|
Separator A horizontal separator that can be added to the right region. |
separator_element |
Allowed regions:
|
Title The assessment title and subtitle. |
title_element |
Allowed regions:
|
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:
|
Vertical Items The vertical style Items view that shows all Items at once, only permitted in the items region. |
vertical_element |
Allowed regions:
|
Vertical Table of Contents The vertical table of contents for the right region. |
verticaltoc_element |
Allowed regions:
|
Buttons
Title / Function | Type name | Options & defaults |
---|---|---|
Accessibility Button Open the Accessibility options dialog for configuring color scheme, font size, and zoom. |
accessibility_button |
Allowed regions:
|
Add Sticky Note Button Add one sticky note window to the screen (Annotations API). |
stickynote_add_button |
Allowed regions:
|
Calculator Button Toggle the visibility of a simple calculator. |
calculator_button |
Allowed regions:
|
Close Region Button |
closeregion_button | Allowed regions:
|
Custom Button Trigger a custom event as specified by the name in the configuration for this button. |
custom_button |
Allowed regions:
|
Drawing Mode Button Enable the drawing tools for making annotations on the screen (Annotations API). |
drawing_mode_button |
Allowed regions:
|
Flag Item Button Flag the current item for later. |
flagitem_button |
Allowed regions:
|
Fullscreen Button Launch the assessment in fullscreen mode.
|
fullscreen_button |
Allowed regions:
|
Image Tool Button Toggle the visibility of a customized Image Tool. |
imagetool_button |
Allowed regions:
|
Line Reader Button Allow a student to focus onto a section of text. |
linereader_button |
Allowed regions:
|
Masking Button Toggle the masking tool to cross out response options on Questions. |
masking_button |
Allowed regions:
|
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 |
Allowed regions:
|
Notepad Button Show and hide the notepad window (Annotations API). |
notepad_button |
Allowed regions:
|
Pause Button Pause the assessment timer. |
pause_button |
Allowed regions:
|
Previous Button Go back to the previous Item. |
previous_button |
|
Protractor Button An Image Tool button that is preset for a protractor. |
protractor_button |
Allowed regions:
|
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: |
resource_button |
Allowed regions:
|
Review Screen Button Open the review screen dialog. |
reviewscreen_button |
Allowed regions:
|
Ruler Button An Image Tool button that is preset for a 15cm ruler. |
ruler_button |
Allowed regions:
|
Save Button Save the assessment without fully quitting or submitting. |
save_button |
Allowed regions:
|
Show/Hide Drawings Button
Show or hide all of the drawings on the screen (Annotations API). |
drawing_visibility_button | Allowed regions:
|
Show/Hide Sticky Notes
Show or hide all of the sticky notes on the screen (Annotations API). |
stickynote_visibility_button | Allowed regions:
|
Submit Button Fully submit and exit the assessment. |
submit_button |
Allowed regions:
|
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:
|
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 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. |
|
Medium In containers ranging from 481px to 800px wide. |
|
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
...
},
...
};