Skip to content

P
problem-builder
Commit 4e3006d6 by Braden MacDonald
Options

Dashboard documentation

parent a854a0d8
Showing with 278 additions and 178 deletions
README.md
......@@ -23,6 +23,8 @@ It supports:
next step. Provides a link to the next step to the student.
* **Tables**, which allow to present answers from the student to
free-form answers in a concise way. Supports custom headers.
* **Dashboards**, for displaying a summary of the student's answers
to multiple choice questions. [Details](doc/Dashboard.md)
The screenshot shows an example of a mentoring block containing a
free-form question, two MCQs and one MRQ.
......@@ -54,184 +56,7 @@ settings.
Usage
-----
When you add the `Mentoring` component to a course in the studio, the
built-in editing tools guide you through the process of configuring the
block and adding individual questions.
### Mentoring modes
There are 2 mentoring modes available:
* *standard*: Traditional mentoring. All questions are displayed on the
page and submitted at the same time. The students get some tips and
feedback about their answers. This is the default mode.
* *assessment*: Questions are displayed and submitted one by one. The
students don't get tips or feedback, but only know if their answer was
correct. Assessment mode comes with a default `max_attempts` of `2`.
Below are some LMS screenshots of a mentoring block in assessment mode.
Question before submitting an answer:
![Assessment Step 1](doc/img/assessment-1.png)
Question after submitting the correct answer:
![Assessment Step 2](doc/img/assessment-2.png)
Question after submitting a wrong answer:
![Assessment Step 3](doc/img/assessment-3.png)
Score review and the "Try Again" button:
![Assessment Step 4](doc/img/assessment-4.png)
### Free-form Question
Free-form questions are represented by a "Long Answer" component.
Example screenshot before answering the question:
![Answer Initial](doc/img/answer-1.png)
Screenshot after answering the question:
![Answer Complete](doc/img/answer-2.png)
You can add "Long Answer Recap" components to mentoring blocks later on
in the course to provide a read-only view of any answer that the student
entered earlier.
The read-only answer is rendered as a quote in the LMS:
![Answer Read-Only](doc/img/answer-3.png)
### Multiple Choice Questions (MCQ)
Multiple Choice Questions can be added to a mentoring component and
have the following configurable options:
* Question - The question to ask the student
* Message - A feedback message to display to the student after they
have made their choice.
* Weight - The weight is used when computing total grade/score of
the mentoring block. The larger the weight, the more influence this
question will have on the grade. Value of zero means this question
has no influence on the grade (float, defaults to `1`).
* Correct Choice - Specify which choice[s] is considered correct. If
a student selects a choice that is not indicated as correct here,
the student will get the question wrong.
Using the Studio editor, you can add "Custom Choice" blocks to the MCQ.
Each Custom Choice represents one of the options from which students
will choose their answer.
You can also add "Tip" entries. Each "Tip" must be configured to link
it to one or more of the choices. If the student chooses a choice, the
Screenshot: Before attempting to answer the questions:
![MCQ Initial](doc/img/mcq-1.png)
While attempting to complete the questions:
![MCQ Attempting](doc/img/mcq-2.png)
After successfully completing the questions:
![MCQ Success](doc/img/mcq-3.png)
#### Rating MCQ
When constructing questions where the student rates some topic on the
scale from `1` to `5` (e.g. a Likert Scale), you can use the Rating
question type, which includes built-in numbered choices from 1 to 5
The `Low` and `High` settings specify the text shown next to the
lowest and highest valued choice.
Rating questions are a specialized type of MCQ, and the same
instructions apply. You can also still add "Custom Choice" components
if you want additional choices to be available such as "I don't know".
### Self-assessment Multiple Response Questions (MRQ)
Multiple Response Questions are set up similarly to MCQs. The answers
are rendered as checkboxes. Unlike MCQs where only a single answer can
be selected, MRQs allow multiple answers to be selected at the same
time.
MRQ questions have these configurable settings:
* Question - The question to ask the student
* Required Choices - For any choices selected here, if the student
does *not* select that choice, they will lose marks.
* Ignored Choices - For any choices selected here, the student will
always be considered correct whether they choose this choice or not.
* Message - A feedback message to display to the student after they
have made their choice.
* Weight - The weight is used when computing total grade/score of
the mentoring block. The larger the weight, the more influence this
question will have on the grade. Value of zero means this question
has no influence on the grade (float, defaults to `1`).
* Hide Result - If set to True, the feedback icons next to each
choice will not be displayed (This is false by default).
The "Custom Choice" and "Tip" components work the same way as they
do when used with MCQs (see above).
Screenshot - Before attempting to answer the questions:
![MRQ Initial](doc/img/mrq-1.png)
While attempting to answer the questions:
![MRQ Attempt](doc/img/mrq-2.png)
After clicking on the feedback icon next to the "Its bugs" answer:
![MRQ Attempt](doc/img/mrq-3.png)
After successfully completing the questions:
![MRQ Success](doc/img/mrq-4.png)
### Tables
The mentoring table allows you to present answers to multiple
free-form questions in a concise way. Once you create an "Answer
Recap Table" inside a Mentoring component in Studio, you will be
able to add columns to the table. Each column has an optional
"Header" setting that you can use to add a header to that column.
Each column can contain one or more "Answer Recap" element, as
well as HTML components.
Screenshot:
![Mentoring Table](doc/img/mentoring-table.png)
### Maximum Attempts
You can set the number of maximum attempts for the unit completion by
setting the Max. Attempts option of the Mentoring component.
Before submitting an answer for the first time:
![Max Attempts Before](doc/img/max-attempts-before.png)
After submitting a wrong answer two times:
![Max Attempts Reached](doc/img/max-attempts-reached.png)
### Custom tip popup window size
You can specify With and Height attributes of any Tip component to
customize the popup window size. The value of those attribute should
be valid CSS (e.g. `50px`).
See [Usage Instructions](doc/Usage.md)
Workbench installation and settings
-----------------------------------
......
doc/Dashboard.md 0 → 100644
"Dashboard" Self-Assessment Summary Block
=========================================
A "Dashboard" XBlock provides a concise way to summarize a student's answers to
groups of multiple choice questions.
You configure it like this, by pasting in the `url_name`s of some Problem
Builder ("Mentoring") blocks:
![Screen shot of Dashboard XBlock configuration](img/dashboard-configuration.png)
And it will then look like this (after a student has submitted their answers):
![Screen shot of a Dashboard XBlock](img/dashboard-example.png)
Visual Representation
---------------------
The Dashboard also supports an optional visual representation. This is a
powerful feature, but setting it up is quite involved.
The end result is shown below. You can see a diagram, in which a colored arrow
appears as the student works through the various "Steps". Each "Step" is one
mentoring block, which contains several multiple choice questions. Based on the
average value of the student's choices, the step is given a color.
In this example, steps that have not been attempted are transparent, steps that
have been attempted but with an average less than two are grey, and steps with
an average higher than two are green.
![Screen shot of visual representation](img/dashboard-visual.png)
To achieve the result shown above requires a set of "stacked" image files (one
for each step), as well as an overlay image (in this case, the overlay image
contains all the text).
To build this example, the images used look like this:
![Images Used](img/dashboard-visual-instructions.png)
The block was configured to use these images as follows:
![Screen shot of visual representation rule configuration](img/dashboard-visual-config.png)
Notice that step 2 has turned green due to the default rule "hueRotate 280" for
any steps with an average above 2, and the first step has a blurred, grey
background due to the first rule for average values less than 2.
The **Visual Representation Settings** used to define the visual representation
must be in JSON format. The supported entries are:
* **`"images"`**: A list of image URLs, one per PB block, in the same order as
the 'blocks' list (the list of `url_name`s described above). If the images you
wish to use are on your computer, first upload them to the course's "Files and
Uploads" page. You can then find the URL for each image listed on that page.
Note that each URL must start with "http://" or "https://".
* All images listed here will be layered on top of each other, and can be
colorized, faded, etc. based on the average value of the student's choices
for the corresponding group of MCQs.
* **`"overlay"`**: (Optional) The URL of an image to be drawn on top of the
layered images, with no effects applied.
* **`"background"`**: (Optional) The URL of an image to be drawn behind the
layered images, with no effects applied.
* **`"colorRules"`**: (Optional) The rules used to determine how the student's
average choice values affect each layer's image. Each rule is evaluated in
order, and the first matching rule is used. Each rule is a JSON object
(`{ ... }`) that may consist of any of the following optional entries.
* `if`: An optional expression involving `x` (the student's average choice
value). If this is true, then this rule will be used. If this is false, the
rule will not be used. If no `if` clause is set, the rule will always be
used, unless an earlier rule matched first.
Examples:
- `"if": "x > 3"`
- `"if": "0 < x < 1"`
- `"if": "(x > 3) and (x < 6 or x > 100)"`
* `hueRotate`: If this rule matches, adjust the color of all parts of the
image that have some saturation. In the above example, this is used to
change from a turquiose color to a light green. Valid values are between 0
(no change) and 360. Note that this effect will *not* affect any parts of
the image have no saturation (i.e. are white, black, or any shade of grey).
Examples:
- `"hueRotate": "180"`
- `"hueRotate": "x * 30"`
* `blur`: If this rule matches, apply a gaussian blur to blur this layer's
image. The standard deviation of the blur must be specified.
Examples:
- `"blur": "3"`
- `"blur": "x"`
* `saturate`: If this rule matches, adjust the saturation of the image. `1`
means no change, and `0` means fully desaturated. Valid values are between
zero and one.
Examples:
- `"saturate": "0.2"`
doc/Usage.md 0 → 100644
Mentoring Block Usage
=====================
When you add the `Mentoring` component to a course in the studio, the
built-in editing tools guide you through the process of configuring the
block and adding individual questions.
### Mentoring modes
There are 2 mentoring modes available:
* *standard*: Traditional mentoring. All questions are displayed on the
page and submitted at the same time. The students get some tips and
feedback about their answers. This is the default mode.
* *assessment*: Questions are displayed and submitted one by one. The
students don't get tips or feedback, but only know if their answer was
correct. Assessment mode comes with a default `max_attempts` of `2`.
Below are some LMS screenshots of a mentoring block in assessment mode.
Question before submitting an answer:
![Assessment Step 1](img/assessment-1.png)
Question after submitting the correct answer:
![Assessment Step 2](img/assessment-2.png)
Question after submitting a wrong answer:
![Assessment Step 3](img/assessment-3.png)
Score review and the "Try Again" button:
![Assessment Step 4](img/assessment-4.png)
### Free-form Question
Free-form questions are represented by a "Long Answer" component.
Example screenshot before answering the question:
![Answer Initial](img/answer-1.png)
Screenshot after answering the question:
![Answer Complete](img/answer-2.png)
You can add "Long Answer Recap" components to mentoring blocks later on
in the course to provide a read-only view of any answer that the student
entered earlier.
The read-only answer is rendered as a quote in the LMS:
![Answer Read-Only](img/answer-3.png)
### Multiple Choice Questions (MCQ)
Multiple Choice Questions can be added to a mentoring component and
have the following configurable options:
* Question - The question to ask the student
* Message - A feedback message to display to the student after they
have made their choice.
* Weight - The weight is used when computing total grade/score of
the mentoring block. The larger the weight, the more influence this
question will have on the grade. Value of zero means this question
has no influence on the grade (float, defaults to `1`).
* Correct Choice - Specify which choice[s] is considered correct. If
a student selects a choice that is not indicated as correct here,
the student will get the question wrong.
Using the Studio editor, you can add "Custom Choice" blocks to the MCQ.
Each Custom Choice represents one of the options from which students
will choose their answer.
You can also add "Tip" entries. Each "Tip" must be configured to link
it to one or more of the choices. If the student chooses a choice, the
Screenshot: Before attempting to answer the questions:
![MCQ Initial](img/mcq-1.png)
While attempting to complete the questions:
![MCQ Attempting](img/mcq-2.png)
After successfully completing the questions:
![MCQ Success](img/mcq-3.png)
#### Rating MCQ
When constructing questions where the student rates some topic on the
scale from `1` to `5` (e.g. a Likert Scale), you can use the Rating
question type, which includes built-in numbered choices from 1 to 5
The `Low` and `High` settings specify the text shown next to the
lowest and highest valued choice.
Rating questions are a specialized type of MCQ, and the same
instructions apply. You can also still add "Custom Choice" components
if you want additional choices to be available such as "I don't know".
### Self-assessment Multiple Response Questions (MRQ)
Multiple Response Questions are set up similarly to MCQs. The answers
are rendered as checkboxes. Unlike MCQs where only a single answer can
be selected, MRQs allow multiple answers to be selected at the same
time.
MRQ questions have these configurable settings:
* Question - The question to ask the student
* Required Choices - For any choices selected here, if the student
does *not* select that choice, they will lose marks.
* Ignored Choices - For any choices selected here, the student will
always be considered correct whether they choose this choice or not.
* Message - A feedback message to display to the student after they
have made their choice.
* Weight - The weight is used when computing total grade/score of
the mentoring block. The larger the weight, the more influence this
question will have on the grade. Value of zero means this question
has no influence on the grade (float, defaults to `1`).
* Hide Result - If set to True, the feedback icons next to each
choice will not be displayed (This is false by default).
The "Custom Choice" and "Tip" components work the same way as they
do when used with MCQs (see above).
Screenshot - Before attempting to answer the questions:
![MRQ Initial](img/mrq-1.png)
While attempting to answer the questions:
![MRQ Attempt](img/mrq-2.png)
After clicking on the feedback icon next to the "Its bugs" answer:
![MRQ Attempt](img/mrq-3.png)
After successfully completing the questions:
![MRQ Success](img/mrq-4.png)
### Tables
The mentoring table allows you to present answers to multiple
free-form questions in a concise way. Once you create an "Answer
Recap Table" inside a Mentoring component in Studio, you will be
able to add columns to the table. Each column has an optional
"Header" setting that you can use to add a header to that column.
Each column can contain one or more "Answer Recap" element, as
well as HTML components.
Screenshot:
![Mentoring Table](img/mentoring-table.png)
### Maximum Attempts
You can set the number of maximum attempts for the unit completion by
setting the Max. Attempts option of the Mentoring component.
Before submitting an answer for the first time:
![Max Attempts Before](img/max-attempts-before.png)
After submitting a wrong answer two times:
![Max Attempts Reached](img/max-attempts-reached.png)
### Custom tip popup window size
You can specify With and Height attributes of any Tip component to
customize the popup window size. The value of those attribute should
be valid CSS (e.g. `50px`).
### "Dashboard" Self-Assessment Summary Block
[Instructions for using the "Dashboard" Self-Assessment Summary Block](Dashboard.md)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment