Question Parts¶

Every question in Varsity Learning is built from several distinct sections. Understanding the structure helps you write questions efficiently and control exactly what students see.

Question Structure Overview¶

Question
├── Setup code (randomization, calculations)
├── Question text (displayed to student)
├── One or more answer parts
│   ├── Answer template (input field type)
│   ├── Correct answer (evaluated server-side)
│   └── Per-part tolerance / scoring settings
├── Hints (optional $hints array in setup code, shown after tries)
└── Detailed solution (optional, shown with the answer and/or as a help button)

Setup Code¶

The setup block runs before the question is displayed. Use it to: - Generate random values - Compute derived quantities - Define variables used in the question text and answer

$a = rand(2, 9)
$b = rand(1, 5)
$ans = $a + $b

Variables defined here are available in all other parts of the question using $variablename.

Question Text¶

Written in a mix of HTML and AsciiMath. Use backticks to delimit inline math:

<p>Find the sum of `$a` and `$b`.</p>

Math is AsciiMath, never LaTeX — \frac, \sqrt and other LaTeX commands do not render. Wrapping math in a <div> does not switch it to a separate display mode; the renderer treats backtick math the same in any container. To set an expression on its own line, give it its own paragraph:

<p>Evaluate:</p>
<p>`$a/$b`</p>

Displaying a Graph¶

Build the graph in the setup code with showplot, store it in a variable, and put that variable in the question text where the graph should appear. Give every showplot graph alternative text with replacealttext. A screen reader announces it, so it has to carry what a sighted student reads off the graph. (A showasciisvg figure takes its alternative text as its fourth argument instead; see Graph & Table Macros.)

Common Control — setup:

$a = nonzerorand(-2, 2)
$h, $k = nonzerodiffrands(-3, 3, 2)
$eqn = makexxpretty("$a(x - $h)^2 + $k")
$dir = ifthen($a > 0, "upward", "downward")
$x1 = $h + 1
$y1 = $a + $k
$graph = showplot("$eqn,red", -6, 6, -6, 6)
$graph = replacealttext($graph, "Graph of a parabola that opens $dir, with vertex ($h, $k), passing through ($x1, $y1).")

"$eqn,red" draws y = $eqn in red, and the four numbers set the window: xmin, xmax, ymin, ymax. makexxpretty tidies the signs and coefficients a random value leaves behind, so -1(x - -2)^2 + 3 becomes -(x+2)^2+3. See Graph & Table Macros for showplot's other arguments (several curves, labels, grid, size).

Question Text:

<p>Find an equation for the parabola graphed below.</p>
$graph
<p>`y =` $answerbox</p>

Common Control, continued — answer and options (a Function question):

$answer = $eqn
$readerlabel = "y ="
$showanswer = "`y = $eqn`"

The box follows y =, so the student types only the right-hand side. $answer must not contain the = either. $readerlabel gives screen-reader users the same y = cue. Placing the Answer Box and Shown Answer below explain $answerbox and $showanswer.

Answer Parts¶

Each answer part defines one input field. A question can have multiple parts (e.g., Part a, Part b).

For each part, you configure: - Answer type — number, string, multiple choice, etc. (see Question Types) - Correct answer — the value or expression the student must match - Tolerance — how close a numeric answer must be (absolute or relative) - Score weight — this part's share of the question's points ($answeights in a multipart question; weights are relative, and the question's point value is set in the assessment)

Placing the Answer Box¶

Unless you place it, the answer box appears below the question text. To put it somewhere else, such as after a label or inside a sentence, write $answerbox (or its shorthand [AB]) in the question text:

<p>`y =` $answerbox</p>

In a multipart or conditional question, each part has its own box, numbered from zero: $answerbox[0], $answerbox[1] …, or [AB0], [AB1] …. A conditional question numbers its box even when it has only one part. Place every box or none. Once you place any numbered box, the engine adds none of the others below the question, so a part you leave out has no box at all, and testing gives no warning.

<p>x-intercept: `x =` [AB0]</p>
<p>y-intercept: `y =` [AB1]</p>

Text in front of a box labels it on screen only. A screen reader announces each box as "Question N" (plus "Part k of m" when the question has more than one part), followed by $readerlabel. The exception is a molecule box, which ignores $readerlabel and carries no question or part number. When the label matters, also set $readerlabel in Common Control, as plain text: one entry per part when the question has more than one part (multipart or conditional), such as $readerlabel = array("x-intercept", "y-intercept"), otherwise one string. See also $ansprompt.

Numbered boxes only in multipart and conditional questions

In any other question type, use $answerbox or [AB]. With a number, the student gets no answer box at all: [AB0] stays on the page as literal text, and $answerbox[0] inserts a stray <, the first character of the box's HTML. Testing a question you own warns about $answerbox[0] ("did you mean for this question to be Multipart?") but not about [AB0].

The reverse fails too. In a multipart or conditional question, a bare [AB] stays on the page as literal text and the boxes are added below the question, and a bare $answerbox prints the word "Array" and no box at all.

Hint Text¶

Optional. There is no separate hint box and no "Show Hint" button. Hints are an array named $hints in the setup code, indexed by how many tries the student has used: $hints[1] appears after the first try, $hints[2] after the second, and the last hint keeps showing after that. Hints appear only where you put $hintloc in the question text, and only when the assessment's settings allow hints. Write guidance without giving away the answer:

$hints[1] = "Try substituting `$a` into the formula first."

Then place the hint in the question text:

$hintloc

Solution Text¶

Optional. Enter it in the Detailed Solution box. On a new question, click Add a detailed solution to open it. The checkboxes just above the text box decide where it appears. Display with the "Show Answer" shows it with the correct answer, once the assessment's settings reveal answers. Use this as a "written example" help button also offers it as a help button while the student is working (if the assessment allows help), drawn with a different set of random values. Both are ticked for a new question. If your solution uses the question's variables, as below, also tick Uses random variables from the question, or question is not randomized. Otherwise students see "This solution is for a similar problem, not your specific version" above it. Write a full step-by-step solution:

<p>Step 1: Identify the values: `a = $a`, `b = $b`.</p>
<p>Step 2: Add them: `$a + $b = $ans`.</p>

Shown Answer¶

When the assessment's settings reveal answers, each part shows its correct answer, which the engine formats from the part's answer: $answer, or $answers for Multiple Answer, Matching and Drawing parts. A Conditional question has no answer to format, so unless you set $showanswer it shows only "Answers may vary". To show something else, set $showanswer in Common Control. Use it to restore the y = that $answer has to leave out, or to show a short sentence:

$showanswer = "The vertex is at ($h, $k), so `y = $eqn`."

$showanswer is the short answer. The detailed solution above is the worked explanation, and it is set separately. In a multipart question, give an array with one entry per part. A single string is shown once, as the answer to the whole question, and only when answers are revealed for the whole question. It also replaces the parts' own answers, so where the assessment would reveal answers part by part, nothing shows until the whole question qualifies.

Conditional Content¶

You can show different text based on the random values chosen:

if ($a > 5) {
    $scenario = "large";
} else {
    $scenario = "small";
}

Then reference $scenario in the question text to adapt the wording.

Testing Your Question¶

Use Quick Save and Preview (or Save and Test Question) while editing to see how the question renders for a student. On the test page, use New Version to generate a different set of random values and verify the question works correctly across the range of possible inputs.