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.
Basics
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.
The root region
{
"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 |
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 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 |
scroll | ScrollOptions object |
If specified, the ScrollOptions has a single property as follows: Specify Omit the scroll property (or specify Required: false |
Column regions
{
"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 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 |
Tabs regions
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 |
Tab regions
{
"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 Required: false |
Example: 2 columns
{
"regions": [
{
"type": "column",
"width": 70,
"widgets": [
{
"reference": "widget_reference_1"
}
]
},
{
"type": "column",
"width": 30,
"widgets": [
{
"reference": "widget_reference_2"
}
]
}
]
}
Example: 2 tabs
{
"type": "tabs",
"regions": [
{
"type": "tab",
"label": "Tab 1",
"widgets": [
{
"reference": "widget_reference_1"
}
]
},
{
"type": "tab",
"label": "Tab 2",
"widgets": [
{
"reference": "widget_reference_2"
}
]
}
]
}
Example: combining tabs and columns
{
"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"
}
]
}
]
}