Skip to content

New: Support structured feedback objects (fixes: #251) #252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joe-replin wants to merge 4 commits into
base: master
Choose a base branch
from
Open

New: Support structured feedback objects (fixes: #251) #252

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
324d76c
Support structured feedback objects for MCQ
joe-replin Feb 27, 2026
18942e1
Feedback optional, add altText, update migration
joe-replin Feb 27, 2026
64f6c74
reduce spaces in example
joe-replin Feb 27, 2026
ee5c976
Clarify feedback title fallback behavior
joe-replin Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 51 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ guide the learner’s interaction with the component.

**\_recordInteraction** (boolean) Determines whether or not the learner's answers will be recorded to the LMS via cmi.interactions. Default is `true`. For further information, see the entry for `_shouldRecordInteractions` in the README for [adapt-contrib-spoor](https://github.com/adaptlearning/adapt-contrib-spoor).

**\_items** (array): Each *item* represents one choice for the multiple choice question and contains values for **text**, **\_shouldBeSelected**, and **feedback**.
**\_items** (array): Each *item* represents one choice for the multiple choice question and contains values for **text**, **\_shouldBeSelected**, and optionally **feedback**.

>**text** (string): Text that comprises the multiple choice option.

Expand All @@ -78,30 +78,69 @@ Optional for providing alternative text, for example, to specify how a word shou

>**\_isPartlyCorrect** (boolean): Determines whether the *item* when selected marks the question as partly correct. Value can be `true` or `false`. Default is `false`.

>**feedback** (string): This attribute is used only when the value for **\_selectable** is set to `1` (i.e., radio button style questions). This text will be shown if the learner selects this item, and it is an incorrect answer.
>**feedback** (object): Used only when **\_selectable** is set to `1` (radio button style). When the learner selects this item and it is an incorrect answer, this object overrides the component-level **\_feedback** state. A plain string is also accepted (legacy) and is used as the body text only.

>>**title** (string): Feedback title for this item. Overrides the component-level `_feedback.title`.

>>**altTitle** (string): Alternative title read by screen readers if no visual title is included.

>>**body** (string): The feedback body text for this item.

>>**\_classes** (string): CSS class name(s) to be applied to the feedback panel for this item.

>>**\_imageAlignment** (string): Alignment of the graphic relative to the feedback text. Acceptable values are `left` and `right`. Defaults to `right`.

>>**\_graphic** (object): An optional image to display in the feedback panel for this item.

>>>**\_src** (string): File path (relative to the `course` folder) to the image.

>>>**alt** (string): A description of the image for screen readers.

>>>**attribution** (string): Optional text to be displayed as an attribution.

>**\_score** (number): If `_hasItemScoring` is `true`, when selected, item scores are summed to give the question score.

**\_feedback** (object): If the [**Tutor** extension](https://github.com/adaptlearning/adapt-contrib-tutor) is enabled, these various texts will be displayed depending on the submitted answer. **\_feedback**
contains values for three types of answers: **correct**, **\_incorrect**, and **\_partlyCorrect**. Some attributes are optional. If they are not supplied, the default that is noted below will be used.
**\_feedback** (object): If the [**Tutor** extension](https://github.com/adaptlearning/adapt-contrib-tutor) is enabled, these texts will be displayed depending on the submitted answer.

>**title** (string): Title text for the feedback that will be displayed when the question is submitted.
>**title** (string): Default title text shown in the feedback modal header. Per-state objects can override this with their own `title` field; if a state's `title` is empty or absent, this value is used as the fallback.

>**altTitle** (string): This will be read out by screen readers as an alternative title if no visual title is included.

>**correct** (string): Text that will be displayed when the submitted answer is correct.
>**\_classes** (string): CSS class name(s) to be applied to the feedback panel for all states. Separate multiple classes with a space.

**Per-state feedback properties:**

Each of the five properties below accepts the same feedback state object:

>**\_correct** (object): Feedback displayed when the submitted answer is correct.

>**\_incorrectFinal** (object): Feedback displayed when the submitted answer is incorrect and no more attempts are permitted.

>**\_incorrectNotFinal** (object): Feedback displayed when the submitted answer is incorrect and attempts remain. If omitted, **\_incorrectFinal** is used instead.

>**\_partlyCorrectFinal** (object): Feedback displayed when the submitted answer is partly correct and no more attempts are permitted. If omitted, **\_incorrectFinal** is used instead.

>**\_partlyCorrectNotFinal** (object): Feedback displayed when the submitted answer is partly correct and attempts remain. If omitted, **\_partlyCorrectFinal** is used instead.

Each feedback state object accepts the following properties:

>>**title** (string): Title text for this feedback state. When non-empty, overrides the top-level `title`. When empty or absent, the top-level `title` is used as a fallback.

>>**altTitle** (string): Alternative title text read out by screen readers if no visual title is included.

>>**body** (string): The feedback body text for this state.

>**\_incorrect** (object): Texts that will be displayed when the submitted answer is incorrect. It contains values that are displayed under differing conditions: **final** and **notFinal**.
>>**\_classes** (string): CSS class name(s) to be applied to the feedback panel for this state only. Separate multiple classes with a space.

>>**final** (string): Text that will be displayed when the submitted answer is incorrect and no more attempts are permitted.
>>**\_imageAlignment** (string): The alignment of the graphic relative to the feedback text. Acceptable values are `left` and `right`. Defaults to `right`.

>>**notFinal** (string): Text that will be displayed when the submitted answer is incorrect while more attempts are permitted. This is optional—if you do not supply it, the **\_incorrect.final** feedback will be shown instead.
>>**\_graphic** (object): An optional image to display in the feedback panel for this state.

>**\_partlyCorrect** (object): Texts that will be displayed when the submitted answer is partially correct. It contains values that are displayed under differing conditions: **final** and **notFinal**.
>>>**\_src** (string): File path (relative to the `course` folder) to the image. Best practice is to include the file extension.

>>**final** (string): Text that will be displayed when the submitted answer is partly correct and no more attempts are permitted. This is optional—if you do not supply it, the **\_incorrect.final** feedback will be shown instead.
>>>**alt** (string): A description of the image for screen readers.

>>**notFinal** (string): Text that will be displayed when the submitted answer is partly correct while more attempts are permitted. This is optional—if you do not supply it, the **\_incorrect.notFinal** feedback will be shown instead.
>>>**attribution** (string): Optional text to be displayed as an attribution.

### Accessibility
**Multiple Choice Question** has been assigned a descriptive label using the [aria-label](https://github.com/adaptlearning/adapt_framework/wiki/Aria-Labels) attribute: **ariaRegion**.
Expand Down
239 changes: 153 additions & 86 deletions example.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,89 +1,156 @@
{
"_id": "c-05",
"_parentId": "b-05",
"_type": "component",
"_component": "mcq",
"_classes": "",
"_layout": "left",
"title": "MCQ",
"displayTitle": "MCQ",
"body": "Which of the following options would you consider to be correct?",
"instruction": "Choose {{#if _isRadio}}one option{{else}}one or more options{{/if}} then select Submit.",
"ariaQuestion": "",
"_attempts": 1,
"_shouldDisplayAttempts": false,
"_isRandom": false,
"_hasItemScoring": false,
"_questionWeight": 1,
"_selectable": 1,
"_canShowModelAnswer": true,
"_canShowCorrectness": false,
"_canShowFeedback": true,
"_canShowMarking": true,
"_recordInteraction": true,
"_items": [
{
"text": "This is option 1 (Correct)",
"altText": "",
"_shouldBeSelected": true,
"_isPartlyCorrect": false
},
{
"text": "This is option 2",
"_shouldBeSelected": false,
"feedback": "Option two incorrect feedback",
"_isPartlyCorrect": false
},
{
"text": "This is option 3",
"_shouldBeSelected": false,
"_isPartlyCorrect": false
},
{
"text": "This is option 4",
"_shouldBeSelected": false,
"_isPartlyCorrect": false
}
],
"_feedback":{
"title": "Feedback",
"altTitle": "Alt feedback title text",
"correct": "Congratulations, this is the correct feedback.",
"_incorrect": {
"notFinal": "",
"final": "This feedback will appear if you answered the question incorrectly."
},
"_partlyCorrect": {
"notFinal": "",
"final": "This feedback will appear if you answered the question correctly."
}
},
"_comment": "You only need to include _buttons if you want to override the button labels that are set in course.json",
"_buttons": {
"_submit": {
"buttonText": "Submit",
"ariaLabel": "Select here to submit your answer."
},
"_reset": {
"buttonText": "Reset",
"ariaLabel": ""
},
"_showCorrectAnswer": {
"buttonText": "Correct Answer",
"ariaLabel": ""
},
"_hideCorrectAnswer": {
"buttonText": "My Answer",
"ariaLabel": ""
},
"_showFeedback": {
"buttonText": "Show feedback",
"ariaLabel": ""
},
"remainingAttemptsText": "attempts remaining",
"remainingAttemptText": "final attempt"
{
"_id": "c-05",
"_parentId": "b-05",
"_type": "component",
"_component": "mcq",
"_classes": "",
"_layout": "left",
"title": "MCQ",
"displayTitle": "MCQ",
"body": "Which of the following options would you consider to be correct?",
"instruction": "Choose {{#if _isRadio}}one option{{else}}one or more options{{/if}} then select Submit.",
"ariaQuestion": "",
"_attempts": 1,
"_shouldDisplayAttempts": false,
"_isRandom": false,
"_hasItemScoring": false,
"_questionWeight": 1,
"_selectable": 1,
"_canShowModelAnswer": true,
"_canShowCorrectness": false,
"_canShowFeedback": true,
"_canShowMarking": true,
"_recordInteraction": true,
"_items": [
{
"text": "This is option 1 (Correct)",
"altText": "",
"_shouldBeSelected": true,
"_isPartlyCorrect": false
},
{
"text": "This is option 2",
"_shouldBeSelected": false,
"feedback": {
"title": "Option two feedback title",
"altTitle": "",
"body": "Option two incorrect feedback",
"_classes": "",
"_imageAlignment": "right",
"_graphic": {
"_src": "",
"alt": "",
"attribution": ""
}
},
"_pageLevelProgress": {
"_isEnabled": true
"_isPartlyCorrect": false
},
{
"text": "This is option 3",
"altText": "",
"_shouldBeSelected": false,
"_isPartlyCorrect": false
},
{
"text": "This is option 4",
"altText": "",
"_shouldBeSelected": false,
"_isPartlyCorrect": false
}
],
"_feedback": {
"title": "Feedback",
"altTitle": "",
"_classes": "",
"_correct": {
"title": "Feedback",
"altTitle": "",
"body": "Congratulations, this is the correct feedback.",
"_classes": "",
"_imageAlignment": "right",
"_graphic": {
"_src": "",
"alt": "",
"attribution": ""
}
},
"_incorrectFinal": {
"title": "Feedback",
"altTitle": "",
"body": "This feedback will appear if you answered the question incorrectly.",
"_classes": "",
"_imageAlignment": "right",
"_graphic": {
"_src": "",
"alt": "",
"attribution": ""
}
},
"_incorrectNotFinal": {
"_comment": "Optional. If omitted or body is empty, _incorrectFinal is shown instead.",
"title": "Feedback",
"altTitle": "",
"body": "",
"_classes": "",
"_imageAlignment": "right",
"_graphic": {
"_src": "",
"alt": "",
"attribution": ""
}
},
"_partlyCorrectFinal": {
"title": "Feedback",
"altTitle": "",
"body": "This feedback will appear if you answered the question partly correctly.",
"_classes": "",
"_imageAlignment": "right",
"_graphic": {
"_src": "",
"alt": "",
"attribution": ""
}
},
"_partlyCorrectNotFinal": {
"_comment": "Optional. If omitted or body is empty, _partlyCorrectFinal is shown instead; if that is also absent, _incorrectFinal is used.",
"title": "Feedback",
"altTitle": "",
"body": "",
"_classes": "",
"_imageAlignment": "right",
"_graphic": {
"_src": "",
"alt": "",
"attribution": ""
}
}
},
"_comment": "You only need to include _buttons if you want to override the button labels that are set in course.json",
"_buttons": {
"_submit": {
"buttonText": "Submit",
"ariaLabel": "Select here to submit your answer."
},
"_reset": {
"buttonText": "Reset",
"ariaLabel": ""
},
"_showCorrectAnswer": {
"buttonText": "Correct Answer",
"ariaLabel": ""
},
"_hideCorrectAnswer": {
"buttonText": "My Answer",
"ariaLabel": ""
},
"_showFeedback": {
"buttonText": "Show feedback",
"ariaLabel": ""
},
"remainingAttemptsText": "attempts remaining",
"remainingAttemptText": "final attempt"
},
"_pageLevelProgress": {
"_isEnabled": true
}
}
Loading