This article explains the concept of regions within the user interface of the Items API.
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.
Figure 1: the regions on the screen that can be customized.
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.
The sections below describe different ways of configuring Items API's regions using simple layout presets and the more flexible regions configuration object.
Note: The "regions" attribute replaces "ui_style".
Set the regions attribute to "main".
"regions": "horizontal"Set the regions attribute to "horizontal".
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".
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"Set the regions attribute to "items-only".
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.
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.
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.
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.
This code will disable a region (the top-left region, in this example).
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).
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.
Add an element to a region Array (at the end) with options. This example adds a calculator with the scientific option.
Remove an element from a region Array if the element override value is `false`.
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.
Sets which direction the element or button is floated. Some elements have different default positions in different regions.
Show the icon and text label in the button.
Show only the icon in the button. The opposite of show_label_option.
The assessment title and subtitle.
A timer for the assessment, counting up or down depending on if the timer countdown option is enabled. Hidden during reading time.
Displays the current reading time, during which questions can be viewed by not answered. Hides automatically when the reading time ends or if there is none configured.
The current item number out of the total. For example the second item on an assessment with 10 items total would read "2 of 10".
The number to start counting the current item number from, 0-indexed.
The number to display as the total.
Count based on the number of questions in each item.
The number to start counting the first question from, 0-indexed.
A dropdown menu containing one or more buttons.
An array of button objects to be included in the dropdown. Can be any button below in the Buttons table.
A horizontal separator that can be added to the right region.
The vertical table of contents for the right region.
A horizontal arrangement of the table of contents, like used with pagination.
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.
The default 1-item-at-a-time view, only permitted in the items region.
Size the assessment player vertically to fit its parent container.
Size the assessment player to vertically fill the browser viewport.
Show a confirmation dialog when navigating away from an Item that has not been attempted.
The vertical style Items view that shows all Items at once, only permitted in the Items region.
Save the assessment without fully quitting or submitting.
Fully submit and exit the assessment.
Always display as a "Submit" button, users can submit assessment at any Item.
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".
Always display as a "Next" button, disables automatically changing to Review Screen or Submit.
Go back to the previous Item.
Open the Accessibility options dialog for configuring color scheme, font size, and zoom.
Enable the "Color Scheme" tab of the accessibility dialog.
Enable the "Font Size" tab of the accessibility dialog.
Enable the "Zoom" tab of the accessibility dialog.
Flag the current item for later.
Launch the assessment in fullscreen mode.
Toggle the masking tool to cross out response options on Questions.
Open the review screen dialog.
Toggle the visibility of a simple calculator.
Display the simple calculator extended with square root and percentage.
Display a full scientific calculator.
Toggle the visibility of a customized Image Tool.
The CSS class applied to the button, intended to determine the icon used.
The URL of the image to show when visible. Also supports the Image Tool shorthand images.
A label bundle reference. If not a default one, it should be specified manually in the label bundle configuration.
An Image Tool button that is preset for a 15cm ruler.
An Image Tool button that is preset for a protractor.
Trigger a custom event as specified by the name in the configuration for this button.
The button name, determines the event that is triggered upon clicking.
Show and hide the notepad window (Annotations API).
Add one sticky note window to the screen (Annotations API).
Show or hide all of the sticky notes on the screen (Annotations API).
Enable the drawing tools for making annotations on the screen (Annotations API).
Show or hide all of the drawings on the screen (Annotations API).
Allow a student to receive another attempt at the Question in context, with a different stimulus and answer.
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.
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.
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.
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.
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.
In containers ranging from 481px to 800px wide.
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.
In containers of 801px wide or larger. No changes are made, will behave as described by the regions configuration.
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.