Quiz: Difference between revisions

Latest revision as of 13:59, 18 May 2023

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

letting teachers assemble questions into quizzes.
controlling which students can attempt the quiz when.
providing access so that students can review their past attempts and the feedback (if the teacher permits it).
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.

@@ Line 1: / Line 1: @@
-The quiz module is a complex module with its own modular structure to allow question type plug-ins. The module has grown organically and in spite of a lot of rewriting for Moodle 1.5 the code is not very simple to understand.
+{{Quiz developer docs}}
-On this page I am planning to give an overview of how the module works. --[[User:Gustav|Gustav]] 07:12, 28 January 2006 (WST)
+The quiz is a complex module, although attempts have been made to re-organise the code to keep things managable.
-==Terminology==
+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.
-In order to describe and understand the quiz module, it is necessary to
-understand the terminology that is used to describe its aspects. Below
-some important terms are listed and explained and in some cases linked to more
-detailed documentation.
-'''adaptive question''' (QTI speak: adaptive item)
+==What the quiz does and does not do==
-Adaptive questions are questions that walk the user through a directed graph of question states depending on the user's responses. E.g. a complicated mathematical question that is answered incorrectly, but is likely to be incorrect because of a common mistake, could provide the user with a hint towards this mistake, apply a penalty and allow a second attempt at this question.
+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]].
-Quizzes can be run in adaptive mode, which provides buttons to mark each question individually.
-'''answer(s)'''
+The quiz module itself is only responsible for
+# letting teachers assemble questions into quizzes.
+# controlling which students can attempt the quiz when.
+# providing access so that students can review their past attempts and the feedback (if the teacher permits it).
+# providing reports on the outcomes for teachers.
-The term answer is used exclusively for the teacher defined answers of a question. These answers are usually stored in the <code>quiz_answers</code> table and are compared to the responses for grading.
+Displaying the results is delegated to [[Quiz reports|quiz report]] sub-plugins. Note that some fairly core functionality is implemented in the reports. For example deleting and regrading attempts is handled by <tt>quiz_overview</tt> report, and bulk manual grading is handled by <tt>quiz_grading</tt>.
-'''attempt(s)'''
+A lot of the details of when and if students can access the quiz are handled by [[Quiz access rules|quiz access rule]] sub-plugins.
-The term attempt is used in the sense of "Attempt at the quiz". Depending on the quiz settings, a student may be allowed several attempts at a quiz. An attempt is finished when the student clicks on the corresponding button on the attempt page. Students do not have to complete an attempt in one visit. They can navigate away from the quiz page and return later to continue the same attempt.
-Within one and the same quiz attempt a student may make several attempts        at answering a particular question, at least if the questiontype allows        it and the quiz is set up in adaptive mode. These will always be        referred to as &quot;attempts at a question&quot;, never just as        &quot;attempts&quot;.
+==Code overview==
-'''event'''
+All the code has PHPdoc comments which provides a lot of detailed explanation. That is not repeated here.
-The $stateobject (and the <code>quiz_states</code> table) has a        field <code>event</code>, which indicates the event that led to the        creation of the state. The field can take the value of any of the        following constants (defined in locallib.php):
+This is a [[Modules|standard Moodle activity module]], so inside <tt>mod/quiz</tt> there are all the things you would expect to see like <tt>db/</tt>, <tt>lib.php</tt>, <tt>locallib.php</tt>, <tt>view.php</tt>, <tt>version.php</tt> and so on.
-*EVENTOPEN: The attempt has just been opened and this is the initial state of a question, i.e. the user has seen the question did not interact with it yet.
-*EVENTSAVE: The responses are just being saved, either because the student requested this explicitly or because the student navigated to another quiz page.
-*EVENTVALIDATE: The student requested a validation of the responses. (This is not supported by all questiontypes.)
-*EVENTGRADE: The responses are being graded but the question session is not closed. This is generally the case for adaptive questions.
-*EVENTCLOSE: The responses are being graded and the question session is closed. Usually this happens because the whole attempt closes, either because the student requests it or because the time is up or because we are beyond the due date.
-*EVENTDUPLICATEGRADE: This is a strange one. It indicates that the responses would have been graded had they not been found to be identical to previous responses.
-When new responses are being processed by the function <code>        quiz_process_responses</code>, then this function is being passed the       event type in <code>$action->event</code> while the responses are in        <code>$action->responses</code>.
+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.
-'''question(s)'''
+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 <tt>edit.php</tt>.
+; attemptlib.php
+: This defines the <tt>quiz</tt> and <tt>quiz_attempt</tt> 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 <tt>view.php</tt>, <tt>startattempt.php</tt>, <tt>attempt.php</tt>, <tt>processattempt.php</tt>, <tt>summary.php</tt> and <tt>review.php</tt> scripts.
+; accessmanager.php
+: This provides the interface point that the rest of the quiz code uses to access the [[Quiz access rules|quiz access rule]] sub-plugins.
+; renderer.php
+: the quiz uses the [[Themes 2.0 overriding a renderer|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 <tt>accessmanager.php</tt>, <tt>addrandom.php</tt> and <tt>overridedit.php</tt> respectively.
+; module.js
+: JavaScript used by <tt>attempt.php</tt> and to a lesser extent <tt>view.php</tt>, <tt>summary.php</tt> and <tt>review.php</tt>.
+; edit.js
+:JavaScript used by <tt>edit.php</tt>.
-Strictly, a question in the context of the quiz module is the set of        definitions (question name, question text, possible answers, feedback,        etc.) that constitute a reusable item. Therefore a question itself is a        static entity. All data related to interactions with a particular        question (in a particular attempt on a particular quiz) is stored in its        corresponding states.
-'''questiontype'''
+==Quiz navigation fake block==
-There are several questiontypes built into the quiz module, however,      due to the plugin architecture of the quiz module, it is possible to        define custom questiontypes. Existing questiontypes include true/false,       multiple choice, short answer, numerical and  calculated questions.
+During the quiz attempt (so, on <tt>attempt.php</tt>, <tt>summary,php</tt> (from Moodle 2.2 onwards) and <tt>review.php</tt>) we display a navigation UI that looks like a block. This uses the <tt>block_manager::add_fake_block</tt> feature.
-'''responses'''
+The block contents is produce by classes in <tt>attemptlib.php</tt> working with methods in the renderer. The navigation relies on some JavaScript in <tt>module.js</tt> 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.
-Conceptually these are the students' responses to a question. This is always used in plural, although for some questiontypes there is only one possible response. In the runtime <code>$state</code> object there is a field <code>$state-&gt;responses</code>, which holds an array of a student's responses to a question. See also: [[Quiz response storage]]
-'''state'''
+==Quiz layout==
-Question states are saved in the table <code>quiz_states</code>. States always "belong" to a question within a particular attempt and are therefore also user specific. The first state in a question's life cycle during an attempt records the fact that the user has seen the question. This state is never modified, however, it can be superseded by a new state, which represents a user interaction. Different user interactions are defined by the events, a set of constants, one for each possible type of user interaction.
+Information about the structure of a quiz is stored in the <tt>quiz.qestions</tt> column and the <tt>quiz_question_instances</tt> table. The layout is a comma-separated list of question ids, with 0s to represent page-breaks.
-'''session'''
+There are methods in <tt>locallib.php</tt> and <tt>editlib.php</tt> to manipulate this structure.
-A question session is the complete history of question states that the question is taken through. Usually only the most recent state and the last graded state are of interest though.
+When a quiz attempt is stared, the questions are added to a <tt>question_usage_by_activity</tt> 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 <tt>quiz_attempts.layout</tt>. This is done in <tt>startattempt.php</tt>.
-==More details==
+One of the options is to randomise the order of the question in the quiz. This is done by shuffling <tt>quiz_attempts.layout</tt>.
-More details can be found on the following pages:
+<tt>startattempt.php</tt> 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.
-*[[Quiz database structure]]
+==See also==
+* [[Goals of an online assessment system]] - a summary of what the quiz is trying to achieve, and the developments that might be done in the future.
+* [[Question bank]]
+* [[Question engine]] - also [[Question_Engine_2]], which needs to be merged into it. In particular, see [[Using the question engine from module]].
+* [[Quiz Usability portal]] - docs from the project to re-design the editing interface in Moodle 2.1.
+* [[Quiz support in the Mobile app]] - Quiz support in the Mobile app is one of the most requested features by users
+[[Category:Quiz]]

Documentation