Display Options

In student notebooks, quizzes are rendered by display_quiz(). This function is called automatically by the code cells that CreateQuiz generates during nbgrader generate_assignment, but you can also call it directly when working with quizzes outside the nbgrader pipeline.

nbgrader_jupyterquiz.display_quiz(ref, num=1000000, shuffle_questions=False, shuffle_answers=True, preserve_responses=False, border_radius=10, question_alignment='left', max_width=600, colors=None, load_js=True, grade_id=None)

Display an interactive quiz in a Jupyter notebook.

Parameters

reflist or str

Question list, DOM element id (#name:tag), URL, or file path.

numint, optional

Maximum number of questions to show.

shuffle_questionsbool, optional

Randomise question order on each display.

shuffle_answersbool, optional

Randomise answer order on each display.

preserve_responsesbool, optional

Keep student responses visible after answering.

border_radiusint, optional

CSS border-radius in pixels.

question_alignmentstr, optional

One of 'left', 'center', 'right'.

max_widthint, optional

Maximum quiz width in pixels.

colorsdict or str, optional

CSS variable overrides, or 'fdsp' for the alternate palette.

load_jsbool, optional

Whether to inline the JavaScript source.

grade_idstr, optional

Nbgrader grade_id of the host task cell. When set, the JS recorder persists student responses to a responses.json sidecar file so an autograded test cell can read them via nbgrader_jupyterquiz.autograde.grade_quiz(). When None (the default for non-nbgrader callers), the recorder is a no-op.

Reference source

The ref argument determines where question data is loaded from.

Type	Description
list	A Python list of question dictionaries (see Quiz Syntax).
"#name:tag"	A CSS identifier. The element is looked up first by id, then by class name. Its innerHTML is parsed as JSON (plain or base64-encoded). This is the format CreateQuiz-generated cells use to reference hidden answer spans (e.g. "#unique_key:0.0").
"https://..."	An HTTP/HTTPS URL pointing to a JSON file.
"path/to/file.json"	A local file path to a JSON file.

Display parameters

Parameter	Type	Default	Description
num	int	all	Maximum number of questions to show. A random subset is chosen each time the cell is executed. Incompatible with preserve_responses.
shuffle_questions	bool	False	Randomise question order each time the cell is executed. Incompatible with preserve_responses.
shuffle_answers	bool	True	Randomise answer option order each time the cell is executed.
preserve_responses	bool	False	Keep student responses visible after answering. Requires fixed question order (shuffle_questions=False) and all questions displayed (num unset).
border_radius	int	10	CSS border-radius of the question boxes, in pixels.
question_alignment	str	"left"	Text alignment inside question boxes. One of "left", "center", "right".
max_width	int	600	Maximum width of the quiz widget, in pixels.
colors	dict or str	default palette	Colour customisation. Pass "fdsp" for the alternate palette, or a dict of CSS variable overrides (see Colour customisation).
load_js	bool	True	Whether to inline the JavaScript source. Set to False only if the jupyterquiz JavaScript is already loaded on the page.

Colour customisation

Pass a dictionary to colors to override individual CSS variables. Any variables not included in the dictionary retain their default values.

from nbgrader_jupyterquiz import display_quiz

display_quiz(questions, colors={
    "--jq-multiple-choice-bg": "#1a1a2e",
    "--jq-correct-color": "#00b894",
})

Pass colors="fdsp" to switch to the alternate fdsp palette entirely.

Available CSS variables:

Variable	Default	Description
--jq-multiple-choice-bg	#392061	Background of single-choice question boxes
--jq-many-choice-bg	#f75c03	Background of many-choice question boxes
--jq-numeric-bg	#392061	Background of numeric question boxes
--jq-mc-button-bg	#fafafa	Answer button background
--jq-mc-button-border	#e0e0e0e0	Answer button border colour (88 % opacity)
--jq-mc-button-text	#333333	Answer button text colour (default and deselected state)
--jq-mc-button-inset-shadow	#555555	Answer button inset shadow colour
--jq-numeric-input-bg	#c0c0c0	Numeric input field background
--jq-numeric-input-label	#101010	Numeric input field label colour
--jq-numeric-input-shadow	#999999	Numeric input field shadow colour
--jq-string-bg	#4c1a57	Background of string-type question boxes
--jq-correct-color	#009113	Highlight colour for correct answers
--jq-incorrect-color	#c80202	Highlight colour for incorrect answers
--jq-text-color	#fafafa	Question and answer text colour
--jq-link-color	#9abafa	Link colour inside questions

Capturing responses

Persistent answer capture for graded quizzes is handled automatically by placing the quiz inside a Manually Graded Task cell — the preprocessor wires up the recorder and autograder for you. See Graded Quizzes.