diff --git a/docs/labs/create_checker.md b/docs/labs/create_checker.md index ac1b5e77..b9a99cbf 100644 --- a/docs/labs/create_checker.md +++ b/docs/labs/create_checker.md @@ -4,16 +4,25 @@ These are the instructions for how to create labs with `checker.js`, ## Introduction -The `checker.js` system -represents each lab exercise in an HTML file. -You define text explaining the lab exercise, -a form allowing the learner to enter their answer, -pattern(s) that the correct answer(s) must match, -and an example of an expected answer. +The `checker.js` system represents each lab exercise as: + +1. An HTML file. There is an HTML file for each lab for each locale. + If the locale isn't English, the filename is conventionally prefixed + with the locale name (e.g. `ja`) and an underscore. + The HTML file provides text explaining the lab exercise and + a form allowing the learner to enter their answer. +2. A JavaScript file. The JavaScript file is shared between all locales + for a given lab. + This file includes an example of an expected answer, + the pattern(s) defining the correct answer(s), + and a list of hints to help users complete the lab. + The file may have other information, including various self-tests + that are run when an HTML file is loaded. Everything runs in the user's browser - no installation is needed. This system does *not* run arbitrary code written by the user. -You can also provide patterns for various hints. +Users can even download the labs and run them locally, using nothing +other than their web browser, if they want to do that. There are three basic tasks, which can be done by different people: @@ -25,16 +34,25 @@ There are three basic tasks, which can be done by different people: 2. [Creating the lab instructions and correct answer](#creating-the-lab-instructions-and-correct-answer). This is done by a subject matter expert. See below. 3. [Creating the lab HTML file](#creating-the-lab-html-file). - Much of the text below focuses on implementing this part. - You'd typically start with an existing lab, like + You'd typically copy an existing lab, like + [template.html](template.html) or [input1.html](input1.html), and modify it for your situation. See David A. Wheeler who can help you get started. +4. [Creating the lab JavaScript file](#creating-the-lab-javascript-file). + You might want to copy + [template.js](template.js) or + [input1.js](input1.js) and modify it for your situation. The text below discusses these in more detail. -We suggest using the [template](template.html) as a start. +We suggest using the [template.html](template.html) and +[template.js](template.js) as a starting point. You can also see our [potential future directions](#potential-future-directions). +**NOTE**: At one time we used embedded values in the HTML, +including data in YAML format. We no longer do this; we use +per-lab JavaScript files instead. + ## Creating the lab instructions and correct answer We strongly urge you to first work out the basic lab and what @@ -61,94 +79,86 @@ The HTML file of a given lab is expected to: * Describe the exercise (in HTML text) * Provide the exercise itself as a form * Identify where the user will enter their attempted answer(s) - (id `attempt0` etc.) -* Provide information about the lab, in particular: - * Provide an example of an expected answer (id `expected0` etc.) - * Provide the pattern of a correct answer (id `correct0` etc.) - * Optionally provide other information such as tests and hints (id `info`) - -The system is implemented by the client-side JavaScript file `checker.js`. - -### TL;DR + (id `attempt0` etc.). This also sets its starting value on load. An easy way implement a lab is to copy use our [template](template.html) and modify it for your situation. -Modify the `expected0` section to have a sample expected answer, and -`correct0` to have a full pattern for a correct answer. -See [input1.html](input1.html) and [input2.html](input2.html) +Again, see [input1.html](input1.html) and [input2.html](input2.html) for examples. -Whenever a lab is loaded it automatically runs all embedded self-tests. -At the least, it checks that the initial attempted answer does -*not* satisfy the correct answer pattern, while the example expected answer -*does* satisfy the correct answer pattern. We suggest including the buttons (Hint, Reset, and Give up) as shown in the examples. The code will automatically set up the buttons if they are present. -To submit new or updated labs, create a pull request on the -[OpenSSF Best Practices Working Group (WG) repository](https://github.com/ossf/wg-best-practices-os-developers/) -under the `docs/labs` directory. -Simply fork the repository, add your proposed lab in the `docs/labs` directory, -and create a pull request. - -### Transitioning away from YAML - -Configuration data was originally in an embedded YAML file. -We are transitioning to using separate `.js` files to simplify -translations and eliminate the need for the YAML library. -E.g., `input1.html` will have a corresponding `input1.js` -with configuration information that is shared between translations. -That transition hasn't completed yet. - -To help, you can create a JavaScript file that sets info2 -instead of info. The checker will automatically report -any differences between the two values. +If the lab is not in English, the `` tag should say +`` where LOCALE is the conventional locale ID +(e.g., `ja` for Japanese), and name the file `LOCAL_NAME.html`. -### Quick aside: script tag requirements +## Creating the lab JavaScript file -Data about the lab is embedded in the HTML in a -`script` tag. Embedding this data simplifies lab maintenance, -and this approach is the -[recommended approach for embedding script-supporting elements](https://html.spec.whatwg.org/multipage/scripting.html). +### TL;DR -This technique does create a -[few quirky restrictions](https://html.spec.whatwg.org/multipage/scripting.html#restrictions-for-contents-of-script-elements), -though it shouldn't matter in practice. -Basically, the text embedded in the `script` sections must -*not* include the following text sequences (ignoring case): +Each lab, regardless of the number of translations, will typically have +a single shared JavaScript file. +This shared JavaScript file provides information on +an example of expected answer(s), a pattern defining the correct answer(s), +hints, and so on. -* `