--- title: 'Discovery Prompts Example Notebook' author: Peter Mawhorter ... # Example Notebook 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. ## Question Types 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? [___][|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? [___nu][|1m|] Here are a few multiple-choice questions (two underscores for an incorrect option; an underscore plus a letter for a correct option): 1. Drop-down style: Is this a drop-down? [_d][|Yes|] [__][|No|] 1. Radio-button-style: Are these radio buttons? [_r][|Yes|] [__][|No|] 1. Click-to-cycle-style: Can you click this to cycle through options? [_c][|Yes|] [__][|Hmmm...|] [__][|No|] 1. Multiple-correct-options checkboxes: [_x][|Select me|] [__][|Not me|] [_x][|Select me too|] 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. [_...][|Free response example answer.|] ## Hints, Feedback, and Explanations 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? [___][|10|] [_f][|Nice try!|] [_f]/[0-9]\{3,\}/[|That's a big number|] [_fc]/ten/[|Why not spell it out?|] [_h][|The answer is 10!|] [_e][|I wasn't thinking very hard... |] Questions that don't have a correct answer show feedback when the show-answer button is clicked. [_...][|Long answer|] [_f][|feedback|] ## Groups 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): [_G] A B Result --- --- -------- 0 0 [_c][|0|] [__][|1|] 0 1 [_c][|0|] [__][|1|] 1 0 [_c][|0|] [__][|1|] 1 1 [__][|0|] [_c][|1|] [_E] ## Data Storage & Edits 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. ## Show/hide all buttons [ ]{#discovery-show-all} 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.