Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Quiz

From MoodleDocs
Revision as of 13:59, 18 May 2023 by Luca Bösch (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

The quiz is a complex module, although attempts have been made to re-organise the code to keep things managable.

This page is only intended to give a high level overview. To really understand the quiz, you will have to look at the code, much of which should be clear and well commented.


What the quiz does and does not do

The quiz module uses the Question bank to manage the questions that teachers create, and the Question engine to display and process questions when students attempt them. You are particularly advised to read Using the question engine from module.

The quiz module itself is only responsible for

  1. letting teachers assemble questions into quizzes.
  2. controlling which students can attempt the quiz when.
  3. providing access so that students can review their past attempts and the feedback (if the teacher permits it).
  4. providing reports on the outcomes for teachers.

Displaying the results is delegated to quiz report sub-plugins. Note that some fairly core functionality is implemented in the reports. For example deleting and regrading attempts is handled by quiz_overview report, and bulk manual grading is handled by quiz_grading.

A lot of the details of when and if students can access the quiz are handled by quiz access rule sub-plugins.


Code overview

All the code has PHPdoc comments which provides a lot of detailed explanation. That is not repeated here.

This is a standard Moodle activity module, so inside mod/quiz there are all the things you would expect to see like db/, lib.php, locallib.php, view.php, version.php and so on.

The scripts that are directly accessed by the user are listed on Quiz user interface overview, and I will not list them again here. It would probably also help to look at the Quiz database structure before trying to understand the back-end code.

The back-end code is organised thus:

lib.php
All the functions that are called by the Moodle core. For performance reasons it is important that this does not include any other files.
locallib.php
This contains all the other quiz library functions that do not have a more specific home. Including this file also includes all the other quiz libraries that you might need.
mod_form.php
The module settings form, as you would expect for any Moodle activity module.
editlib.php
This defines the functions that are used when at teacher edits the quiz. Thus, they are mostly called from edit.php.
attemptlib.php
This defines the quiz and quiz_attempt classes. These are all about what happens when a student (or other user) is looking at the quiz, so they provide a personalised view of the quiz data from the point of view of that user. Thus these classes are mainly used by the view.php, startattempt.php, attempt.php, processattempt.php, summary.php and review.php scripts.
accessmanager.php
This provides the interface point that the rest of the quiz code uses to access the quiz access rule sub-plugins.
renderer.php
the quiz uses the Moodle 2.x renderer system to generate the HTML for all the student-visible parts of the UI. This means that theme designer have a lot of freedom as to how the quiz is displayed to students. Perhaps one day the editing UI will also be re-factored. As is standard for a Moodle plug-in, this file defines the renderer class.
settings.php & settingslib.php
define the admin settings for the quiz.
accessmanager_form.php, addrandomform.php & override_form.php
Used by accessmanager.php, addrandom.php and overridedit.php respectively.
module.js
JavaScript used by attempt.php and to a lesser extent view.php, summary.php and review.php.
edit.js
JavaScript used by edit.php.


Quiz navigation fake block

During the quiz attempt (so, on attempt.php, summary,php (from Moodle 2.2 onwards) and review.php) we display a navigation UI that looks like a block. This uses the block_manager::add_fake_block feature.

The block contents is produce by classes in attemptlib.php working with methods in the renderer. The navigation relies on some JavaScript in module.js because it is vitally important that every time the user moves from one page of the quiz attempt to another, we save their answers. The javascript turns click on the navigation links into form submissions.


Quiz layout

Information about the structure of a quiz is stored in the quiz.qestions column and the quiz_question_instances table. The layout is a comma-separated list of question ids, with 0s to represent page-breaks.

There are methods in locallib.php and editlib.php to manipulate this structure.

When a quiz attempt is stared, the questions are added to a question_usage_by_activity object ($quba) that is managed by the question bank. The $quba indexes things by 'slot' rather than question.id, so the quiz layout gets rewritten and stored in quiz_attempts.layout. This is done in startattempt.php.

One of the options is to randomise the order of the question in the quiz. This is done by shuffling quiz_attempts.layout.

startattempt.php also handles selecting a real question to go in each place where the teacher has added a 'Random question from category X' to the quiz.


See also