Usage and Tips - adaptlearning/adapt-contrib-assessmentResults GitHub Wiki

Usage

To Do: Add bullets describing situations Assessment Results is good at addressing.

Layouts

Single or spanned (full width).

Mobile fall-back

If spanned, it will resize to a single width

Configuration in the Adapt Framework

Below is a selection of code from course.json. We'll see how it controls the values displayed in the component. Please note that the texts assigned to _comment are meant to guide you; they are not used by the Adapt framework.

"displayTitle": "Results",
"body": "",
"instruction": "",
"_retry": {
    "button": "Retry Assessment",
    "_comment": "use {{attempts}}, {{attemptsSpent}} and {{attemptsLeft}} to display attempts",
    "feedback": ""
    },
"_comment": "use {{score}}, {{maxScore}} and {{scoreAsPercent}} to display score and percentage",
"_completionBody": "{{{feedback}}}",
"_bands": [
   {
	"_score": 0,
	"feedback": "You didn’t pass, achieving a score of {{scoreAsPercent}}%.<br><br>You didn’t do so well in the Adapt assessment demo, but don’t worry. There’s lots of information about the Adapt basics on our site. We’d also suggest you pay a visit to the forums and ask our ever helpful community to answer any questions that you might have.",
	"_allowRetry": true
    },
    {
	"_score": 40,
	"feedback": "You didn’t pass, achieving a score of {{scoreAsPercent}}%.<br><br>You already know some of the Adapt basics but please explore our site for more information. Also pay a visit to the forums and ask our ever helpful community to answer any questions that you might have.",
	"_allowRetry": true
    },
    {
	"_score": 70,
	"feedback": "You passed, achieving a score of {{scoreAsPercent}}%.<br><br>You’re clearly already pretty knowledgeable about Adapt so, if you haven’t already, please consider sharing your expertise on the Adapt community forums.",
	"_allowRetry": true
    },
    {
	"_score": 100,
	"feedback": "You passed, achieving a score of {{scoreAsPercent}}%.<br><br>You’re clearly already a black belt in Adapt! If you haven’t already, please consider sharing your expertise on the Adapt community forums.",
	"_allowRetry": false
    }
],

[To Do: Compare feedback with no _bands to feedback with _bands.]
sample assessment results component

In the image to the right, numbers are paired with the text's source attributes as follows:

  1. _displayTitle
  2. _bands.feedback
  3. {{scoreAsPercent}}
  4. _retry.button

The body attribute is only useful if you choose to display the component ("_isVisibleBeforeCompletion": true) before the learner has completed the assessment. This might be helpful in some courses, but it is not common. Once the assessment has been completed, the body attribute will be replaced by the _completionBody.

_completionBody should always be supplied. There are two techniques for using it. The first way is to supply static text, for example, "Thank you for completing the assessment." This text will be displayed no matter the score. The second technique employs a variable associated with scoring bands to present different texts to different range of scores. This is the technique configured in the JSON sample above.

When the variable {{{feedback}}} is assigned to _completionBody, Adapt locates the _band that encompasses the learner's score. Then Adapt replaces the variable with the text assigned to the band's feedback. This way you tailor feedback to the learner's performance. Let's look in more detail at how to configure this technique.

You can set as many _bands as you need, but each will have the same three attributes: _score, feedback, and _allowRetry. _score indicates the upper limit of the range and is inclusive. Whether the _score represents the raw score or a percentile is determined by how the assessment was configured.

_allowRetry determines whether performance at this level permits the learner to attempt the assessment again. The number of attempts that is allowed is set in the Assessment, not in Assessment Results. However, if the learner's performance matches a _band configured with "_allowRetry": false, no further attempts will be permitted. This setting will override the number of attempts configured in Assessment.

feedback, although invoked by the variable {{{feedback}}}, can itself utilize some variables. {{score}}, {{maxScore}}, and {{scoreAsPercent}} make an appearance in the sample JSON in the value of _comment to remind you they are available for your use. You can use them as you construct your feedback texts. Just as {{{feedback}}} is replaced by the value of feedback, {{score}} will be replaced by the learner's raw score; {{maxScore}} will be replaced by the maximum score achievable; and {{scoreAsPercent}} will be replaced by the learner's raw score converted to a percentage of the max score possible.

In practice you can compose the feedback, then switch in the variables. For example, let's work with an assessment of 10 questions. We want learners who answer 6 to 8 question correctly to see this kind of feedback: "You answered correctly 7 out of 10 questions. That's 70%." We simply replace the data that can change from learner to learner with variables: "You answered correctly {{score}} out of {{maxScore}} questions. That's {{scoreAsPercent}}%." Two details are worth pointing out. First, notice that it was necessary to append % to {{scoreAsPercent}} since the variable presents the number exclusively. And secondly, you have the option of not replacing "10" with a variable. Once this course is published, the assessment will always have 10 questions. However, including it during course development can help since content is likely to change during this phase. With the variable in place, the feedback does not need to be rewritten when the number of questions is changed.

Tips

Here are some techniques for getting the most from Assessment Results:

⚠️ **GitHub.com Fallback** ⚠️