Understanding the Item Definition Structure

Data API contains an Item definition structure - a clean and consistent format for specifying the layout of Questions and Features within an Item. The Item definition makes it easy to create, import and update Items with advanced layouts via Data API. Single column and side-by-side layouts as well as tabs and scrolling panels can all be created programmatically using the expressive definition structure.

Author API v1 and Data API v1 both use the same Item definition, so your Items are fully interoperable whether you bulk upload them or use the authoring tools.

The Item definition determines the Item's layout everywhere it is rendered to a user: in an Items API Activity, in Author API, or in Reports API, on desktop, tablet and mobile.

The Item definition is stored in the definition property against the Item. The definition is returned with all Items retrieved from Data API v1's itembank/items endpoint . You must specify an Item definition when you create or update Items via Data API v1.

The Item definition is specified as one or more nested objects, representing regions and a list of widgets (questions and/or features) they contain. Here's a sample Item demonstrating the simplest kind of Item definition - a single root region and a list of widgets. The two widgets will be rendered in a single column layout, in the same order they appear in the array.

{
    "reference": "5b8b9d40-f03b-4df3-b276-84eef5580431",
    "status": "unpublished",
    "definition": {
        "widgets": [
            {
                "reference": "1a52f377-0db1-4aed-818c-866f684bb088"
            },
            {
                "reference": "2b21eca6-37af-4272-950a-fd9c472b2290"
            }
        ]
    },
    "questions": [
        {
            "reference": "2b21eca6-37af-4272-950a-fd9c472b2290",
            "type": "clozeassociation"
        }
    ],
    "features": [
        {
            "reference": "1a52f377-0db1-4aed-818c-866f684bb088",
            "type": "sharedpassage"
        }
    ]
}

There are different types of regions to support more complex layouts. The currently supported region types are root, column and tab. Each region type may contain either:

  • A set of widgets (rendered vertically in a root, column or tab region); OR
  • A set of nested regions, which must all share the same type. Use multiple layers of nesting to achieve combinations of columns and tabs.

 

The following sections cover the usage and behaviour of the different region types.

{
    "regions": [],
    "widgets": [
        {
            "reference": "widget_reference_1"
        },
        {
            "reference": "widget_reference_2"
        }
    ],
    "vertical_divider": false,
    "scroll": {
        "enabled": false
    }
}

The root region is always at the top level of the Item definition. Its rendering behaviour is designed to easily accommodate the most common Item layouts:

  • If the widgets array is specified, those widgets will be rendered in a single vertical column, in the same order they are listed in the array.
  • If the regions array is specified as a list of column regions, the columns are rendered side-by-side.
  • If the regions array is specified as a list of tab regions, the tabs will occupy the full width and height of the Item.

 

The vertical_divider and scroll properties can only be set on the root region. They globally determine the behaviour for all regions on the Item.

Property Type Description
type `"root"`

Required: false
Default: "root"

regions array of Region objects

Nested column or tab regions. The given Region objects must all share the same type.

Required: false

widgets array of IncludedWidget objects

Each IncludedWidget object contains a reference property indicating the reference of the widget to include. Widgets are rendered in a vertical stack, in the same order they appear in the widgets array.

Required: false

vertical_divider boolean

Specify true to render a vertical divider between all column regions in the Item. Enabling this option on the root region affects all descendent regions.

Required: false
Default: false

scroll ScrollOptions object

If specified, the ScrollOptions has a single property as follows:{"enabled": true}

Specify "enabled": true to enable scrolling on all regions in the Item. If the content of a region is taller than the height allocated for the Item, the region will become a scrollable panel.

Omit the scroll property (or specify"enabled": false ) to force the Item to expand to accommodate the full height of the content.

Required: false

{
    "type": "column",
    "regions": [],
    "widgets": [
        {
            "reference": "widget_reference_1"
        },
        {
            "reference": "widget_reference_2"
        }
    ],
    "width": 50
}

Column regions subdivide their parent region into a set of side-by-side columns. Any parent region may contain either 1 or 2 columns. Widgets included in a column region will be rendered in a vertical stack, in the same order they appear in the widgets array.

 

Property Type Description
type "column" Required: true
regions array of Region objects

Nested column or tab regions. The given Region objects must all share the same type.

Required: false

widgets array of IncludedWidget objects

Each IncludedWidget object contains a reference property indicating the reference of the widget to include. Widgets are rendered in a vertical stack, in the same order they appear in the widgets array.

Required: false

width int

Controls the width of this column, as a percentage of the width of the parent region. Allowed values are 50, 30, 40, 60, 70, 100. The width value of sibling columns must sum to 100.

Required: false
Default: 100

A tabs region acts as a required wrapper for grouping tabs - individual tabs will render standalone without this defined parent. The wrapper will occupy the full width and height of the parent region, and will provide the navigation element for displaying tabs.

{
    "type": "tabs",
    "regions": [
        {
            "type": "tab",
            ...
        },
        {
            "type": "tab",
            ...
        }
    ]
}
Property Type Description
type "tabs" Required: true
regions array of Region objects

Nested column or tab regions. The given Region objects must all share the same type.

Required: true

{
    "type": "tab",
    "label": "tab-1",
    "regions": [],
    "widgets": [
        {
            "reference": "widget_reference_1"
        },
        {
            "reference": "widget_reference_2"
        }
    ]
}

All sibling tab regions will be rendered as a set of tabs within their parent region. The set of tabs will occupy the full width and height of their parent region. Widgets included in a tab region will be rendered as a vertical stack within the tab's panel.

 

Property Type Description
type "tab" Required: true
label string

Label to be displayed for this tab.

Required: true

regions array of Region objects

Nested column or tab regions. The given Region objects must all share the same type.

Required: false

widgets array of IncludedWidget objects

Each IncludedWidget object contains a reference property indicating the reference of the widget to include. Widgets are rendered in a vertical stack, in the same order they appear in the widgets array.

Required: false

{
    "regions": [
        {
            "type": "column",
            "width": 70,
            "widgets": [
                {
                    "reference": "widget_reference_1"
                }
            ]
        },
        {
            "type": "column",
            "width": 30,
            "widgets": [
                {
                    "reference": "widget_reference_2"
                }
            ]
        }
    ]
}
{
"type": "tabs", "regions": [ { "type": "tab", "label": "Tab 1", "widgets": [ { "reference": "widget_reference_1" } ] }, { "type": "tab", "label": "Tab 2", "widgets": [ { "reference": "widget_reference_2" } ] } ] }
{
    "regions": [
        {
            "type": "column",
            "width": 60,
            "regions": [
                {
                    "type": "tabs",
                    "regions": [
                        {
                            "type": "tab",
                            "label": "Tab 1",
                            "widgets": [
                                {
                                    "reference": "widget_reference_1"
                                }
                            ]
                        },
                        {
                            "type": "tab",
                            "label": "Tab 2",
                            "widgets": [
                                {
                                    "reference": "widget_reference_2"
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "type": "column",
            "width": 40,
            "widgets": [
                {
                    "reference": "widget_reference_3"
                }
            ]
        }
    ]
}
Was this article helpful?

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