Submit a request
Submit a request

Customizing the Assessment Player experience with User Interface Regions

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

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: regions.png

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.
The sections below describe different ways of configuring Items API's regions using simple layout presets and the more flexible regions configuration object.
 

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)
  1. title_element
top-right
(left to right)
  1. itemcount_element
  2. timer_element
  3. reading_timer_element
  4. pause_button
items
(top to bottom)
  1. progress_element
  2. slider_element
right
(top to bottom)
  1. save_button
  2. fullscreen_button
  3. reviewscreen_button
  4. accessibility_button
  5. calculator_button
  6. flagitem_button
  7. verticaltoc_element
  8. notepad_button (*)
  9. stickynote_addbutton (*)
  10. stickynote_visibility_button (*)
  11. drawing_mode_button (*)
  12. drawing_visibility_button (*)
bottom-right
(left to right)
  1. previous_button
  2. next_button

 (*) Requires Annotations API.

Horizontal region

"regions": "horizontal"Set the regions attribute to "horizontal".

Region Elements
top-left
(left to right)
  1. title_element
top-right
(left to right)
  1. itemcount_element
  2. timer_element
  3. reading_timer_element
  4. pause_button
items
(top to bottom)
  1. progress_element
  2. slider_element
right
(top to bottom)
  1. save_button
  2. fullscreen_button
  3. reviewscreen_button
  4. accessibility_button
  5. calculator_button
  6. flagitem_button
  7. notepad_button (*)
  8. stickynote_addbutton (*)
  9. stickynote_visibility_button (*)
  10. drawing_mode_button (*)
  11. drawing_visibility_button (*)
bottom
(left to right)
  1. previous_button
  2. horizontaltoc_element
  3. 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.

"regions": "items-only"Set the regions attribute to "items-only".

Region Elements
items
(top to bottom)
  1. slider_element

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.

 

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"
            }
        ]
    },
    ...
}; 

 

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.

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 }

 

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
Sets 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
Title / Function Type name Options & defaults
Title

The assessment title and subtitle.

title_element -
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 -
Reading Timer

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.

reading_timer_element -
Item Count

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

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

A horizontal separator that can be added to the right region.

separator_element -
Vertical Table of Contents

The vertical table of contents for the right region.

verticaltoc_element -
Horizontal Table of Contents

A horizontal arrangement of the table of contents, like used with pagination.

horizontaltoc_element -
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 -
Item Slider

The default 1-item-at-a-time view, only permitted in the items region.

slider_element
  • vertical_stretch_option: false
    Size the assessment player vertically to fit its parent container.
  • scrollable_option: false
    Size 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.
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
    Size the assessment player vertically to fit its parent container.
  • scrollable_option: false
    Size the assessment player to vertically fill the browser viewport.
Title / Function Type name Options & defaults
Pause

Pause the assessment timer.

pause_button
  • show_label_option: false
Save

Save the assessment without fully quitting or submitting.

save_button -
Submit

Fully submit and exit the assessment.

submit_button
  • enable_basic_submit_option: false
    Always display as a "Submit" button, users can submit assessment at any Item.
Next

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: false
    Always display as a "Next" button, disables automatically changing to Review Screen or Submit.
Previous

Go back to the previous Item.

previous_button
  • show_label_option: false
Accessibility

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.
Flag Item

Flag the current item for later.

flagitem_button
  • show_label_option: false
Fullscreen

Launch the assessment in fullscreen mode.

fullscreen_button -
Masking

Toggle the masking tool to cross out response options on Questions.

masking_button -
Review Screen

Open the review screen dialog.

reviewscreen_button -
Calculator

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.
Image Tool

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

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

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

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.

Notepad

Show and hide the notepad window (Annotations API).

notepad_button  -

Add Sticky Note

Add one sticky note window to the screen (Annotations API).

 stickynote_add_button  -

Show/Hide Sticky Notes

Show or hide all of the sticky notes on the screen (Annotations API).

 stickynote_visibility_button

Draw

Enable the drawing tools for making annotations on the screen (Annotations API).

 drawing_mode_button  -

Show/Hide Drawings

Show or hide all of the drawings on the screen (Annotations API).

 drawing_visibility_button  -

Try Again

Allow a student to receive another attempt at the Question in context, with a different stimulus and answer.

try_again_button  -

Line Reader

Allow a student to focus onto a section of text.

 linereader_button  

 

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

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 expandMenucollapseMenumoreTools, 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.

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)

responsive-regions.gif

 

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
        ...
    },
    ...
};
Was this article helpful?
1 out of 2 found this helpful

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