A guide to setting up the Try Again functionality for Questions API and Assess API.
What is the Try Again functionality?
Try Again allows students to ask for another set of data for the Question they are attempting. In this case, they can click the Try Again button, and they will be given the same format of Question again, but with different values, which requires a different answer (it could be any part of the Question). The dataset of Question variations uses the existing Dynamic Content functionality.
Figure 1: how selecting Try Again changes data in the current Question
Note
Try Again only is only compatible with a subset of Questions. The supported list of Questions is:
- association
- choicematrix
- classification
- clozeassociation
- clozedropdown
- clozeformula
- formulaV2 [Deprecated]
- imageclozedropdown
- imageclozeassociationV2
- mcq
1. Create an Item with Dynamic Content
2. Configure Items API
Setting initialization options
In order for Items API to generate the dynamic data and add it to the Question JSON of each Question, you need to add the following in the initialization options:
initObj = {
"dynamic_items": {
"data_table_seed": "SOME_SEED", // optional
"try_again": {
"max_attempts": 5, // required, max 10
"random": true // optional, false default
}
}
}
Code example: Items API initialization
For the initObj
object, we have two variables of interest, dynamic_items
and try_again
.
For the dynamic_items
element, we can set the sub-element try_again: random
element to to true. This will cause to the user to be given a randomised sequence of data rows when clicking Try Again.
For the try_again
variable, max_attempts
is a required variable that sets the number of times the user can click Try Again. The maximum number of tries that can be specified is ten.
Variable | Type | Default | Required? | Description |
---|---|---|---|---|
try_again: max_attempts | integer | If the number of dataset rows is less than the defined max_attempts, then that Item will will use the number of rows available. | Yes | Sets the number of times the user can click Try Again. Dataset rows are processed sequentially by default. |
try_again: random | boolean | false | No | Changes the initial loading of data rows from the original author dataset to be random (when true). This controls how the data from the dataset is captured and brought down to the page. |
data_table_seed | string | If not defined, the random seed will use the value of the current session_id. | No | A randomising seed that will be used to generate a sequence of data rows given to students clicking Try Again. |
Table: variables specified in the Items API initialization object
Note: When using Try Again random
: if you have 50 rows in your data set and you have random: false
you have, for example, max_attempts
set to 7, then only the first 7 of the 50 rows of the data set are captured and rendered for the users. If random
is set to false, there is no reason to add any more rows to the data set at authoring time. If random
is set to true, then any user can get any seven rows from the dataset and not necessarily the same rows. A seed of the rows in each session is stored, so that they can be restored in resume mode.
The Try Again button
The Try Again button will allow the student to view the Item with a new set of data from the dataset created for it.
By default, this button is already available using the "horizontal" and "horizontal-fixed" regions presets.
initObj = {
"config": {
"regions": "horizontal" // Or "horizontal-fixed"
},
"dynamic_items": { ... }
}
Code example: regions layout preset override
If you are not using one of the regions mentioned above, to show the Try Again button on screen, it must be added to a region. See the Assess API documentation for more information on region configuration.
initObj = {
"config": {
"regions": {
"bottom-left": [{
"type": "try_again_button"
}]
}
},
"dynamic_items": { ... }
}
Code example: region configuration
Public methods
If you prefer to avoid using the default Try Again button, you can control the Dynamic Content directly through our public methods.
But to be able to do that, you will need the Item's reference. Once you know which Item you want to access, you will have four methods at your disposal:
itemsApp.assessApp().item('ITEM_REF').dynamic.previousAttempt();
itemsApp.assessApp().item('ITEM_REF').dynamic.nextAttempt();
itemsApp.assessApp().item('ITEM_REF').dynamic.currentAttemptIndex();
itemsApp.assessApp().item('ITEM_REF').dynamic.totalAttempts();
Code example: Items API public methods for Try Again
In the example above, ITEM_REF
refers to the unique reference for the Item in context, with the Question(s) that the student is answering.
Method | Description |
---|---|
previousAttempt() | Load the previous attempt data row. |
nextAttempt() | Load the next attempt data row. |
currentAttemptIndex() | Returns the index of the current attempt. |
totalAttempts() | Count the total number of attempts so far. |
Table: public methods for building custom navigation with Try Again in Items API
Public event
An event listener is provided that can be used to trigger your own functions.
itemsApp.on('dynamic:item:changed', function () {
// Do something
});
Code example: listening for an event when a dynamic Item is changed
Caveats
The Dynamic Content and “Try again” feature is not compatible with Adaptive assessments.