This page demonstrates the capabilities of the
discoveryPrompts.py panflute filter. See
README.md for project details. You can also check out the
detailed documentation at the top of the
discoveryPrompts.py file.
Questions are defined by a square bracket followed by an underscore,
followed eventually by another square bracket, like this
[___]. Other characters in the middle determine the type of
question. Each question will have at least a “show answer” button, and
questions that have a correct answer (as opposed to free-response
questions) will have a “check answer” button as well that checks for
correctness without showing what the correct answer is.
The answer to a question (or value for an option) comes after the
question brackets, in its own set of brackets that also include vertical
bars right inside, like this: [___][|answer|]. Check the
“example.mdi” file to see the inputs that resulted in each question
below.
Here’s a fill-in-the-blank question (three or more contiguous underscores in the square brackets):
What is 2 + 3? Correct answer: 5
There are a number of letter suffixes you can attach to the
underscores in fill-in-the-blank questions to control how input is
matched against the answer; see the documentation at the top of
discoveryPrompts.py for details. ‘n’ or ‘nu’ are useful
suffixes; here’s a question that handles metric units (try “100 cm” or
“1m” or “0.001 Km”, although it won’t convert feet or miles):
How long is a meter? Correct answer: 1m
Here are a few multiple-choice questions (two underscores for an incorrect option; an underscore plus a letter for a correct option):
The system looks for multiple “option” questions in a row within the same HTML element and merges them together into a single selector (or generates linked radio buttons or checkboxes for each).
Here’s a free-response question. These have an “example” answer but not a “correct” answer. Use three periods after the underscore for this type of question.
Example answer: Free response example answer.
Adding a [_h] group after another question will add a
“show-hint” button that shows the provided hint.
Adding a [_f] group will add a feedback item to be shown
only when the user checks the answer and it’s wrong. Between the
[_f] and the [|...|] part that has the
feedback in it, you can include a regular expression in slashes and the
feedback will only be given for wrong answers that match that regular
expression. Try entering a 3+-digit number in the question below…
For questions that don’t have a check-answer button because they don’t have a correct answer, feedback is shown when clicking show-answer.
Adding a [_e] group after a question will add an
explanation which gets displayed when the user gets the question right,
OR if they click the show-answer button.
What number am I thinking of? Correct answer: 10 Feedback: Nice try! Feedback: That’s a big number Feedback: Why not spell it out? Hint: The answer is 10! Explanation: I wasn’t thinking very hard…
Questions that don’t have a correct answer show feedback when the show-answer button is clicked.
Example answer: Long answer Feedback: feedback
In some cases, it’s nicer to fill in multiple answers and check them
all at once instead of having separate buttons to check each. You can
use [_G] and [_E] to start and then end a
group, and the check/hint/show-answer buttons will appear at the end of
the group, and will affect the entire group at once.
Here’s a table with multiple values to fill in: Fill in the truth table for A AND B (click to cycle ones/zeroes in the last column):
GCorrect answer:
| A | B | Result |
|---|---|---|
| 0 | 0 | 0 1 |
| 0 | 1 | 0 1 |
| 1 | 0 | 0 1 |
| 1 | 1 | 0 1 |
Correct answer: See above
Users’ answers to questions are stored whenever an answer is checked or a correct answer is shown, using local browser storage, which is specific to the device & browser used. They’re not sent anywhere (and there’s currently no mechanism for this) but they are stored so that if you refresh the page, they’ll be populated again, to prevent people from losing work. There’s even an attempt to store them per question-identity/order so that if you edit a page and add new questions, the answers to the old questions can probably still be put back into the correct places, OR if you edit the page in a way that changes a question’s identity, the old answer can probably still be put back based on ordering. If you make lots of changes to both ordering and identity of questions this will break down at some point of course.
Buttons to show/hide all answers are added at the end of the
document, but if you have an element with
discovery-show-all as its ID, instead they get added to the
end of that element. Writing [ ]{#discover-show-all} in
Markdown creates an empty span with that ID.