9. Using OpenDSA with the Khan Academy infrastructure¶
We use the Khan Academy (KA) infrastructure for writing questions. KA supplies some documentation at their wiki.
In the rest of this section, we will go through examples of the most common question types used in OpenDSA.
9.1. Summary Exercises¶
Individual questions, as appropriate, can be grouped together into “summary” exercise. These can in turn be grouped together into a broader summary, such as an end-of-chapter review. ~OpenDSA/Exercises/Background/IntroSumm.html provides a typical example. If you are creating a new summary exercie, you can copy this file and start by changing the title on line 4. Note that the two library includes on lines 5 and 6 are needed for all Khan Academy exercises within OpenDSA. Replace lines 9-16 with your exercises, one per line, using the same format as these lines use. Note that data-name takes a file name using a path relative to the summary exercise.
9.2. Math and Variables¶
You can include math (in LaTeX notation) by bracketing it in <code></code>. See ~OpenDSA/Exercises/Background/MthBgMCQperm.html for simple examples.
9.3. True/False Questions¶
~OpenDSA/Exercises/Design/CompareTF2.html is an example of a typical simple T/F question. Simply change the question in the “question” paragraph, set “solution” to be True or False, and set the hints.
ALL questions (aside from summary exercises) should have at least one hint!
~OpenDSA/Exercises/Design/CompareTF1.html shows use of simple alternate wording, called a “spin”. Note the required change in line 2 to load “spin” support.
~OpenDSA/Exercises/Background/SetTFequivrel.html shows sophisticated use of variables to generate a variety of questions. It also shows use of katex functionality to support interpretation of math inside a string (not a typical problem that you will encounter).
9.4. Multiple Choice Questions¶
The simplest form of MCQ is shown in ~OpenDSA/Exercises/Background/IntroMCQeff.html. Just change your title, your question, the text for the choices (add as many as you like), and the hints. This style of MCQ will show the answer string and the choices strings, all arranged in random order each time the question is presented. Note that the correct answer is not included as a choice. In contrast, T/F questions are a special type of MCQ where the question choices are given in the specified order (and the correct answer is therefore also one of the listed choices). ~OpenDSA/Exercises/Design/CompareMCQ4.html is an MCQ with fixed choices.
~OpenDSA/Exercises/Binary/HparentMCQ.html shows a somewhat different approach. Line 18 has two key flags. data-show is set to 4, meaning that 4 choices will be shown. data-none is set to true, which means that the choice None of the above will always appear. Counting the correct answer, the four distractors, and None of the above, this means that there are six possible choices to display (None of the above will appear last, and three of the other five will appear at random). When the correct answer is not shown, None of the above becomes the correct answer. If a student chooses that, then the correct answer is shown after clicking the Check answer button.
9.5. Fill-in-the-Blank Questions¶
See ~OpenDSA/Exercises/Background/MthBgFIBlgbs1.html for simple FIB formatting. It is important to understand that the KA framework provides support for processing certain types of student inputs. The simplest approach is to do an exact string match, as in this simple example. This is indicated by the fact that line 15 includes the tag data-type="text" (even though the student answer is actually a number, they have type it exactly this way). ~OpenDSA/Exercises/Background/AlgAnlsFIBsqrt.html shows off two different features. It will allow the student to type either of two diffrent answers: the string “1/2” or anything that is the decimal equivalent to 0.5.
~OpenDSA/Exercises/AlgAnal/GrowthRatesPRO.html and ~OpenDSA/Exercises/AlgAnal/GrowthRatesPRO.js show a relatively simple example of using JSAV with the Khan Academy framework. Note that all of the following naming conventions should be observed unless you know what you are doing when you change it.
Any required CSS styling is included in the .html file for the exercise. Be aware that many elements have defined styles already that should not be overwritten without cause. GrowthRatesPRO is a rare exception in that it explicitly needs to define the JSAV array cells to be large. Most JSAV-based exercises have only a height value, and all CSS elements should include the file name to keep from colliding namespace with other parts of the page. Never adjust the width of the .jsavcanvas. You have no reason to make it narrower than the default, and you will probably break things if you make it wider.
The body tag (Line 12) must include the data-height and data-width fields. Always set ``data-width="950". Make sure that the height can accommodate the hints when they are displayed.
The JSAV object must be declared with the exercise name for its parameter. It is petty much universal that the JSAV objects appear as a static display (that is, not a JSAV slideshow). Lines 86-90 show the standard format for this section, beginning with creating the JSAV object, followed by setting out any JSAV objects (this one is pretty simple in that there is only a single JSAV array), followed by the displayInit and recorded to get the elements displayed on the HTML page.
9.7. Naming Conventions¶
Summary exercises should always be given names of the form <topicname>Summ.html.
T/F questions should have file names as <topicname>TF<question>.html. Multiple choice questions should be named as <topicname>MCQ<question>.html. Fill-in-the-blank questions should be named as <topicname>FIB<question>.html. It is bad style to use counts (like 1, 2, 3) for the <question> part in the name for a series of questions.
Proficiency exercises should be named as <topicname>PRO.html. A proficiency exercise is something where the student must manipulate a data structure (including any exercise where the user interface for answering the question is to click or drag JSAV objects), or sometimes work a problem to reach an answer. In the case where students do a computation to complete a fill-in-the-blank problem, this might be a matter of judgement on how to name it. Generally, a fill-in-the-blanks question that generates random problem instances and is presented as a stand-alone exercise to students should probably be named as a proficiency exercise.
9.8. Common Errors¶
Your exercise might generate a console error that looks like:
Error while evaluating var#JSAV khan-exercise.js:359 TypeError: Cannot read property 'id' of undefined(…)
This is a common problem. Nearly always, it means that either you forgot to include jsav in the data-require field of the <html> tag, or else you got the names wrong somewhere for the divs.