options block

<options> blocks are an extension to legacy PDS files. They are backwards compatible, but enable question bank creators to preconfigure Drill 2 features. <options> blocks have no effect in PDS.

Users can opt out from any settings preconfigured with <options> block, but some features can be unavailable until enabled in the block.

Format

<options> block must be added at the very end of a question bank, after all questions, and must be separated from them with at least one empty line.

The block is a JavaScript object in a strict JSON notation. The object is loaded by Drill 2 and then processed. If any errors are encountered when parsing JSON, an error message will be displayed in JavaScript console.

Recognized properties are interpreted and affect various features of Drill 2. Missing properties will use default values. No properties are required.

The block of JSON must be preceded with <options> string. That string is stripped before parsing JSON.

Example of an <options> block is presented below.

<options> {
    "format": "2.1",
    "markdown": true,
    "mathjax": true,
    "grading": "custom: incorrect ? 0 : (missed == 0) ? 3 : (missed == 1 && correct) ? 1 : 0",
    "radical": true,
    "ptsPerQuestion": 1,
    "timeLimit": 90,
    "repeatIncorrect": true,
    "explain": "always",
    "explanations": {
        "1": "This question's purpose is testing if explanations work."
    }
}

Supported properties

• explain - when and how should explanation be available
• explanations - explanations for questions
• format - file format version
• grading - recommended grading method
• markdown - whether file is Markdown-formatted or not
• mathjax - whether LaTeX and MathML should be parsed in this file
• ptsPerQuestion - how many points each question is worth (applies only if per question grading is recommended)
• radical - whether wrong answers zero score or not (applies only if built-in grading is recommended)
• repeatIncorrect - whether questions with score lower than 100% should be asked again
• timeLimit - time limit for questions

explain, explanations

Used for adding explanations to questions. Can be used to clarify why certain answers are correct or incorrect.

Accepted values for explain:

• summary - Explanations are hidden and unavailable until the test is completed.
• optional (default value) - Additional button is displayed after checking answers if explanations are available. Clicking the button reveals explanations.
• always - Explanations are immediately shown when answers are checked.

Format of explanations is described on the Explanations page.

format

This field designates the Drill version the file is dedicated for. A warning will be displayed if a file with unrecognized format version is be loaded. In the future this value may also be used to switch default values if some behavior will be changed.

Accepted values:

• "legacy" (default value) - For files created with PDS in mind.
• 2.x - For files dedicated for Drill 2.
  • "2" - For original Drill 2.
  • "2.1" - For Drill 2 versions that support MathJax.

It is recommended to declare oldest format that supports all features the question bank uses. Declaring newer versions is not recommended. Declaring format that doesn't support features used in the bank is strongly discouraged, because it may prevent incompatibility warning from showing after the bank is loaded.

grading, ptsPerQuestion, radical

These properties define default grading rules.

Accepted values for grading:

• "perAnswer" (default value) - Each correct answer scores user one point.
• "perQuestion" - Each question is worth a constant amount of points. Points are split equally between correct answers. Amount of points per question is configured by ptsPerQuestion's value.
• custom - Hand-crafted grading schemes can be provided. Details for creating custom graders are available on Custom graders page.

For built-in grading rules (per answer and per question) radical grading is enabled by default. radical property doesn't affect custom graders.

Accepted values for radical:

• true (default value) - User can't score any points on a question if he has checked at least one incorrect answer.
• false - Incorrect answers counterbalance correct ones. Each incorrect answer cancels points scored for one correct answer. If there are more incorrect answers than correct ones, no points are added nor subtracted.

Accepted values for ptsPerQuestion:

• Any integer numeric value. This property applies only if grading is set to perQuestion.

markdown

Markdown parsing can be enabled for question bodies and explanations. Answers are never parsed as Markdown. Details on using Markdown are provided on Formatting and formulas page.

Users can opt out from using Markdown if it's enabled in the <options> block, but they can't opt in if it's disabled or undefined. Enabling Markdown on questions that aren't adapted to use it can lead to unexpected behavior.

Accepted values:

• false (default value) - Disable Markdown and don't let user enable it.
• true - Enable Markdown and let user disable it.

mathjax

This property can be used to enable parsing of TeX, LaTeX and MathML in question bodies, answers and explanations. Details on using formulas are provided on Formatting and formulas page.

As with Markdown, users can opt out from using formula parsing if it's enabled in the <options> block, but they can't opt in if it's disabled or undefined.

Accepted values:

• false (default value) - Disable formula parsing and don't let user enable it.
• true - Enable formula parsing and let user disable it.

repeatIncorrect

This property sets the "learning mode" to be enabled by default. If user scores less than 100% on a question, it's added to the end of questions queue and asked again later. Questions are asked over and over until all questions are answered correctly.

Scores from repeated questions are saved and shown on the summary screen, but don't count into total score.

Accepted values:

• false (default value) - Each question is asked once.
• true - Answers are repeated until answered correctly.

timeLimit

Setting this property to any numeric value sets a time limit for each question. If the question isn't answered until the time runs out, all answers are unchecked and grading is forced. There is no other penalty other than scoring 0 points. (unless some weird grader is defined)

Accepted values:

• 0 (default value) - The time isn't limited.
• Any positive integer - Time per question will be limited to that number of seconds. The value is rounded to a multiple of 5.