MoodleDocs - User contributions [en]

Cloze

2006-02-22T19:53:13Z

Gustav: removed duplicate paragraph

'''Embedded answers (Cloze)''' questions consist of a passage of text (in Moodle format) that has various answers embedded within it, including multiple choice, short answers and numerical answers.

There is currently no graphical interface to create these questions - you need to specify the question format using the text box or by importing them from external files.

Lots of people suggest that [http://hotpot.uvic.ca/ Hot Potatoes] software is the easiest way to create Embedded answer (Cloze) questions. Once you have created your questions on your PC, you can then import them into into Moodle's quiz module.

==Format==

The Moodle [http://moodle.org/help.php?module=quiz&file=multianswer.html help documentation for Cloze questions] gives an example. Peter Ruthven-Stuart advises, "I found the best way to learn how to make the Cloze type questions was to copy the example in the above link, and then make small changes to the example until I broke it."

The number appearing at the beginning of a 'blank' indicates the weighting for the question, and is nothing to do with the question number. So, in the example below the blank has been given a weight of '2'. So, if the blanks all have an equal weight, you don't need to type any number.

{2:SHORTANSWER:%100%CALL#Yes, that's it!~%0%?#What should I __ you? Either lower or UPPER case is OK.}

NB: Be careful when copying a cloze type question into the WYSIWYG HTML editor, as line breaks tend to get added, which destroys the question.

Joseph Rézeau provided the following examples and the detailed explanation of the syntax.

Match the following cities with the correct state:

* San Francisco: {1:MULTICHOICE:=California#OK~Arizona#Wrong}
* Tucson: {1:MULTICHOICE:California#Wrong~%100%Arizona#OK}
* Los Angeles: {1:MULTICHOICE:=California#OK~Arizona#Wrong}
* Phoenix: {1:MULTICHOICE:%0%California#Wrong~=Arizona#OK}

The capital of France is {1:SHORTANSWER:=Paris#Congratulations!~%50%Marseille#No, that is the second largest city in France (after Paris).~.*#Wrong answer. The capital of France is Paris, of course.} Note! This example only works in Moodle 1.5.2, see the point 12 below.

Please note that this does not cover the [[NUMERICAL]] type question.

# all question items within a cloze-type question are coded inside curled braces { }
# the number which appears between the opening brace and the colon {1: is the weighting of that item; if it is set at 1 for all the items, it needs not be specified, so you can have {:
# after the colon we have the item type: MULTICHOICE, SHORTANSWER, NUMERICAL
# the syntax for MULTICHOICE and SHORTANSWER is the same; the only difference is in the displaying of the item to the student
# the order of the various answers is indifferent (except if you want a catch-all for wrong answers, see #12 below)
# a correct answer is preceded with the equal sign = or a percentage (usually %100%)
# a wrong answer is preceded with nothing or a percentage (usually %0%)
# you can allocate some points between 0 and 100 to some answers, if you put the appropriate percentage
# all answers except the first one are separated from one another by the tilde ~ sign
# answers can be followed by an optional feedback message, preceded with the # sign; if there is no feedback message, the # sign can be present or absent, it does not matter
# note that the feedback message is displayed in a small popup window (if and when feedback has been declared accessible to the students in the Quiz settings) upon mouse hovering
# in the SHORTANSWER type you may want to put a catch-all (wrong) answer in order to send a "wrong, try again" feedback; you can do this by inserting .* as a wrong answer; this does not work in Moodle 1.5, 1.5.3 and 1.6; it works in version 1.5.2 only; see my post here
# unfortunately in MULTICHOICE MODE it is not possible to get the answers to be scrambled
# unfortunately in SHORTANSWER mode it is not possible to make the answers case-sensitive (except by using a workaround which I will make explain in a further post in this thread)

==See also==
This information was drawn from:
*[http://moodle.org/mod/forum/discuss.php?d=36521 Is there a guide to using the cloze format?] forum discussion
*[http://moodle.org/mod/forum/discuss.php?d=36430&parent=170308 Cloze-type question syntax] forum post

[[Category:Teacher]]
[[Category:Quiz]]

Backup and restore FAQ

2006-02-15T21:23:29Z

Gustav: /* How do I backup my whole Moodle site? */

;Site backups
:Site backups, as explained in [[Upgrading_Moodle#Backup_important_data|upgrading Moodle]], are recommended in order to have all data saved with the best confidence and the shortest recovery time.

;Course backups
:Course backups, configured on the [[admin/backup|backup]] page, are more expensive in terms of time and CPU usage. The recovery time to have your site running again is longer. Course backups are useful for obtaining "fresh" copies of courses to be re-used or distributed individually, however they should never be used as a primary backup system (unless your hosting doesn't allow the preferred site backups). In order to make scheduled backups, you have to setup CRON to run periodically. Have a look at [[Installing Moodle#Set_up_cron|Set up cron]] for details.

===How do I backup my whole Moodle site?===

There are two main things you need to make a copy of - the database and the uploaded files. The Moodle scripts themselves are less important, since you can always download a fresh copy if you have to.

There are many ways to do such backups. Here is an outline of a little script you can run on Unix to backup the database (it works well to have such a script run daily via a cron task):

cd /my/backup/directory
mv moodle-database.sql.gz moodle-database-old.sql.gz
mysqldump -h example.com -u myusername --password=mypassword -C -Q -e -a mydatabasename > moodle-database.sql
gzip moodle-database.sql

For the files, you can use rsync regularly to copy only the changed files to another host:

rsync -auvtz --delete -e ssh mysshusername@example.com:/my/server/directory /my/backup/directory/

===What data is not contained in course backups?===

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:
* Quiz questions are only backed up if at least one question from their category has been added to a quiz.
* Scales are only backed up if they are used by at least one activity.

===Error: An error occurred deleting old backup data===

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

* Delete old records from "backup_ids" table: Check the table exists, repair it and try again.

* Delete old records from "backup_files" table: Check the table exists, repair it and try again.

* Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

There are various ways of repairing tables, including using MySQL Admin.

===XML error: not well-formed (invalid token) at line YYYY===

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

* Unzip the problematic backup file under one empty folder.

* Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

* Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

* Test the moodle.xml file again with Firefox until no error was displayed.

* Zip everything again (all the folder contents but the folder itself!).

* Restore the course. It should work now.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

=== Some of your courses weren't saved!! ===

There are two possible causes of this problem:

1. Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.

2. Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking (generally internal zip libraries, try to switch to external executables instead).

== See also ==

*[http://moodle.org/mod/forum/view.php?f=128 Using Moodle: Backup and Restore]
*[http://download.moodle.org/modules/integrations.php Moodle Download: Integrations] - MySQL Admin for download

== External links ==

*[http://www.databasejournal.com/features/mysql/article.php/10897_3300511_2 Repairing Database Corruption in MySQL]

[[Category:Administrator]]
[[Category:FAQ]]

Development:Quiz database structure

2006-02-15T20:18:34Z

Gustav: /* quiz_question_instances */ explain problem with random questions

{{Quiz developer docs}}
==Overview==
The quiz data model has a fairly large pool of database tables, so the first step in explaining them is to provide some order. Conceptually it is possible to distinguish between the tables holding the teacher-supplied data, defining quizzes and questions, and the tables storing all the data that is generated when students interact with the quizzes and questions.

A further simplification is possible by separating out the questiontype specific tables. They are logical extensions to other tables and therefore are not necessary for understanding the general basic model. They are therefore explained on the developer documentation page for the individual [[Quiz developer docs#Question types|question types]].

The diagram below shows how the most important tables are linked to one another.

[[image:Quiz_database_tables.gif]]

==Teacher-supplied data==

===quiz===

The quiz table contains the definition for all the quizzes. Each quiz belongs to a course, reflected by the course id, has a name and a short descriptive text (intro), an opening and a closing time and several fields that store the settings of various quiz options, each of which is explained in the quiz help that is linked to from the quiz settings page.

The only field that requires additional information is the optionsflag, which... I will put an explanation here eventually --[[User:Gustav|Gustav]] 06:02, 5 February 2006 (WST)

For quizzes that contain random questions the $quiz object may acquire an additional property
;questionsinuse
:A comma separated list of questions that are being used in the quiz. This is used by the random questiontype to avoid choosing a question that is already being used.

===quiz_questions===

This table constitutes the item or question bank, i.e. the repository of defined questions. The quiz_questions table defines the data that is common to questions of all types.

;id
:int(10) NOT NULL auto_increment,
:Primary key. This is used as a foreign key in many other tables. for example the quiz_answers table allows to define an arbitrary number of answers that are part of the question. And many questiontypes have their own tables that hold more information about the question.

;category
:int(10) NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_categories|quiz_categories]]

;parent
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. This field is set to zero except in the case of wrapped questions as they are used for example in the multianswer questiontype. When a question wraps around any number of subquestions the subquestions will have their parent id field set to the id of the main question, thus allowing the question to find all its sub-questions (or wrapped questions). If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself. This is also used for hiding random questions from the question list. Their parent field is simply set to their own id.

;name
:varchar(255) NOT NULL default '',
:Question name that is used in question lists on the quiz editing pages

;questiontext
:text NOT NULL,
:Main text of the question

;questiontextformat
:tinyint(2) NOT NULL default '0',

;image
:varchar(255) NOT NULL default '',

;defaultgrade
:int(10) unsigned NOT NULL default '1',
:Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.

;penalty
:float NOT NULL default '0.1',
:The penalty that is applied (if the respective quiz option is set) for an incorrect attempt at the question.

;qtype
:smallint(6) NOT NULL default '0',
:The questiontype of the question. (Constants are defined in locallib.php)

;length
:int(10) unsigned NOT NULL default '1',
:This defines how many question numbers are required for this question. It is generally set to "1", but the description questiontype, for example, sets it to "0", reflecting the fact that it doesn't have a question number.

;stamp
:varchar(255) NOT NULL default '',
:Unique identifier

;version
:int(10) NOT NULL default '1',
:A number representing how often the question was edited.

;hidden
:int(1) unsigned NOT NULL default '0',
:Controls whether to display a question in the question bank list in edit.php. Hiding questions is a mechanism to "delete" questions without removing them from the database and thus to allow them to be restored or "unhidden" at a later stage. Also the (unfinished and disabled) [[Quiz_developer_docs#Question_versioning|versioning feature]] uses the hidden field to prevent older versions of a question from cluttering the user interface.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of the static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these later fields can differ when a question is used in different quizzes.

The runtime fields are added to question objects with the function <code>quiz_get_questions_options()</code> is called. This in turn calls the questiontype specific <code>get_question_options()</code> method for to add the options field.

;maxgrade
:This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in the [[#quiz_question_instances|quiz_question_instances table]].

;instance
:Foreign key: refers to an id in the table [[#quiz_question_instances|quiz_question_instances]]

;options
:Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the <code>get_question_options</code> method.

;name_prefix
:The prefix to be used on all interactions printed as part of the question.

We now deal in alphabetical order with the remaining tables for the teacher-provided data.

===quiz_answers===

This table allows a common way to store one or more teacher-defined answers for each question. It is not mandatory for a questiontype to make use of this table however. A questiontype may choose to store it's teacher-defined answers in an entirely different way, or even to do away with teacher-defined answers and use some other method to mark the student-supplied answer. For example it could calculate the correct answer on the fly.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to [[#quiz_questions|quiz_questions]] table.

;answer
:text NOT NULL,
:The string that represents the teacher-defined answer that will be compared to the student responses for grading and feedback purposes. The format of this field is entirely up to the question type.

;fraction
:varchar(10) NOT NULL default '0.0',
:The fraction of the total mark that the student should earn for giving this particular answer. This could be a negative number for wrong answers. Note that it is stored in a varchar(10) field.

;feedback
:text NOT NULL,
:Text that can be displayed to student as feedback when the student's responses match this particular answer.

In the past there was also a sequence number field was sometimes used to store the order of the different answers and was set to '0' if the order was of no importance.

===quiz_categories===

Categories are provided as a way to organize questions. Each category has a name and a descriptive text (info) and the sortorder as metadata. Categories allow hierarchical nesting via the parent id and can be private or published, i.e. they can be made available to teachers in other courses.

Since categories are simply a means for organising questions they are not vital for understanding how the quiz module works.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;course
:int(10) unsigned NOT NULL default '0',
:Foreign key to the course table

;name
varchar(255) NOT NULL default '',

;info
:text NOT NULL,

;publish
:tinyint(4) NOT NULL default '0',

;stamp
:varchar(255) NOT NULL default '',

;parent int(10)
:unsigned NOT NULL default '0',

;sortorder int(10)
:unsigned NOT NULL default '999',

===quiz_question_instances===

Questions can be assigned different grades in different quizzes. These are stored in this table. This table can also be used to find all the questions assigned to a particular quiz. But note that this is not the same as the questions that are actually used because if the quiz contains random questions then these in turn choose other questions to be used when an attempt is started and these actually used questions are not stored in this table.

While, after a small extension, this table could also fulfill the purpose of storing the order of the questions in a quiz, this is currently still done in the questions field in the [[#quiz|quiz]] table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz|quiz]] table.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz_questions|quiz_questions]] table.

;grade
:smallint(6) NOT NULL default '0',
:The maximum grade assigned to this question in this quiz. This grade was set by the teacher on the [[mod/quiz/edit|quiz editing page]]. At runtime this information is stored in the $question->maxgrade field.

===quiz_question_versions===

This feature is not finished and disabled. The table structure may still change. See [[Quiz developer docs#Question versioning]] for a discussion.

;id
:int(10) unsigned NOT NULL auto_increment,

;quiz
:int(10) unsigned NOT NULL default '0',

;oldquestion
:int(10) unsigned NOT NULL default '0',

;newquestion
:int(10) unsigned NOT NULL default '0',

;userid
:int(10) unsigned NOT NULL default '0',

;timestamp
:int(10) unsigned NOT NULL default '0',

==Student-created data==

===quiz_attempts===

In the quiz_attempts table a record is created each time a user starts an attempt at a quiz. This is one of the important tables and the corresponding $attempt object is passed between many of the quiz module functions and methods.

;id :int(10) unsigned NOT NULL auto_increment,
:Primary key
;uniqueid :int(10) unsigned NOT NULL default '0',
:Primary key since Moodle 1.6 used by [[Quiz database structure#quiz_states|quiz_states table]]. See [[Separating_questions_from_quizzes]] for details.
;quiz
:int(10) unsigned NOT NULL default '0',<br />The id of the quiz that is attempted
;userid
:int(10) unsigned NOT NULL default '0',<br />The id of the user who is attempting the quiz
;attempt
:smallint(6) NOT NULL default '0',<br>It is possible for a user to attempt a quiz several times, therefore the number of the attempt is stored in this field.
;sumgrades
:varchar(10) NOT NULL default '0.0',<br>The (unscaled) grade for the attempt, i.e. if the grades assigned to the questions add up to 8, but the maximum grade for the quiz is set to 10, then the sumgrades field can contain 8 at maximum.
;timestart
:int(10) unsigned NOT NULL default '0',<br>The timestart field is set to the current time when an attempt is started and is never changed afterwards.
;timefinish
:int(10) unsigned NOT NULL default '0',<br>The timefinish field is set to "0" initially and to the current time when the attempt is closed. This is exploited at several places in the code to determine whether an attempt has been closed or not (i.e. closed = timefinish > 0). For all other modifications of an attempt record the timemodified field should be changed as well.
;timemodified
:int(10) unsigned NOT NULL default '0',<br>This should be changed each time data in the record is modified.
;layout
:text NOT NULL,<br>a comma separated list of question ids, with a "0" denoting a page break. Usually the comma separated list ends with ",0".
;preview
:tinyint(3) unsigned NOT NULL default '0',<br>A flag that marks a teacher preview (i.e. an attempt by a user with teacher privileges) that may be automatically deleted when the quiz is previewed again, and which is not taken into account when viewing statistics.

===quiz_states===

States are saved for each interaction with a question. This allows a review of the complete history of a user's interactions with individual questions. The current state is the most important object used by the quiz module run-time code. This $state run-time object has a few additional fields not in the database that will be explained further down. The database fields are:

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;attempt
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_attempts|quiz_attempts]]. In Moodle 1.5 it referred to the id field of that table, since Moodle 1.6 it refers to the uniqueid field. This change was done while [[Separating questions from quizzes]].

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. The attempt id and the question id together sufficiently identify a question instance that a state belongs to.

;originalquestion
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table quiz_questions. It identifies which question was in use when the student attempted the question. This is part of the [[Quiz_developer_docs#Question_versioning|question versioning]] code.

;seq_number
:int(6) unsigned NOT NULL default '0',
:A counter that provides information about the sequence in which the states were created.

;answer
:text NOT NULL,
:This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses. Questiontypes are allowed to deviate from this and handle their response storage in any desired way. Some questiontypes do not use this field but instead store the student response in their own table extending this table.

;timestamp
:int(10) unsigned NOT NULL default '0',
:A time stamp to record when the state was created. This could mainly be useful for audit purposes.

;event
:int(4) unsigned NOT NULL default '0',
:Records the event or interaction type that lead from the previous state to the current one. The field can take the value of any of the following constants (defined in locallib.php):
:*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.

;grade
:varchar(10) NOT NULL default '0.0',
:Calculated from the raw grade by deducting the penalty and rescaling to the defaultgrade value of the question. Note that this is a varchar(10) field like most grade-related fields in the quiz module.

;raw_grade
:varchar(10) NOT NULL default '',
:The grade that was achieved for the question scaled to the question's weight or grade as assigned in the quiz_question_instances table

;penalty
:varchar(10) NOT NULL default '0.0',
:The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous marking events.

In addition to the database fields a few fields are added to the states at run time. They are dealt with by the questiontypes with the methods <code>create_session_and_responses</code>, <code>restore_session_and_responses</code> and <code>save_session_and_responses</code> and are defined as follows.

;sumpenalty
:The cumulative penalty, which can be calculated by adding up all the penalties from previous marking events. For efficiency these cumulative penalties are stored in the table [[#quiz_newest_states|quiz_newest_states]] so that they do not need to be re-calculated each time.

;changed
:This records whether a change has taken place to the run-time state. This is set to false when the state is restored from the database. Any code which changes the question state must set this field to true and must increment seq_number. The <code>quiz_save_question_session()</code> function will save the new state object to the database if the field is set to true.

;responses
:This is automatically set to the value of the database field <code>answer</code> before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indices are determined by the name of the elements after the name_prefix is stripped.

;last_graded
:This field contains another state object representing the most recent graded state in the history of this question attempt. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.

;options
:Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

We now deal in alphabetical order with the remaining tables holding the student-created data.

===quiz_grades===

The quiz_grades table merely stores a student's awarded grade for a quiz. Since it is possible to allow several attempts on a quiz, the grade stored is calculated depending on the quiz setting grademethod. This table exists mainly for convenience, because the values of its fields can be recalculated.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the [[#quiz|quiz]] table

;userid
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the user table

;grade
:double NOT NULL default '0',
:The grade awarded for this quiz to this user

;timemodified
:int(10) unsigned NOT NULL default '0',
:Unix timestamp to be updated each time the grade is changed

===quiz_newest_states===

This table exists only for efficiency reasons:
#Via its 'newest' and 'newgraded' fields it gives attempt.php a way to quickly find the newest state and the newest graded state for an attempt. It allows the construction of SQL to select all the states that need to be loaded on attempt.php or review.php.
#Via its 'sumpenalty' field it gives quiz_apply_penalty() a quick way for getting at the accumulated penalty that needs to be applied. Without this field the penalties from all previous graded states would have to be added up each time. Not a big deal actually because this could be achieved with a single SQL query (using SUM) but this field was introduced when we still had the multiplicative penalty scheme around which would have been more difficult to recompute.

This table was introduced in Moodle 1.5 and is not populated for all states during the upgrade because on sites with a lot of existing states that could take too long. Rather it is done whenever needed by quiz_upgrade_states().

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;attemptid
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_attempts|quiz_attempts]] table. In Moodle 1.5 it referred to the id field of that table, since Moodle 1.6 it refers to the uniqueid field. This change was done while [[Separating questions from quizzes]].

;questionid
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_questions|quiz_questions]] table

;newest
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state for this attempt and this question.

;newgraded
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state created by a grading event.

;sumpenalty
:varchar(10) NOT NULL default '0.0',
This stores the total penalty that this user has accumulated over previous graded responses to this question in this attempt.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz database structure

2006-02-14T16:33:47Z

Gustav: Moved table of contents to the top

{{Quiz developer docs}}
==Overview==
The quiz data model has a fairly large pool of database tables, so the first step in explaining them is to provide some order. Conceptually it is possible to distinguish between the tables holding the teacher-supplied data, defining quizzes and questions, and the tables storing all the data that is generated when students interact with the quizzes and questions.

A further simplification is possible by separating out the questiontype specific tables. They are logical extensions to other tables and therefore are not necessary for understanding the general basic model. They are therefore explained on the developer documentation page for the individual [[Quiz developer docs#Question types|question types]].

The diagram below shows how the most important tables are linked to one another.

[[image:Quiz_database_tables.gif]]

==Teacher-supplied data==

===quiz===

The quiz table contains the definition for all the quizzes. Each quiz belongs to a course, reflected by the course id, has a name and a short descriptive text (intro), an opening and a closing time and several fields that store the settings of various quiz options, each of which is explained in the quiz help that is linked to from the quiz settings page.

The only field that requires additional information is the optionsflag, which... I will put an explanation here eventually --[[User:Gustav|Gustav]] 06:02, 5 February 2006 (WST)

For quizzes that contain random questions the $quiz object may acquire an additional property
;questionsinuse
:A comma separated list of questions that are being used in the quiz. This is used by the random questiontype to avoid choosing a question that is already being used.

===quiz_questions===

This table constitutes the item or question bank, i.e. the repository of defined questions. The quiz_questions table defines the data that is common to questions of all types.

;id
:int(10) NOT NULL auto_increment,
:Primary key. This is used as a foreign key in many other tables. for example the quiz_answers table allows to define an arbitrary number of answers that are part of the question. And many questiontypes have their own tables that hold more information about the question.

;category
:int(10) NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_categories|quiz_categories]]

;parent
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. This field is set to zero except in the case of wrapped questions as they are used for example in the multianswer questiontype. When a question wraps around any number of subquestions the subquestions will have their parent id field set to the id of the main question, thus allowing the question to find all its sub-questions (or wrapped questions). If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself. This is also used for hiding random questions from the question list. Their parent field is simply set to their own id.

;name
:varchar(255) NOT NULL default '',
:Question name that is used in question lists on the quiz editing pages

;questiontext
:text NOT NULL,
:Main text of the question

;questiontextformat
:tinyint(2) NOT NULL default '0',

;image
:varchar(255) NOT NULL default '',

;defaultgrade
:int(10) unsigned NOT NULL default '1',
:Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.

;penalty
:float NOT NULL default '0.1',
:The penalty that is applied (if the respective quiz option is set) for an incorrect attempt at the question.

;qtype
:smallint(6) NOT NULL default '0',
:The questiontype of the question. (Constants are defined in locallib.php)

;length
:int(10) unsigned NOT NULL default '1',
:This defines how many question numbers are required for this question. It is generally set to "1", but the description questiontype, for example, sets it to "0", reflecting the fact that it doesn't have a question number.

;stamp
:varchar(255) NOT NULL default '',
:Unique identifier

;version
:int(10) NOT NULL default '1',
:A number representing how often the question was edited.

;hidden
:int(1) unsigned NOT NULL default '0',
:Controls whether to display a question in the question bank list in edit.php. Hiding questions is a mechanism to "delete" questions without removing them from the database and thus to allow them to be restored or "unhidden" at a later stage. Also the (unfinished and disabled) [[Quiz_developer_docs#Question_versioning|versioning feature]] uses the hidden field to prevent older versions of a question from cluttering the user interface.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of the static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these later fields can differ when a question is used in different quizzes.

The runtime fields are added to question objects with the function <code>quiz_get_questions_options()</code> is called. This in turn calls the questiontype specific <code>get_question_options()</code> method for to add the options field.

;maxgrade
:This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in the [[#quiz_question_instances|quiz_question_instances table]].

;instance
:Foreign key: refers to an id in the table [[#quiz_question_instances|quiz_question_instances]]

;options
:Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the <code>get_question_options</code> method.

;name_prefix
:The prefix to be used on all interactions printed as part of the question.

We now deal in alphabetical order with the remaining tables for the teacher-provided data.

===quiz_answers===

This table allows a common way to store one or more teacher-defined answers for each question. It is not mandatory for a questiontype to make use of this table however. A questiontype may choose to store it's teacher-defined answers in an entirely different way, or even to do away with teacher-defined answers and use some other method to mark the student-supplied answer. For example it could calculate the correct answer on the fly.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to [[#quiz_questions|quiz_questions]] table.

;answer
:text NOT NULL,
:The string that represents the teacher-defined answer that will be compared to the student responses for grading and feedback purposes. The format of this field is entirely up to the question type.

;fraction
:varchar(10) NOT NULL default '0.0',
:The fraction of the total mark that the student should earn for giving this particular answer. This could be a negative number for wrong answers. Note that it is stored in a varchar(10) field.

;feedback
:text NOT NULL,
:Text that can be displayed to student as feedback when the student's responses match this particular answer.

In the past there was also a sequence number field was sometimes used to store the order of the different answers and was set to '0' if the order was of no importance.

===quiz_categories===

Categories are provided as a way to organize questions. Each category has a name and a descriptive text (info) and the sortorder as metadata. Categories allow hierarchical nesting via the parent id and can be private or published, i.e. they can be made available to teachers in other courses.

Since categories are simply a means for organising questions they are not vital for understanding how the quiz module works.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;course
:int(10) unsigned NOT NULL default '0',
:Foreign key to the course table

;name
varchar(255) NOT NULL default '',

;info
:text NOT NULL,

;publish
:tinyint(4) NOT NULL default '0',

;stamp
:varchar(255) NOT NULL default '',

;parent int(10)
:unsigned NOT NULL default '0',

;sortorder int(10)
:unsigned NOT NULL default '999',

===quiz_question_instances===

Questions can be assigned different grades in different quizzes. These are stored in this table.

While, after a small extension, this table could also fulfill the purpose of storing the order of the questions in a quiz, this is currently still done in the questions field in the [[#quiz|quiz]] table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz|quiz]] table.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz_questions|quiz_questions]] table.

;grade
:smallint(6) NOT NULL default '0',
:The maximum grade assigned to this question in this quiz. This grade was set by the teacher on the [[mod/quiz/edit|quiz editing page]]. At runtime this information is stored in the $question->maxgrade field.

===quiz_question_versions===

This feature is not finished and disabled. The table structure may still change. See [[Quiz developer docs#Question versioning]] for a discussion.

;id
:int(10) unsigned NOT NULL auto_increment,

;quiz
:int(10) unsigned NOT NULL default '0',

;oldquestion
:int(10) unsigned NOT NULL default '0',

;newquestion
:int(10) unsigned NOT NULL default '0',

;userid
:int(10) unsigned NOT NULL default '0',

;timestamp
:int(10) unsigned NOT NULL default '0',

==Student-created data==

===quiz_attempts===

In the quiz_attempts table a record is created each time a user starts an attempt at a quiz. This is one of the important tables and the corresponding $attempt object is passed between many of the quiz module functions and methods.

;id :int(10) unsigned NOT NULL auto_increment,
:Primary key
;uniqueid :int(10) unsigned NOT NULL default '0',
:Primary key since Moodle 1.6 used by [[Quiz database structure#quiz_states|quiz_states table]]. See [[Separating_questions_from_quizzes]] for details.
;quiz
:int(10) unsigned NOT NULL default '0',<br />The id of the quiz that is attempted
;userid
:int(10) unsigned NOT NULL default '0',<br />The id of the user who is attempting the quiz
;attempt
:smallint(6) NOT NULL default '0',<br>It is possible for a user to attempt a quiz several times, therefore the number of the attempt is stored in this field.
;sumgrades
:varchar(10) NOT NULL default '0.0',<br>The (unscaled) grade for the attempt, i.e. if the grades assigned to the questions add up to 8, but the maximum grade for the quiz is set to 10, then the sumgrades field can contain 8 at maximum.
;timestart
:int(10) unsigned NOT NULL default '0',<br>The timestart field is set to the current time when an attempt is started and is never changed afterwards.
;timefinish
:int(10) unsigned NOT NULL default '0',<br>The timefinish field is set to "0" initially and to the current time when the attempt is closed. This is exploited at several places in the code to determine whether an attempt has been closed or not (i.e. closed = timefinish > 0). For all other modifications of an attempt record the timemodified field should be changed as well.
;timemodified
:int(10) unsigned NOT NULL default '0',<br>This should be changed each time data in the record is modified.
;layout
:text NOT NULL,<br>a comma separated list of question ids, with a "0" denoting a page break. Usually the comma separated list ends with ",0".
;preview
:tinyint(3) unsigned NOT NULL default '0',<br>A flag that marks a teacher preview (i.e. an attempt by a user with teacher privileges) that may be automatically deleted when the quiz is previewed again, and which is not taken into account when viewing statistics.

===quiz_states===

States are saved for each interaction with a question. This allows a review of the complete history of a user's interactions with individual questions. The current state is the most important object used by the quiz module run-time code. This $state run-time object has a few additional fields not in the database that will be explained further down. The database fields are:

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;attempt
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_attempts|quiz_attempts]]. In Moodle 1.5 it referred to the id field of that table, since Moodle 1.6 it refers to the uniqueid field. This change was done while [[Separating questions from quizzes]].

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. The attempt id and the question id together sufficiently identify a question instance that a state belongs to.

;originalquestion
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table quiz_questions. It identifies which question was in use when the student attempted the question. This is part of the [[Quiz_developer_docs#Question_versioning|question versioning]] code.

;seq_number
:int(6) unsigned NOT NULL default '0',
:A counter that provides information about the sequence in which the states were created.

;answer
:text NOT NULL,
:This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses. Questiontypes are allowed to deviate from this and handle their response storage in any desired way. Some questiontypes do not use this field but instead store the student response in their own table extending this table.

;timestamp
:int(10) unsigned NOT NULL default '0',
:A time stamp to record when the state was created. This could mainly be useful for audit purposes.

;event
:int(4) unsigned NOT NULL default '0',
:Records the event or interaction type that lead from the previous state to the current one. The field can take the value of any of the following constants (defined in locallib.php):
:*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.

;grade
:varchar(10) NOT NULL default '0.0',
:Calculated from the raw grade by deducting the penalty and rescaling to the defaultgrade value of the question. Note that this is a varchar(10) field like most grade-related fields in the quiz module.

;raw_grade
:varchar(10) NOT NULL default '',
:The grade that was achieved for the question scaled to the question's weight or grade as assigned in the quiz_question_instances table

;penalty
:varchar(10) NOT NULL default '0.0',
:The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous marking events.

In addition to the database fields a few fields are added to the states at run time. They are dealt with by the questiontypes with the methods <code>create_session_and_responses</code>, <code>restore_session_and_responses</code> and <code>save_session_and_responses</code> and are defined as follows.

;sumpenalty
:The cumulative penalty, which can be calculated by adding up all the penalties from previous marking events. For efficiency these cumulative penalties are stored in the table [[#quiz_newest_states|quiz_newest_states]] so that they do not need to be re-calculated each time.

;changed
:This records whether a change has taken place to the run-time state. This is set to false when the state is restored from the database. Any code which changes the question state must set this field to true and must increment seq_number. The <code>quiz_save_question_session()</code> function will save the new state object to the database if the field is set to true.

;responses
:This is automatically set to the value of the database field <code>answer</code> before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indices are determined by the name of the elements after the name_prefix is stripped.

;last_graded
:This field contains another state object representing the most recent graded state in the history of this question attempt. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.

;options
:Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

We now deal in alphabetical order with the remaining tables holding the student-created data.

===quiz_grades===

The quiz_grades table merely stores a student's awarded grade for a quiz. Since it is possible to allow several attempts on a quiz, the grade stored is calculated depending on the quiz setting grademethod. This table exists mainly for convenience, because the values of its fields can be recalculated.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the [[#quiz|quiz]] table

;userid
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the user table

;grade
:double NOT NULL default '0',
:The grade awarded for this quiz to this user

;timemodified
:int(10) unsigned NOT NULL default '0',
:Unix timestamp to be updated each time the grade is changed

===quiz_newest_states===

This table exists only for efficiency reasons:
#Via its 'newest' and 'newgraded' fields it gives attempt.php a way to quickly find the newest state and the newest graded state for an attempt. It allows the construction of SQL to select all the states that need to be loaded on attempt.php or review.php.
#Via its 'sumpenalty' field it gives quiz_apply_penalty() a quick way for getting at the accumulated penalty that needs to be applied. Without this field the penalties from all previous graded states would have to be added up each time. Not a big deal actually because this could be achieved with a single SQL query (using SUM) but this field was introduced when we still had the multiplicative penalty scheme around which would have been more difficult to recompute.

This table was introduced in Moodle 1.5 and is not populated for all states during the upgrade because on sites with a lot of existing states that could take too long. Rather it is done whenever needed by quiz_upgrade_states().

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;attemptid
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_attempts|quiz_attempts]] table. In Moodle 1.5 it referred to the id field of that table, since Moodle 1.6 it refers to the uniqueid field. This change was done while [[Separating questions from quizzes]].

;questionid
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_questions|quiz_questions]] table

;newest
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state for this attempt and this question.

;newgraded
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state created by a grading event.

;sumpenalty
:varchar(10) NOT NULL default '0.0',
This stores the total penalty that this user has accumulated over previous graded responses to this question in this attempt.

[[Category:Developer]]
[[Category:Quiz]]

Blocks

2006-02-14T10:51:47Z

Gustav: Improved image layouts

[[Image:Blocks.jpg|thumb|Example of blocks on a course page]]

<p class="note">'''Note for Contributors'''<br />
This page should explain briefly what '''blocks''' are.</p>

On the left and right sides of the course homepage there are side blocks, which can be added, removed and moved around.

To enable arranging blocks (as well as the content of the course), editing should be enabled (click the "Turn editing on" button located in the top right corner of the screen).

[[Image:BlocksEdit.jpg|frame|none|Blocks with the editing icons showing]]

==See also==
Developer documentation: [[Blocks Howto|A Step-by-step Guide To Creating Blocks]]

admin/modules

2006-02-13T22:33:22Z

Gustav: fixed double redirect

#redirect [[Modules (administrator)]]

Blocks

2006-02-13T19:03:20Z

Gustav:

<p class="note">'''Note for Contributors'''<br />
This page should explain briefly what '''blocks''' are.</p>

On the left and right sides of the course homepage there are side blocks, which can be added, removed and moved around.

[[Image:Blocks.jpg]]

To enable arranging blocks (as well as the content of the course), editing should be enabled (click the "Turn editing on" button located in the top right corner of the screen).

[[Image:BlocksEdit.jpg]]

==See also==
Developer documentation: [[Blocks Howto|A Step-by-step Guide To Creating Blocks]]

Development:Matching question type

2006-02-13T15:54:26Z

Gustav: /* quiz_match_sub */ added code field

{{Questiontype developer docs}}

==Database tables==

===quiz_match===

This table is only used in the code for saving matching questions and can therefore be considered redundant.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;subquestions
:varchar(255) NOT NULL default '',
:a comma separated list of ids of the question-answer pairs used in this question. These ids refer to the id field of the quiz_match_sub table.

;shuffleanswers :tinyint(4) NOT NULL default '1',
:a flag that determines whether the answers should be shuffled, provided the quiz settings allows this.

===quiz_match_sub===

The quiz_match_sub extends the quiz_questions table. It stores the pairs of questions and answers (as strings) that need to be matched for a correct solution.

;id
:int(10) unsigned NOT NULL auto_increment,

;code
:int(10) unsigned NOT NULL default '0',
:This field is randomly set to a unique integer. This code will be used to identify the response. The reason we do not simply use the id is that that would make it possible for students to look at the page source and match the answers and questions with the same id.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;questiontext
:text NOT NULL,

;answertext
:varchar(255) NOT NULL default '',

==Response storage==

The matching questiontype needs to store information about the order of its subquestions and the selected responses. Because each subquestion is identified by one record in the quiz_match_sub table, the ids of this table could be used to identify both the question and the response part. This is indeed how it was done until Moodle 1.5. This however had the drawback that students who looked at the page source could figure out which answer belonged to which question. Since Moodle 1.6 the response part is encoded with respect to the new 'code' field in the quiz_match_sub table. The entry in the 'code' field is randomly created with rand() when a subquestion is created.

For each subquestion a '-'-separated pair is created, giving first the id of the record that provided the subquestion and then the code of the record that provided the selected response. E.g. 1-3 means that the answer of the third question was selected for the first subquestion. If no response is selected, the second entry in the pair is set to '0'. These pairs are then put into a comma separated list to allow each subquestion to store a response.

==Question options object==

The $questions->options object has the properties

;subquestions:an array of all the records from the quiz_match_sub table for this question, i.e., all the question-answer pairs, indexed by the ids.
;shuffleanswers:a flag that indicates whether the answers should be shuffled, provided this is enabled at the quiz level.

==State options object==

The $state->options object has a single property ''''subquestions'''' which holds an array of objects representing the question-answer pairs, indexed by the ids. Each entry from the table is an object with the following properties:
;id
;question
;questiontext
;answertext
;options
The '''options''' property in turn is an object with a single property '''answers''' which is an array of objects with the following properties:
;id:the id of this subquestion
;answer:the answertext for this subquestion
;fraction:this is always set to 1 and has the effect that all subquestions carry the same weight.

The reason this is done in such a complicated manner is that it makes it easier to reuse the code for the matching question type also for the random short-answer questiontype.

[[Category:Developer]]
[[Category:Quiz]]

Development:Matching question type

2006-02-13T15:50:21Z

Gustav: /* quiz_match */ type

{{Questiontype developer docs}}

==Database tables==

===quiz_match===

This table is only used in the code for saving matching questions and can therefore be considered redundant.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;subquestions
:varchar(255) NOT NULL default '',
:a comma separated list of ids of the question-answer pairs used in this question. These ids refer to the id field of the quiz_match_sub table.

;shuffleanswers :tinyint(4) NOT NULL default '1',
:a flag that determines whether the answers should be shuffled, provided the quiz settings allows this.

===quiz_match_sub===

The quiz_match_sub extends the quiz_questions table. It stores the pairs of questions and answers (as strings) that need to be matched for a correct solution.

;id
:int(10) unsigned NOT NULL auto_increment,

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;questiontext
:text NOT NULL,

;answertext
:varchar(255) NOT NULL default '',

==Response storage==

The matching questiontype needs to store information about the order of its subquestions and the selected responses. Because each subquestion is identified by one record in the quiz_match_sub table, the ids of this table could be used to identify both the question and the response part. This is indeed how it was done until Moodle 1.5. This however had the drawback that students who looked at the page source could figure out which answer belonged to which question. Since Moodle 1.6 the response part is encoded with respect to the new 'code' field in the quiz_match_sub table. The entry in the 'code' field is randomly created with rand() when a subquestion is created.

For each subquestion a '-'-separated pair is created, giving first the id of the record that provided the subquestion and then the code of the record that provided the selected response. E.g. 1-3 means that the answer of the third question was selected for the first subquestion. If no response is selected, the second entry in the pair is set to '0'. These pairs are then put into a comma separated list to allow each subquestion to store a response.

==Question options object==

The $questions->options object has the properties

;subquestions:an array of all the records from the quiz_match_sub table for this question, i.e., all the question-answer pairs, indexed by the ids.
;shuffleanswers:a flag that indicates whether the answers should be shuffled, provided this is enabled at the quiz level.

==State options object==

The $state->options object has a single property ''''subquestions'''' which holds an array of objects representing the question-answer pairs, indexed by the ids. Each entry from the table is an object with the following properties:
;id
;question
;questiontext
;answertext
;options
The '''options''' property in turn is an object with a single property '''answers''' which is an array of objects with the following properties:
;id:the id of this subquestion
;answer:the answertext for this subquestion
;fraction:this is always set to 1 and has the effect that all subquestions carry the same weight.

The reason this is done in such a complicated manner is that it makes it easier to reuse the code for the matching question type also for the random short-answer questiontype.

[[Category:Developer]]
[[Category:Quiz]]

Development:Multiple Choice question type

2006-02-13T15:49:41Z

Gustav: /* quiz_multichoice table */ added shuffleanswers field

{{Questiontype developer docs}}
==quiz_multichoice table==

The quiz_multichoice table is an extension of the [[Quiz database structure#quiz_questions|quiz_questions table]].

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field of the [[Quiz database structure#quiz_questions|quiz_questions table]]

;layout
:tinyint(4) NOT NULL default '0',
:does not seem to be used

;answers
:varchar(255) NOT NULL default '',
:stores the order of the answers. This should be superseded by the seq_number field in the quiz_answers table

;single
:tinyint(4) NOT NULL default '0',
:A flag signaling, whether only one option or multiple options can be chosen.

;shuffleanswers :tinyint(4) NOT NULL default '1',
:a flag that determines whether the answers should be shuffled, provided the quiz settings allows this.

==Response storage==

What is stored in $state->responses depends on whether only a single answer is allowed or whether multiple answers are allowed. For single answers the answer id is saved in $state->responses[''], whereas for the multiple answers case the $state->responses array is indexed by the answer ids and the values are also the answer ids (i.e. key = value).

The multichoice questiontype stores both the order of the choices and the selected choices in the answer field of the quiz_states table. Storing the order is optional (mainly to provide backward compatibility with previous versions of this questiontype). The order is stored as a comma separated list of answer ids (i.e. form the quiz_answers table). It is separated with a colon (':') from the selected responses, which are also stored as a comma separated list of answer ids. For example 1,3,2,4:2,4 means that the answers were shown in the order 1, 3, 2 and then 4 and the answers 2 and 4 were checked. Note that the list of selected responses is usually shorter (and often contains only one id) than the list that provides the order.

Comment by [[User:Gustav]]: It is logically not very nice that the quiz_states table is used to store the order of answers in the multiple choice question. This is information that does not change in between states. It is really associated with the attempt and the question, not the state. Unfortunately we don't have a natural table to store such information.

==Question options object==

$question->options is set to the object from the appropriate record in the quiz_multichoice table but with the 'answers' field replaced by an array of answer objects from the [[Quiz database structure#quiz_answers|quiz_answers table]].

==State options object==

$state->options has a single property '''order''' that is set to an array of answerids.

[[Category:Developer]]
[[Category:Quiz]]

Development:Random Short-Answer Matching question type

2006-02-13T15:49:14Z

Gustav: /* Database tables */ added shuffleanswers field

{{Questiontype developer docs}}

==Database tables==
The '''quiz_randomsamatch''' table is an extension of the quiz_questions table

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key
;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field of the quiz_questions table
;choose
:int(10) unsigned NOT NULL default '4',
:The number of shortanswer questions should be randomly chosen to build this randomsamatch question.

;shuffleanswers :tinyint(4) NOT NULL default '1',
:a flag that determines whether the answers should be shuffled, provided the quiz settings allows this.

==Response storage==
The random shortanswer matching questiontype reuses the save_session_and_responses method of the matching questiontype and therefore stores its responses in the same format. The difference is that the first id in the pair is the question id (quiz_questions) of the selected shortanswer and the second id is the id of the first correct answer that is found ofr that shortanswer question in the quiz_answers table.

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Development:Matching question type

2006-02-13T15:48:00Z

Gustav: /* quiz_match */ added shuffleanswers field

{{Questiontype developer docs}}

==Database tables==

===quiz_match===

This table is only used in the code for saving matching questions and can therefore be considered redundant.

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;subquestions
:varchar(255) NOT NULL default '',
:a comma separated list of ids of the question-answer pairs used in this question. These ids refer to the id field of the quiz_match_sub table.

;shuffleanswers :tinyint(4) NOT NULL default '1',
:a flag that determines whether the answers should be shuffled, provided the quiz settings allows this.

===quiz_match_sub===

The quiz_match_sub extends the quiz_questions table. It stores the pairs of questions and answers (as strings) that need to be matched for a correct solution.

;id
:int(10) unsigned NOT NULL auto_increment,

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;questiontext
:text NOT NULL,

;answertext
:varchar(255) NOT NULL default '',

==Response storage==

The matching questiontype needs to store information about the order of its subquestions and the selected responses. Because each subquestion is identified by one record in the quiz_match_sub table, the ids of this table could be used to identify both the question and the response part. This is indeed how it was done until Moodle 1.5. This however had the drawback that students who looked at the page source could figure out which answer belonged to which question. Since Moodle 1.6 the response part is encoded with respect to the new 'code' field in the quiz_match_sub table. The entry in the 'code' field is randomly created with rand() when a subquestion is created.

For each subquestion a '-'-separated pair is created, giving first the id of the record that provided the subquestion and then the code of the record that provided the selected response. E.g. 1-3 means that the answer of the third question was selected for the first subquestion. If no response is selected, the second entry in the pair is set to '0'. These pairs are then put into a comma separated list to allow each subquestion to store a response.

==Question options object==

The $questions->options object has the properties

;subquestions:an array of all the records from the quiz_match_sub table for this question, i.e., all the question-answer pairs, indexed by the ids.
;shuffleanswers:a flag that indicates whether the answers should be shuffled, provided this is enabled at the quiz level.

==State options object==

The $state->options object has a single property ''''subquestions'''' which holds an array of objects representing the question-answer pairs, indexed by the ids. Each entry from the table is an object with the following properties:
;id
;question
;questiontext
;answertext
;options
The '''options''' property in turn is an object with a single property '''answers''' which is an array of objects with the following properties:
;id:the id of this subquestion
;answer:the answertext for this subquestion
;fraction:this is always set to 1 and has the effect that all subquestions carry the same weight.

The reason this is done in such a complicated manner is that it makes it easier to reuse the code for the matching question type also for the random short-answer questiontype.

[[Category:Developer]]
[[Category:Quiz]]

Development:Matching question type

2006-02-13T15:45:05Z

Gustav: /* Response storage */ now using 'code' field

{{Questiontype developer docs}}

==Database tables==

===quiz_match===

This table is only used in the code for saving matching questions and can therefore be considered redundant.

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;subquestions
:varchar(255) NOT NULL default '',

===quiz_match_sub===

The quiz_match_sub extends the quiz_questions table. It stores the pairs of questions and answers (as strings) that need to be matched for a correct solution.

;id
:int(10) unsigned NOT NULL auto_increment,

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;questiontext
:text NOT NULL,

;answertext
:varchar(255) NOT NULL default '',

==Response storage==

The matching questiontype needs to store information about the order of its subquestions and the selected responses. Because each subquestion is identified by one record in the quiz_match_sub table, the ids of this table could be used to identify both the question and the response part. This is indeed how it was done until Moodle 1.5. This however had the drawback that students who looked at the page source could figure out which answer belonged to which question. Since Moodle 1.6 the response part is encoded with respect to the new 'code' field in the quiz_match_sub table. The entry in the 'code' field is randomly created with rand() when a subquestion is created.

For each subquestion a '-'-separated pair is created, giving first the id of the record that provided the subquestion and then the code of the record that provided the selected response. E.g. 1-3 means that the answer of the third question was selected for the first subquestion. If no response is selected, the second entry in the pair is set to '0'. These pairs are then put into a comma separated list to allow each subquestion to store a response.

==Question options object==

The $questions->options object has the properties

;subquestions:an array of all the records from the quiz_match_sub table for this question, i.e., all the question-answer pairs, indexed by the ids.
;shuffleanswers:a flag that indicates whether the answers should be shuffled, provided this is enabled at the quiz level.

==State options object==

The $state->options object has a single property ''''subquestions'''' which holds an array of objects representing the question-answer pairs, indexed by the ids. Each entry from the table is an object with the following properties:
;id
;question
;questiontext
;answertext
;options
The '''options''' property in turn is an object with a single property '''answers''' which is an array of objects with the following properties:
;id:the id of this subquestion
;answer:the answertext for this subquestion
;fraction:this is always set to 1 and has the effect that all subquestions carry the same weight.

The reason this is done in such a complicated manner is that it makes it easier to reuse the code for the matching question type also for the random short-answer questiontype.

[[Category:Developer]]
[[Category:Quiz]]

Development:Matching question type

2006-02-13T14:15:54Z

Gustav: /* State options object */

{{Questiontype developer docs}}

==Database tables==

===quiz_match===

This table is only used in the code for saving matching questions and can therefore be considered redundant.

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;subquestions
:varchar(255) NOT NULL default '',

===quiz_match_sub===

The quiz_match_sub extends the quiz_questions table. It stores the pairs of questions and answers (as strings) that need to be matched for a correct solution.

;id
:int(10) unsigned NOT NULL auto_increment,

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field in the [[Quiz database structure#quiz_questions|quiz_questions table]]

;questiontext
:text NOT NULL,

;answertext
:varchar(255) NOT NULL default '',

==Response storage==

The matching questiontype needs to store information about the order of its subquestions and the selected responses. Because each subquestion is identified by one record in the quiz_match_sub table, the ids of this table are used to identify both the question and the response part. For each subquestion a '-'-separated pair is created, giving first the id of the record that provided the subquestion and then the id of the record that provided the selected response. E.g. 1-3 means that the answer of the third question was selected for the first subquestion. Correct responses are always pairs of identical ids, e.g 2-2. If no response is selected, the second id in the pair is set to '0'. These pairs are then put into a comma separated list to allow each subquestion to store a response.

==Question options object==

The $questions->options object has the properties

;subquestions:an array of all the records from the quiz_match_sub table for this question, i.e., all the question-answer pairs, indexed by the ids.
;shuffleanswers:a flag that indicates whether the answers should be shuffled, provided this is enabled at the quiz level.

==State options object==

The $state->options object has a single property ''''subquestions'''' which holds an array of objects representing the question-answer pairs, indexed by the ids. Each entry from the table is an object with the following properties:
;id
;question
;questiontext
;answertext
;options
The '''options''' property in turn is an object with a single property '''answers''' which is an array of objects with the following properties:
;id:the id of this subquestion
;answer:the answertext for this subquestion
;fraction:this is always set to 1 and has the effect that all subquestions carry the same weight.

The reason this is done in such a complicated manner is that it makes it easier to reuse the code for the matching question type also for the random short-answer questiontype.

[[Category:Developer]]
[[Category:Quiz]]

Development:Matching question type

2006-02-13T14:01:44Z

Gustav: /* Question options object */ added shuffleanswers

Development talk:Developer documentation

2006-02-13T12:39:52Z

Gustav:

After discussions with Helen I think that this page should have a section "Current development projects" which should have the links that are currently on the [[Developer notes]] page. That page should then simply be redirected to [[Developer documentation]]. I find it important to be able to have an overview over everything on this main page. I am not worried about this page being long, the table of contents at the top allows one to easily jump to the section of interest. --[[User:Gustav|Gustav]] 20:39, 13 February 2006 (WST)

Development:Developer documentation

2006-02-13T10:36:12Z

Gustav: /* Guides for developers */ moved link to previous section

==How you can contribute==

The M in Moodle stands for 'Modular'. There are many different types of components that you can contribute that can be plugged into Moodle to provide additional funtionality. Even if you are not a programmer there are things you can change or help with.
*[[Activity modules]]
*[[Blocks Howto|Blocks]]
*[[Themes]]
*[[Translation|Translations]]
*[[Text filters]]
*[[Resource types]]
*[[Assignment types]]
*[[Question types]]
*[[Question import/export formats]]
*[[Quiz reports]]
*[[Database Schemas|Database schemas]]
*[[Course formats]]
You can also help a lot by
*[[Bug tracker|Participating in the bug tracker]]

==Guides for developers==
*[[Moodle architecture]]
*[[Coding|Coding guidelines]]
*[[Interface_guidelines]]
*[[CVS|Moodle CVS for developers]]

==Plans for the future==
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.
*[[Roadmap]]
*[[Developer notes]]
*[[Developer conference|Developer conferences]]

==Documentation for core components==
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

*[[UTF-8 migration|Migration to UTF-8]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]

==Documentation for contributed code==
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib branch] of the Moodle [[CVS]] repository. Developer documentation for these components should be listed here.
* .

== Developer resources and tools ==

*[http://moodle.org/bugs/ Moodle bug tracker] - bug reports, feature requests and other tracked issues
*[http://cvs.sourceforge.net/viewcvs.py/moodle/moodle/ CVS code]
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code
*[http://moodle.org/mod/resource/view.php?id=1267 Core API]
*[http://moodle.sourceforge.net/dhawes-phpdoc/ Moodle PHP doc reference]
*[[Unmerged files|1.4 and 1.5 un-merged files]]

==See also==
*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services
*[[Presentations]]
*[[Moodle manuals]]
*[[Using Moodle book]]

[[Category:Core]]
[[Category:Developer]]

Development:Developer documentation

2006-02-13T10:33:01Z

Gustav: /* How you can contribute */ extended the list of ways to contribute

==How you can contribute==

The M in Moodle stands for 'Modular'. There are many different types of components that you can contribute that can be plugged into Moodle to provide additional funtionality. Even if you are not a programmer there are things you can change or help with.
*[[Activity modules]]
*[[Blocks Howto|Blocks]]
*[[Themes]]
*[[Translation|Translations]]
*[[Text filters]]
*[[Resource types]]
*[[Assignment types]]
*[[Question types]]
*[[Question import/export formats]]
*[[Quiz reports]]
*[[Database Schemas|Database schemas]]
*[[Course formats]]
You can also help a lot by
*[[Bug tracker|Participating in the bug tracker]]

==Guides for developers==
*[[Moodle architecture]]
*[[Coding|Coding guidelines]]
*[[Interface_guidelines]]
*[[CVS|Moodle CVS for developers]]
*[[Blocks Howto|A Step-by-step Guide To Creating Blocks]]

==Plans for the future==
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.
*[[Roadmap]]
*[[Developer notes]]
*[[Developer conference|Developer conferences]]

==Documentation for core components==
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

*[[UTF-8 migration|Migration to UTF-8]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]

==Documentation for contributed code==
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib branch] of the Moodle [[CVS]] repository. Developer documentation for these components should be listed here.
* .

== Developer resources and tools ==

*[http://moodle.org/bugs/ Moodle bug tracker] - bug reports, feature requests and other tracked issues
*[http://cvs.sourceforge.net/viewcvs.py/moodle/moodle/ CVS code]
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code
*[http://moodle.org/mod/resource/view.php?id=1267 Core API]
*[http://moodle.sourceforge.net/dhawes-phpdoc/ Moodle PHP doc reference]
*[[Unmerged files|1.4 and 1.5 un-merged files]]

==See also==
*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services
*[[Presentations]]
*[[Moodle manuals]]
*[[Using Moodle book]]

[[Category:Core]]
[[Category:Developer]]

Development:Developer documentation

2006-02-13T10:09:30Z

Gustav: Section for contributed code

==How you can contribute==

Even if you are not a programmer there are things you can change or help with.
*[[Activity modules]]
*[[Themes]]
*[[Translation]]
*[[Database Schemas|Database schemas]]
*[[Course formats]]
*[[Bug tracker|Participating in the bug tracker]]

==Guides for developers==
*[[Moodle architecture]]
*[[Coding|Coding guidelines]]
*[[Interface_guidelines]]
*[[CVS|Moodle CVS for developers]]
*[[Blocks Howto|A Step-by-step Guide To Creating Blocks]]

==Plans for the future==
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.
*[[Roadmap]]
*[[Developer notes]]
*[[Developer conference|Developer conferences]]

==Documentation for core components==
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

*[[UTF-8 migration|Migration to UTF-8]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]

==Documentation for contributed code==
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib branch] of the Moodle [[CVS]] repository. Developer documentation for these components should be listed here.
* .

== Developer resources and tools ==

*[http://moodle.org/bugs/ Moodle bug tracker] - bug reports, feature requests and other tracked issues
*[http://cvs.sourceforge.net/viewcvs.py/moodle/moodle/ CVS code]
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code
*[http://moodle.org/mod/resource/view.php?id=1267 Core API]
*[http://moodle.sourceforge.net/dhawes-phpdoc/ Moodle PHP doc reference]
*[[Unmerged files|1.4 and 1.5 un-merged files]]

==See also==
*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services
*[[Presentations]]
*[[Moodle manuals]]
*[[Using Moodle book]]

[[Category:Core]]
[[Category:Developer]]

Development:Developer documentation

2006-02-13T09:52:10Z

Gustav: /* Plans for the future */ stress importance of forum discussions

==How you can contribute==

Even if you are not a programmer there are things you can change or help with.
*[[Activity modules]]
*[[Themes]]
*[[Translation]]
*[[Database Schemas|Database schemas]]
*[[Course formats]]
*[[Bug tracker|Participating in the bug tracker]]

==Guides for developers==
*[[Moodle architecture]]
*[[Coding|Coding guidelines]]
*[[Interface_guidelines]]
*[[CVS|Moodle CVS for developers]]
*[[Blocks Howto|A Step-by-step Guide To Creating Blocks]]

==Plans for the future==
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.
*[[Roadmap]]
*[[Developer notes]]
*[[Developer conference|Developer conferences]]

==Documentation for specific components==
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

*[[UTF-8 migration|Migration to UTF-8]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]

== Developer resources and tools ==

*[http://moodle.org/bugs/ Moodle bug tracker] - bug reports, feature requests and other tracked issues
*[http://cvs.sourceforge.net/viewcvs.py/moodle/moodle/ CVS code]
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code
*[http://moodle.org/mod/resource/view.php?id=1267 Core API]
*[http://moodle.sourceforge.net/dhawes-phpdoc/ Moodle PHP doc reference]
*[[Unmerged files|1.4 and 1.5 un-merged files]]

==See also==
*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services
*[[Presentations]]
*[[Moodle manuals]]
*[[Using Moodle book]]

[[Category:Core]]
[[Category:Developer]]

Development:Developer documentation

2006-02-13T09:45:56Z

Gustav: /* Documentation for specific components */ now for existing code only

Development:Developer notes

2006-02-12T15:00:42Z

Gustav: Moved some stuff to the main Developer documentation

<p class="note"> '''Note for contributors:''' This area is for developers to work on various bits of code and documentation as necessary. Once material has matured it should be linked to from the main [[Developer documentation]] page.
Initial text has been taken from [http://moodle.org/course/view.php?id=5 Using Moodle] Developer Wiki. If you find any text missing, please email docs AT moodle DOT org.</p>

*[[Forum development|Forum functional upgrade]]
*[[Other lang issues|Language issues]]
*[[MoodleDocs development]]
*[[Usability]]
*[[Blogs and forums|Blogs, forums and the nature of discussion]]
*[[Document Management API]]
*[[Filters schema]]
*[[Filterall support]]
*[[Application/session variables]]
*[[Wiki development|Wiki module development]]

[[Category:Developer]]

Development:Developer documentation

2006-02-12T14:56:23Z

Gustav: Reorganised and extended

Development:Quiz database structure

2006-02-12T14:15:53Z

Gustav: /* quiz_newest_states */ about uniqueid

{{Quiz developer docs}}The quiz data model has a fairly large pool of database tables, so the first step in explaining them is to provide some order. Conceptually it is possible to distinguish between the tables holding the teacher-supplied data, defining quizzes and questions, and the tables storing all the data that is generated when students interact with the quizzes and questions.

A further simplification is possible by separating out the questiontype specific tables. They are logical extensions to other tables and therefore are not necessary for understanding the general basic model. They are therefore explained on the developer documentation page for the individual [[Quiz developer docs#Question types|question types]].

The diagram below shows how the most important tables are linked to one another.

[[image:Quiz_database_tables.gif]]

==Teacher-supplied data==

===quiz===

The quiz table contains the definition for all the quizzes. Each quiz belongs to a course, reflected by the course id, has a name and a short descriptive text (intro), an opening and a closing time and several fields that store the settings of various quiz options, each of which is explained in the quiz help that is linked to from the quiz settings page.

The only field that requires additional information is the optionsflag, which... I will put an explanation here eventually --[[User:Gustav|Gustav]] 06:02, 5 February 2006 (WST)

For quizzes that contain random questions the $quiz object may acquire an additional property
;questionsinuse
:A comma separated list of questions that are being used in the quiz. This is used by the random questiontype to avoid choosing a question that is already being used.

===quiz_questions===

This table constitutes the item or question bank, i.e. the repository of defined questions. The quiz_questions table defines the data that is common to questions of all types.

;id
:int(10) NOT NULL auto_increment,
:Primary key. This is used as a foreign key in many other tables. for example the quiz_answers table allows to define an arbitrary number of answers that are part of the question. And many questiontypes have their own tables that hold more information about the question.

;category
:int(10) NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_categories|quiz_categories]]

;parent
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. This field is set to zero except in the case of wrapped questions as they are used for example in the multianswer questiontype. When a question wraps around any number of subquestions the subquestions will have their parent id field set to the id of the main question, thus allowing the question to find all its sub-questions (or wrapped questions). If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself. This is also used for hiding random questions from the question list. Their parent field is simply set to their own id.

;name
:varchar(255) NOT NULL default '',
:Question name that is used in question lists on the quiz editing pages

;questiontext
:text NOT NULL,
:Main text of the question

;questiontextformat
:tinyint(2) NOT NULL default '0',

;image
:varchar(255) NOT NULL default '',

;defaultgrade
:int(10) unsigned NOT NULL default '1',
:Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.

;penalty
:float NOT NULL default '0.1',
:The penalty that is applied (if the respective quiz option is set) for an incorrect attempt at the question.

;qtype
:smallint(6) NOT NULL default '0',
:The questiontype of the question. (Constants are defined in locallib.php)

;length
:int(10) unsigned NOT NULL default '1',
:This defines how many question numbers are required for this question. It is generally set to "1", but the description questiontype, for example, sets it to "0", reflecting the fact that it doesn't have a question number.

;stamp
:varchar(255) NOT NULL default '',
:Unique identifier

;version
:int(10) NOT NULL default '1',
:A number representing how often the question was edited.

;hidden
:int(1) unsigned NOT NULL default '0',
:Controls whether to display a question in the question bank list in edit.php. Hiding questions is a mechanism to "delete" questions without removing them from the database and thus to allow them to be restored or "unhidden" at a later stage. Also the (unfinished and disabled) [[Quiz_developer_docs#Question_versioning|versioning feature]] uses the hidden field to prevent older versions of a question from cluttering the user interface.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of the static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these later fields can differ when a question is used in different quizzes.

The runtime fields are added to question objects with the function <code>quiz_get_questions_options()</code> is called. This in turn calls the questiontype specific <code>get_question_options()</code> method for to add the options field.

;maxgrade
:This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in the [[#quiz_question_instances|quiz_question_instances table]].

;instance
:Foreign key: refers to an id in the table [[#quiz_question_instances|quiz_question_instances]]

;options
:Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the <code>get_question_options</code> method.

;name_prefix
:The prefix to be used on all interactions printed as part of the question.

We now deal in alphabetical order with the remaining tables for the teacher-provided data.

===quiz_answers===

This table allows a common way to store one or more teacher-defined answers for each question. It is not mandatory for a questiontype to make use of this table however. A questiontype may choose to store it's teacher-defined answers in an entirely different way, or even to do away with teacher-defined answers and use some other method to mark the student-supplied answer. For example it could calculate the correct answer on the fly.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to [[#quiz_questions|quiz_questions]] table.

;answer
:text NOT NULL,
:The string that represents the teacher-defined answer that will be compared to the student responses for grading and feedback purposes. The format of this field is entirely up to the question type.

;fraction
:varchar(10) NOT NULL default '0.0',
:The fraction of the total mark that the student should earn for giving this particular answer. This could be a negative number for wrong answers. Note that it is stored in a varchar(10) field.

;feedback
:text NOT NULL,
:Text that can be displayed to student as feedback when the student's responses match this particular answer.

In the past there was also a sequence number field was sometimes used to store the order of the different answers and was set to '0' if the order was of no importance.

===quiz_categories===

Categories are provided as a way to organize questions. Each category has a name and a descriptive text (info) and the sortorder as metadata. Categories allow hierarchical nesting via the parent id and can be private or published, i.e. they can be made available to teachers in other courses.

Since categories are simply a means for organising questions they are not vital for understanding how the quiz module works.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;course
:int(10) unsigned NOT NULL default '0',
:Foreign key to the course table

;name
varchar(255) NOT NULL default '',

;info
:text NOT NULL,

;publish
:tinyint(4) NOT NULL default '0',

;stamp
:varchar(255) NOT NULL default '',

;parent int(10)
:unsigned NOT NULL default '0',

;sortorder int(10)
:unsigned NOT NULL default '999',

===quiz_question_instances===

Questions can be assigned different grades in different quizzes. These are stored in this table.

While, after a small extension, this table could also fulfill the purpose of storing the order of the questions in a quiz, this is currently still done in the questions field in the [[#quiz|quiz]] table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz|quiz]] table.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz_questions|quiz_questions]] table.

;grade
:smallint(6) NOT NULL default '0',
:The maximum grade assigned to this question in this quiz. This grade was set by the teacher on the [[mod/quiz/edit|quiz editing page]]. At runtime this information is stored in the $question->maxgrade field.

===quiz_question_versions===

This feature is not finished and disabled. The table structure may still change. See [[Quiz developer docs#Question versioning]] for a discussion.

;id
:int(10) unsigned NOT NULL auto_increment,

;quiz
:int(10) unsigned NOT NULL default '0',

;oldquestion
:int(10) unsigned NOT NULL default '0',

;newquestion
:int(10) unsigned NOT NULL default '0',

;userid
:int(10) unsigned NOT NULL default '0',

;timestamp
:int(10) unsigned NOT NULL default '0',

==Student-created data==

===quiz_attempts===

In the quiz_attempts table a record is created each time a user starts an attempt at a quiz. This is one of the important tables and the corresponding $attempt object is passed between many of the quiz module functions and methods.

;id :int(10) unsigned NOT NULL auto_increment,
:Primary key
;uniqueid :int(10) unsigned NOT NULL default '0',
:Primary key since Moodle 1.6 used by [[Quiz database structure#quiz_states|quiz_states table]]. See [[Separating_questions_from_quizzes]] for details.
;quiz
:int(10) unsigned NOT NULL default '0',<br />The id of the quiz that is attempted
;userid
:int(10) unsigned NOT NULL default '0',<br />The id of the user who is attempting the quiz
;attempt
:smallint(6) NOT NULL default '0',<br>It is possible for a user to attempt a quiz several times, therefore the number of the attempt is stored in this field.
;sumgrades
:varchar(10) NOT NULL default '0.0',<br>The (unscaled) grade for the attempt, i.e. if the grades assigned to the questions add up to 8, but the maximum grade for the quiz is set to 10, then the sumgrades field can contain 8 at maximum.
;timestart
:int(10) unsigned NOT NULL default '0',<br>The timestart field is set to the current time when an attempt is started and is never changed afterwards.
;timefinish
:int(10) unsigned NOT NULL default '0',<br>The timefinish field is set to "0" initially and to the current time when the attempt is closed. This is exploited at several places in the code to determine whether an attempt has been closed or not (i.e. closed = timefinish > 0). For all other modifications of an attempt record the timemodified field should be changed as well.
;timemodified
:int(10) unsigned NOT NULL default '0',<br>This should be changed each time data in the record is modified.
;layout
:text NOT NULL,<br>a comma separated list of question ids, with a "0" denoting a page break. Usually the comma separated list ends with ",0".
;preview
:tinyint(3) unsigned NOT NULL default '0',<br>A flag that marks a teacher preview (i.e. an attempt by a user with teacher privileges) that may be automatically deleted when the quiz is previewed again, and which is not taken into account when viewing statistics.

===quiz_states===

States are saved for each interaction with a question. This allows a review of the complete history of a user's interactions with individual questions. The current state is the most important object used by the quiz module run-time code. This $state run-time object has a few additional fields not in the database that will be explained further down. The database fields are:

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;attempt
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_attempts|quiz_attempts]]. In Moodle 1.5 it referred to the id field of that table, since Moodle 1.6 it refers to the uniqueid field. This change was done while [[Separating questions from quizzes]].

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. The attempt id and the question id together sufficiently identify a question instance that a state belongs to.

;originalquestion
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table quiz_questions. It identifies which question was in use when the student attempted the question. This is part of the [[Quiz_developer_docs#Question_versioning|question versioning]] code.

;seq_number
:int(6) unsigned NOT NULL default '0',
:A counter that provides information about the sequence in which the states were created.

;answer
:text NOT NULL,
:This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses. Questiontypes are allowed to deviate from this and handle their response storage in any desired way. Some questiontypes do not use this field but instead store the student response in their own table extending this table.

;timestamp
:int(10) unsigned NOT NULL default '0',
:A time stamp to record when the state was created. This could mainly be useful for audit purposes.

;event
:int(4) unsigned NOT NULL default '0',
:Records the event or interaction type that lead from the previous state to the current one. The field can take the value of any of the following constants (defined in locallib.php):
:*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.

;grade
:varchar(10) NOT NULL default '0.0',
:Calculated from the raw grade by deducting the penalty and rescaling to the defaultgrade value of the question. Note that this is a varchar(10) field like most grade-related fields in the quiz module.

;raw_grade
:varchar(10) NOT NULL default '',
:The grade that was achieved for the question scaled to the question's weight or grade as assigned in the quiz_question_instances table

;penalty
:varchar(10) NOT NULL default '0.0',
:The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous marking events.

In addition to the database fields a few fields are added to the states at run time. They are dealt with by the questiontypes with the methods <code>create_session_and_responses</code>, <code>restore_session_and_responses</code> and <code>save_session_and_responses</code> and are defined as follows.

;sumpenalty
:The cumulative penalty, which can be calculated by adding up all the penalties from previous marking events. For efficiency these cumulative penalties are stored in the table [[#quiz_newest_states|quiz_newest_states]] so that they do not need to be re-calculated each time.

;changed
:This records whether a change has taken place to the run-time state. This is set to false when the state is restored from the database. Any code which changes the question state must set this field to true and must increment seq_number. The <code>quiz_save_question_session()</code> function will save the new state object to the database if the field is set to true.

;responses
:This is automatically set to the value of the database field <code>answer</code> before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indices are determined by the name of the elements after the name_prefix is stripped.

;last_graded
:This field contains another state object representing the most recent graded state in the history of this question attempt. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.

;options
:Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

We now deal in alphabetical order with the remaining tables holding the student-created data.

===quiz_grades===

The quiz_grades table merely stores a student's awarded grade for a quiz. Since it is possible to allow several attempts on a quiz, the grade stored is calculated depending on the quiz setting grademethod. This table exists mainly for convenience, because the values of its fields can be recalculated.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the [[#quiz|quiz]] table

;userid
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the user table

;grade
:double NOT NULL default '0',
:The grade awarded for this quiz to this user

;timemodified
:int(10) unsigned NOT NULL default '0',
:Unix timestamp to be updated each time the grade is changed

===quiz_newest_states===

This table exists only for efficiency reasons:
#Via its 'newest' and 'newgraded' fields it gives attempt.php a way to quickly find the newest state and the newest graded state for an attempt. It allows the construction of SQL to select all the states that need to be loaded on attempt.php or review.php.
#Via its 'sumpenalty' field it gives quiz_apply_penalty() a quick way for getting at the accumulated penalty that needs to be applied. Without this field the penalties from all previous graded states would have to be added up each time. Not a big deal actually because this could be achieved with a single SQL query (using SUM) but this field was introduced when we still had the multiplicative penalty scheme around which would have been more difficult to recompute.

This table was introduced in Moodle 1.5 and is not populated for all states during the upgrade because on sites with a lot of existing states that could take too long. Rather it is done whenever needed by quiz_upgrade_states().

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;attemptid
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_attempts|quiz_attempts]] table. In Moodle 1.5 it referred to the id field of that table, since Moodle 1.6 it refers to the uniqueid field. This change was done while [[Separating questions from quizzes]].

;questionid
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_questions|quiz_questions]] table

;newest
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state for this attempt and this question.

;newgraded
:int(10) unsigned NOT NULL default '0',
Foreign key referring to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state created by a grading event.

;sumpenalty
:varchar(10) NOT NULL default '0.0',
This stores the total penalty that this user has accumulated over previous graded responses to this question in this attempt.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz database structure

2006-02-12T14:14:16Z

Gustav: /* quiz_states */ fixing some typos

{{Quiz developer docs}}The quiz data model has a fairly large pool of database tables, so the first step in explaining them is to provide some order. Conceptually it is possible to distinguish between the tables holding the teacher-supplied data, defining quizzes and questions, and the tables storing all the data that is generated when students interact with the quizzes and questions.

A further simplification is possible by separating out the questiontype specific tables. They are logical extensions to other tables and therefore are not necessary for understanding the general basic model. They are therefore explained on the developer documentation page for the individual [[Quiz developer docs#Question types|question types]].

The diagram below shows how the most important tables are linked to one another.

[[image:Quiz_database_tables.gif]]

==Teacher-supplied data==

===quiz===

The quiz table contains the definition for all the quizzes. Each quiz belongs to a course, reflected by the course id, has a name and a short descriptive text (intro), an opening and a closing time and several fields that store the settings of various quiz options, each of which is explained in the quiz help that is linked to from the quiz settings page.

The only field that requires additional information is the optionsflag, which... I will put an explanation here eventually --[[User:Gustav|Gustav]] 06:02, 5 February 2006 (WST)

For quizzes that contain random questions the $quiz object may acquire an additional property
;questionsinuse
:A comma separated list of questions that are being used in the quiz. This is used by the random questiontype to avoid choosing a question that is already being used.

===quiz_questions===

This table constitutes the item or question bank, i.e. the repository of defined questions. The quiz_questions table defines the data that is common to questions of all types.

;id
:int(10) NOT NULL auto_increment,
:Primary key. This is used as a foreign key in many other tables. for example the quiz_answers table allows to define an arbitrary number of answers that are part of the question. And many questiontypes have their own tables that hold more information about the question.

;category
:int(10) NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_categories|quiz_categories]]

;parent
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. This field is set to zero except in the case of wrapped questions as they are used for example in the multianswer questiontype. When a question wraps around any number of subquestions the subquestions will have their parent id field set to the id of the main question, thus allowing the question to find all its sub-questions (or wrapped questions). If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself. This is also used for hiding random questions from the question list. Their parent field is simply set to their own id.

;name
:varchar(255) NOT NULL default '',
:Question name that is used in question lists on the quiz editing pages

;questiontext
:text NOT NULL,
:Main text of the question

;questiontextformat
:tinyint(2) NOT NULL default '0',

;image
:varchar(255) NOT NULL default '',

;defaultgrade
:int(10) unsigned NOT NULL default '1',
:Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.

;penalty
:float NOT NULL default '0.1',
:The penalty that is applied (if the respective quiz option is set) for an incorrect attempt at the question.

;qtype
:smallint(6) NOT NULL default '0',
:The questiontype of the question. (Constants are defined in locallib.php)

;length
:int(10) unsigned NOT NULL default '1',
:This defines how many question numbers are required for this question. It is generally set to "1", but the description questiontype, for example, sets it to "0", reflecting the fact that it doesn't have a question number.

;stamp
:varchar(255) NOT NULL default '',
:Unique identifier

;version
:int(10) NOT NULL default '1',
:A number representing how often the question was edited.

;hidden
:int(1) unsigned NOT NULL default '0',
:Controls whether to display a question in the question bank list in edit.php. Hiding questions is a mechanism to "delete" questions without removing them from the database and thus to allow them to be restored or "unhidden" at a later stage. Also the (unfinished and disabled) [[Quiz_developer_docs#Question_versioning|versioning feature]] uses the hidden field to prevent older versions of a question from cluttering the user interface.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of the static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these later fields can differ when a question is used in different quizzes.

The runtime fields are added to question objects with the function <code>quiz_get_questions_options()</code> is called. This in turn calls the questiontype specific <code>get_question_options()</code> method for to add the options field.

;maxgrade
:This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in the [[#quiz_question_instances|quiz_question_instances table]].

;instance
:Foreign key: refers to an id in the table [[#quiz_question_instances|quiz_question_instances]]

;options
:Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the <code>get_question_options</code> method.

;name_prefix
:The prefix to be used on all interactions printed as part of the question.

We now deal in alphabetical order with the remaining tables for the teacher-provided data.

===quiz_answers===

This table allows a common way to store one or more teacher-defined answers for each question. It is not mandatory for a questiontype to make use of this table however. A questiontype may choose to store it's teacher-defined answers in an entirely different way, or even to do away with teacher-defined answers and use some other method to mark the student-supplied answer. For example it could calculate the correct answer on the fly.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to [[#quiz_questions|quiz_questions]] table.

;answer
:text NOT NULL,
:The string that represents the teacher-defined answer that will be compared to the student responses for grading and feedback purposes. The format of this field is entirely up to the question type.

;fraction
:varchar(10) NOT NULL default '0.0',
:The fraction of the total mark that the student should earn for giving this particular answer. This could be a negative number for wrong answers. Note that it is stored in a varchar(10) field.

;feedback
:text NOT NULL,
:Text that can be displayed to student as feedback when the student's responses match this particular answer.

In the past there was also a sequence number field was sometimes used to store the order of the different answers and was set to '0' if the order was of no importance.

===quiz_categories===

Categories are provided as a way to organize questions. Each category has a name and a descriptive text (info) and the sortorder as metadata. Categories allow hierarchical nesting via the parent id and can be private or published, i.e. they can be made available to teachers in other courses.

Since categories are simply a means for organising questions they are not vital for understanding how the quiz module works.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;course
:int(10) unsigned NOT NULL default '0',
:Foreign key to the course table

;name
varchar(255) NOT NULL default '',

;info
:text NOT NULL,

;publish
:tinyint(4) NOT NULL default '0',

;stamp
:varchar(255) NOT NULL default '',

;parent int(10)
:unsigned NOT NULL default '0',

;sortorder int(10)
:unsigned NOT NULL default '999',

===quiz_question_instances===

Questions can be assigned different grades in different quizzes. These are stored in this table.

While, after a small extension, this table could also fulfill the purpose of storing the order of the questions in a quiz, this is currently still done in the questions field in the [[#quiz|quiz]] table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz|quiz]] table.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz_questions|quiz_questions]] table.

;grade
:smallint(6) NOT NULL default '0',
:The maximum grade assigned to this question in this quiz. This grade was set by the teacher on the [[mod/quiz/edit|quiz editing page]]. At runtime this information is stored in the $question->maxgrade field.

===quiz_question_versions===

This feature is not finished and disabled. The table structure may still change. See [[Quiz developer docs#Question versioning]] for a discussion.

;id
:int(10) unsigned NOT NULL auto_increment,

;quiz
:int(10) unsigned NOT NULL default '0',

;oldquestion
:int(10) unsigned NOT NULL default '0',

;newquestion
:int(10) unsigned NOT NULL default '0',

;userid
:int(10) unsigned NOT NULL default '0',

;timestamp
:int(10) unsigned NOT NULL default '0',

==Student-created data==

===quiz_attempts===

In the quiz_attempts table a record is created each time a user starts an attempt at a quiz. This is one of the important tables and the corresponding $attempt object is passed between many of the quiz module functions and methods.

;id :int(10) unsigned NOT NULL auto_increment,
:Primary key
;uniqueid :int(10) unsigned NOT NULL default '0',
:Primary key since Moodle 1.6 used by [[Quiz database structure#quiz_states|quiz_states table]]. See [[Separating_questions_from_quizzes]] for details.
;quiz
:int(10) unsigned NOT NULL default '0',<br />The id of the quiz that is attempted
;userid
:int(10) unsigned NOT NULL default '0',<br />The id of the user who is attempting the quiz
;attempt
:smallint(6) NOT NULL default '0',<br>It is possible for a user to attempt a quiz several times, therefore the number of the attempt is stored in this field.
;sumgrades
:varchar(10) NOT NULL default '0.0',<br>The (unscaled) grade for the attempt, i.e. if the grades assigned to the questions add up to 8, but the maximum grade for the quiz is set to 10, then the sumgrades field can contain 8 at maximum.
;timestart
:int(10) unsigned NOT NULL default '0',<br>The timestart field is set to the current time when an attempt is started and is never changed afterwards.
;timefinish
:int(10) unsigned NOT NULL default '0',<br>The timefinish field is set to "0" initially and to the current time when the attempt is closed. This is exploited at several places in the code to determine whether an attempt has been closed or not (i.e. closed = timefinish > 0). For all other modifications of an attempt record the timemodified field should be changed as well.
;timemodified
:int(10) unsigned NOT NULL default '0',<br>This should be changed each time data in the record is modified.
;layout
:text NOT NULL,<br>a comma separated list of question ids, with a "0" denoting a page break. Usually the comma separated list ends with ",0".
;preview
:tinyint(3) unsigned NOT NULL default '0',<br>A flag that marks a teacher preview (i.e. an attempt by a user with teacher privileges) that may be automatically deleted when the quiz is previewed again, and which is not taken into account when viewing statistics.

===quiz_states===

States are saved for each interaction with a question. This allows a review of the complete history of a user's interactions with individual questions. The current state is the most important object used by the quiz module run-time code. This $state run-time object has a few additional fields not in the database that will be explained further down. The database fields are:

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;attempt
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_attempts|quiz_attempts]]. In Moodle 1.5 it referred to the id field of that table, since Moodle 1.6 it refers to the uniqueid field. This change was done while [[Separating questions from quizzes]].

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. The attempt id and the question id together sufficiently identify a question instance that a state belongs to.

;originalquestion
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table quiz_questions. It identifies which question was in use when the student attempted the question. This is part of the [[Quiz_developer_docs#Question_versioning|question versioning]] code.

;seq_number
:int(6) unsigned NOT NULL default '0',
:A counter that provides information about the sequence in which the states were created.

;answer
:text NOT NULL,
:This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses. Questiontypes are allowed to deviate from this and handle their response storage in any desired way. Some questiontypes do not use this field but instead store the student response in their own table extending this table.

;timestamp
:int(10) unsigned NOT NULL default '0',
:A time stamp to record when the state was created. This could mainly be useful for audit purposes.

;event
:int(4) unsigned NOT NULL default '0',
:Records the event or interaction type that lead from the previous state to the current one. The field can take the value of any of the following constants (defined in locallib.php):
:*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.

;grade
:varchar(10) NOT NULL default '0.0',
:Calculated from the raw grade by deducting the penalty and rescaling to the defaultgrade value of the question. Note that this is a varchar(10) field like most grade-related fields in the quiz module.

;raw_grade
:varchar(10) NOT NULL default '',
:The grade that was achieved for the question scaled to the question's weight or grade as assigned in the quiz_question_instances table

;penalty
:varchar(10) NOT NULL default '0.0',
:The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous marking events.

In addition to the database fields a few fields are added to the states at run time. They are dealt with by the questiontypes with the methods <code>create_session_and_responses</code>, <code>restore_session_and_responses</code> and <code>save_session_and_responses</code> and are defined as follows.

;sumpenalty
:The cumulative penalty, which can be calculated by adding up all the penalties from previous marking events. For efficiency these cumulative penalties are stored in the table [[#quiz_newest_states|quiz_newest_states]] so that they do not need to be re-calculated each time.

;changed
:This records whether a change has taken place to the run-time state. This is set to false when the state is restored from the database. Any code which changes the question state must set this field to true and must increment seq_number. The <code>quiz_save_question_session()</code> function will save the new state object to the database if the field is set to true.

;responses
:This is automatically set to the value of the database field <code>answer</code> before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indices are determined by the name of the elements after the name_prefix is stripped.

;last_graded
:This field contains another state object representing the most recent graded state in the history of this question attempt. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.

;options
:Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

We now deal in alphabetical order with the remaining tables holding the student-created data.

===quiz_grades===

The quiz_grades table merely stores a student's awarded grade for a quiz. Since it is possible to allow several attempts on a quiz, the grade stored is calculated depending on the quiz setting grademethod. This table exists mainly for convenience, because the values of its fields can be recalculated.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the [[#quiz|quiz]] table

;userid
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the user table

;grade
:double NOT NULL default '0',
:The grade awarded for this quiz to this user

;timemodified
:int(10) unsigned NOT NULL default '0',
:Unix timestamp to be updated each time the grade is changed

===quiz_newest_states===

This table exists only for efficiency reasons:
#Via its 'newest' and 'newgraded' fields it gives attempt.php a way to quickly find the newest state and the newest graded state for an attempt. It allows the construction of SQL to select all the states that need to be loaded on attempt.php or review.php.
#Via its 'sumpenalty' field it gives quiz_apply_penalty() a quick way for getting at the accumulated penalty that needs to be applied. Without this field the penalties from all previous graded states would have to be added up each time. Not a big deal actually because this could be achieved with a single SQL query (using SUM) but this field was introduced when we still had the multiplicative penalty scheme around which would have been more difficult to recompute.

This table was introduced in Moodle 1.5 and is not populated for all states during the upgrade because on sites with a lot of existing states that could take too long. Rather it is done whenever needed by quiz_upgrade_states().

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;attemptid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_attempts|quiz_attempts]] table

;questionid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_questions|quiz_questions]] table

;newest
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state for this attempt and this question.

;newgraded
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state created by a grading event.

;sumpenalty
:varchar(10) NOT NULL default '0.0',
This stores the total penalty that this user has accumulated over previous graded responses to this question in this attempt.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz database structure

2006-02-12T14:09:16Z

Gustav: /* quiz_states */ about uniqueid

{{Quiz developer docs}}The quiz data model has a fairly large pool of database tables, so the first step in explaining them is to provide some order. Conceptually it is possible to distinguish between the tables holding the teacher-supplied data, defining quizzes and questions, and the tables storing all the data that is generated when students interact with the quizzes and questions.

A further simplification is possible by separating out the questiontype specific tables. They are logical extensions to other tables and therefore are not necessary for understanding the general basic model. They are therefore explained on the developer documentation page for the individual [[Quiz developer docs#Question types|question types]].

The diagram below shows how the most important tables are linked to one another.

[[image:Quiz_database_tables.gif]]

==Teacher-supplied data==

===quiz===

The quiz table contains the definition for all the quizzes. Each quiz belongs to a course, reflected by the course id, has a name and a short descriptive text (intro), an opening and a closing time and several fields that store the settings of various quiz options, each of which is explained in the quiz help that is linked to from the quiz settings page.

The only field that requires additional information is the optionsflag, which... I will put an explanation here eventually --[[User:Gustav|Gustav]] 06:02, 5 February 2006 (WST)

For quizzes that contain random questions the $quiz object may acquire an additional property
;questionsinuse
:A comma separated list of questions that are being used in the quiz. This is used by the random questiontype to avoid choosing a question that is already being used.

===quiz_questions===

This table constitutes the item or question bank, i.e. the repository of defined questions. The quiz_questions table defines the data that is common to questions of all types.

;id
:int(10) NOT NULL auto_increment,
:Primary key. This is used as a foreign key in many other tables. for example the quiz_answers table allows to define an arbitrary number of answers that are part of the question. And many questiontypes have their own tables that hold more information about the question.

;category
:int(10) NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_categories|quiz_categories]]

;parent
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. This field is set to zero except in the case of wrapped questions as they are used for example in the multianswer questiontype. When a question wraps around any number of subquestions the subquestions will have their parent id field set to the id of the main question, thus allowing the question to find all its sub-questions (or wrapped questions). If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself. This is also used for hiding random questions from the question list. Their parent field is simply set to their own id.

;name
:varchar(255) NOT NULL default '',
:Question name that is used in question lists on the quiz editing pages

;questiontext
:text NOT NULL,
:Main text of the question

;questiontextformat
:tinyint(2) NOT NULL default '0',

;image
:varchar(255) NOT NULL default '',

;defaultgrade
:int(10) unsigned NOT NULL default '1',
:Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.

;penalty
:float NOT NULL default '0.1',
:The penalty that is applied (if the respective quiz option is set) for an incorrect attempt at the question.

;qtype
:smallint(6) NOT NULL default '0',
:The questiontype of the question. (Constants are defined in locallib.php)

;length
:int(10) unsigned NOT NULL default '1',
:This defines how many question numbers are required for this question. It is generally set to "1", but the description questiontype, for example, sets it to "0", reflecting the fact that it doesn't have a question number.

;stamp
:varchar(255) NOT NULL default '',
:Unique identifier

;version
:int(10) NOT NULL default '1',
:A number representing how often the question was edited.

;hidden
:int(1) unsigned NOT NULL default '0',
:Controls whether to display a question in the question bank list in edit.php. Hiding questions is a mechanism to "delete" questions without removing them from the database and thus to allow them to be restored or "unhidden" at a later stage. Also the (unfinished and disabled) [[Quiz_developer_docs#Question_versioning|versioning feature]] uses the hidden field to prevent older versions of a question from cluttering the user interface.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of the static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these later fields can differ when a question is used in different quizzes.

The runtime fields are added to question objects with the function <code>quiz_get_questions_options()</code> is called. This in turn calls the questiontype specific <code>get_question_options()</code> method for to add the options field.

;maxgrade
:This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in the [[#quiz_question_instances|quiz_question_instances table]].

;instance
:Foreign key: refers to an id in the table [[#quiz_question_instances|quiz_question_instances]]

;options
:Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the <code>get_question_options</code> method.

;name_prefix
:The prefix to be used on all interactions printed as part of the question.

We now deal in alphabetical order with the remaining tables for the teacher-provided data.

===quiz_answers===

This table allows a common way to store one or more teacher-defined answers for each question. It is not mandatory for a questiontype to make use of this table however. A questiontype may choose to store it's teacher-defined answers in an entirely different way, or even to do away with teacher-defined answers and use some other method to mark the student-supplied answer. For example it could calculate the correct answer on the fly.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to [[#quiz_questions|quiz_questions]] table.

;answer
:text NOT NULL,
:The string that represents the teacher-defined answer that will be compared to the student responses for grading and feedback purposes. The format of this field is entirely up to the question type.

;fraction
:varchar(10) NOT NULL default '0.0',
:The fraction of the total mark that the student should earn for giving this particular answer. This could be a negative number for wrong answers. Note that it is stored in a varchar(10) field.

;feedback
:text NOT NULL,
:Text that can be displayed to student as feedback when the student's responses match this particular answer.

In the past there was also a sequence number field was sometimes used to store the order of the different answers and was set to '0' if the order was of no importance.

===quiz_categories===

Categories are provided as a way to organize questions. Each category has a name and a descriptive text (info) and the sortorder as metadata. Categories allow hierarchical nesting via the parent id and can be private or published, i.e. they can be made available to teachers in other courses.

Since categories are simply a means for organising questions they are not vital for understanding how the quiz module works.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;course
:int(10) unsigned NOT NULL default '0',
:Foreign key to the course table

;name
varchar(255) NOT NULL default '',

;info
:text NOT NULL,

;publish
:tinyint(4) NOT NULL default '0',

;stamp
:varchar(255) NOT NULL default '',

;parent int(10)
:unsigned NOT NULL default '0',

;sortorder int(10)
:unsigned NOT NULL default '999',

===quiz_question_instances===

Questions can be assigned different grades in different quizzes. These are stored in this table.

While, after a small extension, this table could also fulfill the purpose of storing the order of the questions in a quiz, this is currently still done in the questions field in the [[#quiz|quiz]] table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz|quiz]] table.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz_questions|quiz_questions]] table.

;grade
:smallint(6) NOT NULL default '0',
:The maximum grade assigned to this question in this quiz. This grade was set by the teacher on the [[mod/quiz/edit|quiz editing page]]. At runtime this information is stored in the $question->maxgrade field.

===quiz_question_versions===

This feature is not finished and disabled. The table structure may still change. See [[Quiz developer docs#Question versioning]] for a discussion.

;id
:int(10) unsigned NOT NULL auto_increment,

;quiz
:int(10) unsigned NOT NULL default '0',

;oldquestion
:int(10) unsigned NOT NULL default '0',

;newquestion
:int(10) unsigned NOT NULL default '0',

;userid
:int(10) unsigned NOT NULL default '0',

;timestamp
:int(10) unsigned NOT NULL default '0',

==Student-created data==

===quiz_attempts===

In the quiz_attempts table a record is created each time a user starts an attempt at a quiz. This is one of the important tables and the corresponding $attempt object is passed between many of the quiz module functions and methods.

;id :int(10) unsigned NOT NULL auto_increment,
:Primary key
;uniqueid :int(10) unsigned NOT NULL default '0',
:Primary key since Moodle 1.6 used by [[Quiz database structure#quiz_states|quiz_states table]]. See [[Separating_questions_from_quizzes]] for details.
;quiz
:int(10) unsigned NOT NULL default '0',<br />The id of the quiz that is attempted
;userid
:int(10) unsigned NOT NULL default '0',<br />The id of the user who is attempting the quiz
;attempt
:smallint(6) NOT NULL default '0',<br>It is possible for a user to attempt a quiz several times, therefore the number of the attempt is stored in this field.
;sumgrades
:varchar(10) NOT NULL default '0.0',<br>The (unscaled) grade for the attempt, i.e. if the grades assigned to the questions add up to 8, but the maximum grade for the quiz is set to 10, then the sumgrades field can contain 8 at maximum.
;timestart
:int(10) unsigned NOT NULL default '0',<br>The timestart field is set to the current time when an attempt is started and is never changed afterwards.
;timefinish
:int(10) unsigned NOT NULL default '0',<br>The timefinish field is set to "0" initially and to the current time when the attempt is closed. This is exploited at several places in the code to determine whether an attempt has been closed or not (i.e. closed = timefinish > 0). For all other modifications of an attempt record the timemodified field should be changed as well.
;timemodified
:int(10) unsigned NOT NULL default '0',<br>This should be changed each time data in the record is modified.
;layout
:text NOT NULL,<br>a comma separated list of question ids, with a "0" denoting a page break. Usually the comma separated list ends with ",0".
;preview
:tinyint(3) unsigned NOT NULL default '0',<br>A flag that marks a teacher preview (i.e. an attempt by a user with teacher privileges) that may be automatically deleted when the quiz is previewed again, and which is not taken into account when viewing statistics.

===quiz_states===

States are saved for each interaction with a question. This allows a review of the complete history of a user's interactions with individual questions. The current state is the most important object used by the quiz module runtime code. This $state runtime object has a few additional fields not in the database that will be explained further down. The database fields are:

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;attempt
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_attempts|quiz_attempts]]. In Moodle 1.5 it referred to the id field of that table, since Moodle 1.6 it refers to the uniqueid field. This change was done while [[Separating questions from quizzes]].

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. The attempt id and the question id together sufficiently identify a question instance that a state belongs to.

;originalquestion
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table quiz_questions. It identifies which question was in use when the student attempted the question. This is part of the [[Quiz_developer_docs#Question_versioning|question versioning]] code.

;seq_number
:int(6) unsigned NOT NULL default '0',
:A counter that provides information about the sequence in which the states were created.

;answer
:text NOT NULL,
:This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses. Questiontypes are allowed to deviate from this and handle their response storage in any desired way. Some questiontypes do not use this field but instead store the student response in their own table extending this table.

;timestamp
:int(10) unsigned NOT NULL default '0',
:A timestamp to record when the state was created. This could mainly be useful for audit purposes.

;event
:int(4) unsigned NOT NULL default '0',
:Records the event or interaction type that lead from the previouse state to the current one. The field can take the value of any of the following constants (defined in locallib.php):
:*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.

;grade
:varchar(10) NOT NULL default '0.0',
:Calculated from the raw grade by deducting the penalty and rescaling to the defaultgrade value of the question. Note that this is a varchar(10) field like most grade-related fields in the quiz module.

;raw_grade
:varchar(10) NOT NULL default '',
:The grade that was achieved for the question scaled to the question's weight or grade as assigned in the quiz_question_instances table

;penalty
:varchar(10) NOT NULL default '0.0',
:The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous marking events.

In addition to the database fields a few fields are added to the states at runtime. They are dealt with by the questiontypes with the methods <code>create_session_and_responses</code>, <code>restore_session_and_responses</code> and <code>save_session_and_responses</code> and are defined as follows.

;sumpenalty
:The cumulative penalty, which can be calculated by adding up all the penalties from previous marking events. For efficiency these cumulative penalties are stored in the table [[#quiz_newest_states|quiz_newest_states]] so that they do not need to be re-calculated each time.

;changed
:This records whether a change has taken place to the runtime state. This is set to false when the state is restored from the database. Any code which changes the question state must set this field to true amd must increment seq_number. The <code>quiz_save_question_session()</code> function will save the new state object to the database if the field is set to true.

;responses
:This is automatically set to the value of the database field <code>answer</code> before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indicies are determined by the name of the elements after the name_prefix is stripped.

;last_graded
:This field contains another state object representing the most recent graded state in the history of this question attempt. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.

;options
:Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

We now deal in alphabetical order with the remaining tables holding the student-created data.

===quiz_grades===

The quiz_grades table merely stores a student's awarded grade for a quiz. Since it is possible to allow several attempts on a quiz, the grade stored is calculated depending on the quiz setting grademethod. This table exists mainly for convenience, because the values of its fields can be recalculated.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the [[#quiz|quiz]] table

;userid
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the user table

;grade
:double NOT NULL default '0',
:The grade awarded for this quiz to this user

;timemodified
:int(10) unsigned NOT NULL default '0',
:Unix timestamp to be updated each time the grade is changed

===quiz_newest_states===

This table exists only for efficiency reasons:
#Via its 'newest' and 'newgraded' fields it gives attempt.php a way to quickly find the newest state and the newest graded state for an attempt. It allows the construction of SQL to select all the states that need to be loaded on attempt.php or review.php.
#Via its 'sumpenalty' field it gives quiz_apply_penalty() a quick way for getting at the accumulated penalty that needs to be applied. Without this field the penalties from all previous graded states would have to be added up each time. Not a big deal actually because this could be achieved with a single SQL query (using SUM) but this field was introduced when we still had the multiplicative penalty scheme around which would have been more difficult to recompute.

This table was introduced in Moodle 1.5 and is not populated for all states during the upgrade because on sites with a lot of existing states that could take too long. Rather it is done whenever needed by quiz_upgrade_states().

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;attemptid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_attempts|quiz_attempts]] table

;questionid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_questions|quiz_questions]] table

;newest
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state for this attempt and this question.

;newgraded
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state created by a grading event.

;sumpenalty
:varchar(10) NOT NULL default '0.0',
This stores the total penalty that this user has accumulated over previous graded responses to this question in this attempt.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz database structure

2006-02-12T14:06:38Z

Gustav: /* quiz_attempts */ added uniqueid

{{Quiz developer docs}}The quiz data model has a fairly large pool of database tables, so the first step in explaining them is to provide some order. Conceptually it is possible to distinguish between the tables holding the teacher-supplied data, defining quizzes and questions, and the tables storing all the data that is generated when students interact with the quizzes and questions.

A further simplification is possible by separating out the questiontype specific tables. They are logical extensions to other tables and therefore are not necessary for understanding the general basic model. They are therefore explained on the developer documentation page for the individual [[Quiz developer docs#Question types|question types]].

The diagram below shows how the most important tables are linked to one another.

[[image:Quiz_database_tables.gif]]

==Teacher-supplied data==

===quiz===

The quiz table contains the definition for all the quizzes. Each quiz belongs to a course, reflected by the course id, has a name and a short descriptive text (intro), an opening and a closing time and several fields that store the settings of various quiz options, each of which is explained in the quiz help that is linked to from the quiz settings page.

The only field that requires additional information is the optionsflag, which... I will put an explanation here eventually --[[User:Gustav|Gustav]] 06:02, 5 February 2006 (WST)

For quizzes that contain random questions the $quiz object may acquire an additional property
;questionsinuse
:A comma separated list of questions that are being used in the quiz. This is used by the random questiontype to avoid choosing a question that is already being used.

===quiz_questions===

This table constitutes the item or question bank, i.e. the repository of defined questions. The quiz_questions table defines the data that is common to questions of all types.

;id
:int(10) NOT NULL auto_increment,
:Primary key. This is used as a foreign key in many other tables. for example the quiz_answers table allows to define an arbitrary number of answers that are part of the question. And many questiontypes have their own tables that hold more information about the question.

;category
:int(10) NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_categories|quiz_categories]]

;parent
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. This field is set to zero except in the case of wrapped questions as they are used for example in the multianswer questiontype. When a question wraps around any number of subquestions the subquestions will have their parent id field set to the id of the main question, thus allowing the question to find all its sub-questions (or wrapped questions). If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself. This is also used for hiding random questions from the question list. Their parent field is simply set to their own id.

;name
:varchar(255) NOT NULL default '',
:Question name that is used in question lists on the quiz editing pages

;questiontext
:text NOT NULL,
:Main text of the question

;questiontextformat
:tinyint(2) NOT NULL default '0',

;image
:varchar(255) NOT NULL default '',

;defaultgrade
:int(10) unsigned NOT NULL default '1',
:Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.

;penalty
:float NOT NULL default '0.1',
:The penalty that is applied (if the respective quiz option is set) for an incorrect attempt at the question.

;qtype
:smallint(6) NOT NULL default '0',
:The questiontype of the question. (Constants are defined in locallib.php)

;length
:int(10) unsigned NOT NULL default '1',
:This defines how many question numbers are required for this question. It is generally set to "1", but the description questiontype, for example, sets it to "0", reflecting the fact that it doesn't have a question number.

;stamp
:varchar(255) NOT NULL default '',
:Unique identifier

;version
:int(10) NOT NULL default '1',
:A number representing how often the question was edited.

;hidden
:int(1) unsigned NOT NULL default '0',
:Controls whether to display a question in the question bank list in edit.php. Hiding questions is a mechanism to "delete" questions without removing them from the database and thus to allow them to be restored or "unhidden" at a later stage. Also the (unfinished and disabled) [[Quiz_developer_docs#Question_versioning|versioning feature]] uses the hidden field to prevent older versions of a question from cluttering the user interface.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of the static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these later fields can differ when a question is used in different quizzes.

The runtime fields are added to question objects with the function <code>quiz_get_questions_options()</code> is called. This in turn calls the questiontype specific <code>get_question_options()</code> method for to add the options field.

;maxgrade
:This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in the [[#quiz_question_instances|quiz_question_instances table]].

;instance
:Foreign key: refers to an id in the table [[#quiz_question_instances|quiz_question_instances]]

;options
:Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the <code>get_question_options</code> method.

;name_prefix
:The prefix to be used on all interactions printed as part of the question.

We now deal in alphabetical order with the remaining tables for the teacher-provided data.

===quiz_answers===

This table allows a common way to store one or more teacher-defined answers for each question. It is not mandatory for a questiontype to make use of this table however. A questiontype may choose to store it's teacher-defined answers in an entirely different way, or even to do away with teacher-defined answers and use some other method to mark the student-supplied answer. For example it could calculate the correct answer on the fly.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to [[#quiz_questions|quiz_questions]] table.

;answer
:text NOT NULL,
:The string that represents the teacher-defined answer that will be compared to the student responses for grading and feedback purposes. The format of this field is entirely up to the question type.

;fraction
:varchar(10) NOT NULL default '0.0',
:The fraction of the total mark that the student should earn for giving this particular answer. This could be a negative number for wrong answers. Note that it is stored in a varchar(10) field.

;feedback
:text NOT NULL,
:Text that can be displayed to student as feedback when the student's responses match this particular answer.

In the past there was also a sequence number field was sometimes used to store the order of the different answers and was set to '0' if the order was of no importance.

===quiz_categories===

Categories are provided as a way to organize questions. Each category has a name and a descriptive text (info) and the sortorder as metadata. Categories allow hierarchical nesting via the parent id and can be private or published, i.e. they can be made available to teachers in other courses.

Since categories are simply a means for organising questions they are not vital for understanding how the quiz module works.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;course
:int(10) unsigned NOT NULL default '0',
:Foreign key to the course table

;name
varchar(255) NOT NULL default '',

;info
:text NOT NULL,

;publish
:tinyint(4) NOT NULL default '0',

;stamp
:varchar(255) NOT NULL default '',

;parent int(10)
:unsigned NOT NULL default '0',

;sortorder int(10)
:unsigned NOT NULL default '999',

===quiz_question_instances===

Questions can be assigned different grades in different quizzes. These are stored in this table.

While, after a small extension, this table could also fulfill the purpose of storing the order of the questions in a quiz, this is currently still done in the questions field in the [[#quiz|quiz]] table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz|quiz]] table.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz_questions|quiz_questions]] table.

;grade
:smallint(6) NOT NULL default '0',
:The maximum grade assigned to this question in this quiz. This grade was set by the teacher on the [[mod/quiz/edit|quiz editing page]]. At runtime this information is stored in the $question->maxgrade field.

===quiz_question_versions===

This feature is not finished and disabled. The table structure may still change. See [[Quiz developer docs#Question versioning]] for a discussion.

;id
:int(10) unsigned NOT NULL auto_increment,

;quiz
:int(10) unsigned NOT NULL default '0',

;oldquestion
:int(10) unsigned NOT NULL default '0',

;newquestion
:int(10) unsigned NOT NULL default '0',

;userid
:int(10) unsigned NOT NULL default '0',

;timestamp
:int(10) unsigned NOT NULL default '0',

==Student-created data==

===quiz_attempts===

In the quiz_attempts table a record is created each time a user starts an attempt at a quiz. This is one of the important tables and the corresponding $attempt object is passed between many of the quiz module functions and methods.

;id :int(10) unsigned NOT NULL auto_increment,
:Primary key
;uniqueid :int(10) unsigned NOT NULL default '0',
:Primary key since Moodle 1.6 used by [[Quiz database structure#quiz_states|quiz_states table]]. See [[Separating_questions_from_quizzes]] for details.
;quiz
:int(10) unsigned NOT NULL default '0',<br />The id of the quiz that is attempted
;userid
:int(10) unsigned NOT NULL default '0',<br />The id of the user who is attempting the quiz
;attempt
:smallint(6) NOT NULL default '0',<br>It is possible for a user to attempt a quiz several times, therefore the number of the attempt is stored in this field.
;sumgrades
:varchar(10) NOT NULL default '0.0',<br>The (unscaled) grade for the attempt, i.e. if the grades assigned to the questions add up to 8, but the maximum grade for the quiz is set to 10, then the sumgrades field can contain 8 at maximum.
;timestart
:int(10) unsigned NOT NULL default '0',<br>The timestart field is set to the current time when an attempt is started and is never changed afterwards.
;timefinish
:int(10) unsigned NOT NULL default '0',<br>The timefinish field is set to "0" initially and to the current time when the attempt is closed. This is exploited at several places in the code to determine whether an attempt has been closed or not (i.e. closed = timefinish > 0). For all other modifications of an attempt record the timemodified field should be changed as well.
;timemodified
:int(10) unsigned NOT NULL default '0',<br>This should be changed each time data in the record is modified.
;layout
:text NOT NULL,<br>a comma separated list of question ids, with a "0" denoting a page break. Usually the comma separated list ends with ",0".
;preview
:tinyint(3) unsigned NOT NULL default '0',<br>A flag that marks a teacher preview (i.e. an attempt by a user with teacher privileges) that may be automatically deleted when the quiz is previewed again, and which is not taken into account when viewing statistics.

===quiz_states===

States are saved for each interaction with a question. This allows a review of the complete history of a user's interactions with individual questions. The current state is the most important object used by the quiz module runtime code. This $state runtime object has a few additional fields not in the database that will be explained further down. The database fields are:

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;attempt
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_attempts|quiz_attempts]]

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. The attempt id and the question id together sufficiently identify a question instance that a state belongs to.

;originalquestion
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table quiz_questions. It identifies which question was in use when the student attempted the question. This is part of the [[Quiz_developer_docs#Question_versioning|question versioning]] code.

;seq_number
:int(6) unsigned NOT NULL default '0',
:A counter that provides information about the sequence in which the states were created.

;answer
:text NOT NULL,
:This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses. Questiontypes are allowed to deviate from this and handle their response storage in any desired way. Some questiontypes do not use this field but instead store the student response in their own table extending this table.

;timestamp
:int(10) unsigned NOT NULL default '0',
:A timestamp to record when the state was created. This could mainly be useful for audit purposes.

;event
:int(4) unsigned NOT NULL default '0',
:Records the event or interaction type that lead from the previouse state to the current one. The field can take the value of any of the following constants (defined in locallib.php):
:*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.

;grade
:varchar(10) NOT NULL default '0.0',
:Calculated from the raw grade by deducting the penalty and rescaling to the defaultgrade value of the question. Note that this is a varchar(10) field like most grade-related fields in the quiz module.

;raw_grade
:varchar(10) NOT NULL default '',
:The grade that was achieved for the question scaled to the question's weight or grade as assigned in the quiz_question_instances table

;penalty
:varchar(10) NOT NULL default '0.0',
:The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous marking events.

In addition to the database fields a few fields are added to the states at runtime. They are dealt with by the questiontypes with the methods <code>create_session_and_responses</code>, <code>restore_session_and_responses</code> and <code>save_session_and_responses</code> and are defined as follows.

;sumpenalty
:The cumulative penalty, which can be calculated by adding up all the penalties from previous marking events. For efficiency these cumulative penalties are stored in the table [[#quiz_newest_states|quiz_newest_states]] so that they do not need to be re-calculated each time.

;changed
:This records whether a change has taken place to the runtime state. This is set to false when the state is restored from the database. Any code which changes the question state must set this field to true amd must increment seq_number. The <code>quiz_save_question_session()</code> function will save the new state object to the database if the field is set to true.

;responses
:This is automatically set to the value of the database field <code>answer</code> before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indicies are determined by the name of the elements after the name_prefix is stripped.

;last_graded
:This field contains another state object representing the most recent graded state in the history of this question attempt. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.

;options
:Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

We now deal in alphabetical order with the remaining tables holding the student-created data.

===quiz_grades===

The quiz_grades table merely stores a student's awarded grade for a quiz. Since it is possible to allow several attempts on a quiz, the grade stored is calculated depending on the quiz setting grademethod. This table exists mainly for convenience, because the values of its fields can be recalculated.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the [[#quiz|quiz]] table

;userid
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the user table

;grade
:double NOT NULL default '0',
:The grade awarded for this quiz to this user

;timemodified
:int(10) unsigned NOT NULL default '0',
:Unix timestamp to be updated each time the grade is changed

===quiz_newest_states===

This table exists only for efficiency reasons:
#Via its 'newest' and 'newgraded' fields it gives attempt.php a way to quickly find the newest state and the newest graded state for an attempt. It allows the construction of SQL to select all the states that need to be loaded on attempt.php or review.php.
#Via its 'sumpenalty' field it gives quiz_apply_penalty() a quick way for getting at the accumulated penalty that needs to be applied. Without this field the penalties from all previous graded states would have to be added up each time. Not a big deal actually because this could be achieved with a single SQL query (using SUM) but this field was introduced when we still had the multiplicative penalty scheme around which would have been more difficult to recompute.

This table was introduced in Moodle 1.5 and is not populated for all states during the upgrade because on sites with a lot of existing states that could take too long. Rather it is done whenever needed by quiz_upgrade_states().

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;attemptid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_attempts|quiz_attempts]] table

;questionid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_questions|quiz_questions]] table

;newest
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state for this attempt and this question.

;newgraded
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state created by a grading event.

;sumpenalty
:varchar(10) NOT NULL default '0.0',
This stores the total penalty that this user has accumulated over previous graded responses to this question in this attempt.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz

2006-02-11T13:57:55Z

Gustav: /* Code documentation */ editlib.php

{{Quiz developer docs}}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. This page aims to collect useful documentation on how the module works.

==Terminology==

When talking about the quiz module there are certain terms that can cause confusion because they can be used with different meanings. In Moodle we have adopted a certain terminology that will be explained below.

===Questions===

A '''question''' in the context of the quiz module is the set of definitions (question name, question text, possible answers, grading rules, feedback, etc.) that constitute a reusable assessment item. So it is much more than what one would in everyday language understand under a question and which in Moodle is just on field (the questiontext field) of the question object.

What in Moodle we refer to as a 'question' is what in the terminology of the QTI specification ismore appropriately called an '''assessment item''' or just 'item' for short.

There are different types of questions, like for example multiple-choice questions or numerical questions. These are referred to as '''[[Quiz developer docs#Question types|question types]]''' in Moodle.

Since version 1.5 Moodle is able to handle so-called '''[[Adaptive questions]]''', also known as 'adaptive items' in QTI speak. These are qustions that walk the user through a directed graph of question states depending on the user's responses. For example 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. Quizzes can be run in 'adaptive mode', which provides buttons to mark each question individually.

===Answers===

In Moodle the term ''''answer'''' is used exclusively for the '''teacher-defined answers''' of a question. When talking about the quiz module it is easy to get confused between these teacher-defined answers and the answers that the students actually give. We have therefore adopted the convention to refer to the student-supplied answers as 'responses' and to reserve the term 'answers' to apply to teacher-defined answers. In question types that rely on teacher-supplied answers these are used in the grading process by comparing them with the student responses. Of course not all question types use teacher-defined answers but use some more intelligent way to process the student responses.

Perhaps one should also stress that 'answer' is not always used in the sense of 'correct answer'. For example every choice in a multiple-choice question is referred to as an answer. Other systems use the term 'distractor' for wrong answers.

In Moodle we always use the term ''''responses'''' to refer to the students' responses to a question because term 'answers' that one might also be tempted to use for this is already used to refer to the teacher-defined answers, see above. This term is always used in plural, although for some questiontypes there is only one possible response.

There is unfortunately, for historical reasons, one exception to the above rule: The [[Quiz database structure#quiz_states|quiz_states table]] has a field 'answer' whose purpose it actually is to hold the student's responses.

===Attempts===

In Moodle 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 ''''attempts at a question'''', never just as 'attempts'.

Because a student can have several attempts at a question within the same attempt at the quiz, there is a lot of data that needs to be stored as the student takes the question through several ''''states'''' by repeated interactions with the question. A state object holds the most recent state of the question and whenever a student submits a response or a similar ''''event'''' occurs, the question goes to a new state. The complete history of question states that the question is taken through is saved and this is referred to as the question ''''session''''. Usually only the most recent state and the last graded state are of interest though.

==Code documentation==

The code is documented according to phpdoc conventions. The explanations here in the wiki are meant to complement this.

Inline comments should be used liberally in the code. The following conventions make it easier to search for comments with special meaning:
* use TODO in comments about things that need to be done
* use ??? in comments that are questions about the code

There are three function libraries:

;questionlib.php
:All functions that need to be available to any module wanting to use questions. This is New in Moodle 1.6, in Moodle 1.5 this was part of locallib.php. This instantiates all questiontype classes by loading the questiontype.php files

;lib.php
:All the functions that are sometimes called by the Moodle core. This loads constants from '''constants.php'''

;editlib.php
:Functions that are used by the edit page edit.php. This loads locallib.php

;locallib.php
:All functions that are used only by the quiz module. This loads lib.php and questionlib.php

The default questiontype class is defined in '''questiontypes/questiontype.php''' (in Moodle 1.5 this was still in locallib.php). The individual questiontypes extend this class in their own questiontype.php file. For documentation of the questiontype classes one should often look at the documentation of the default question type because much of the documentation that is in the default class is not repeated in the other questiontype classes

Constants are defined in '''constants.php'''.

While questiontypes are realized as classes, the quiz module is not written in a truly object-oriented way. Instead it follows the Moodle model of using objects mostly only as alternatives to arrays to hold database records. So none of the quiz, question, attempt, and state objects that play a central role in the module have any methods. Only the questiontype objects have methods. Strangely enough the quiz module instantiates on object of each questiontype class at the start and then reuses their methods for the different questions. If one is used to the Moodle way of programming then this is easy enough to handle.

==Objects and data structures==

Key to understanding how the quiz module works is to understand the different kinds of object work together. The most important ones are:

*Quizzes
*Questions
*Attempts
*States

Quizzes and Questions are data created by the teacher when setting up and editing a quiz. Attempts and States are data created by the student when interacting with a quiz.

Moodle allows students to make several attempts at a quiz. Data about such an attempt is stored in an attempt object. This holds for example how the quiz was randomized for this attempt and the ordering of the questions and answers. So attempts are indexed by user id and quiz id.

Moodle allows students to interact repeatedly with a single question. So for example the student might initially just save an answer, later mark it, then correct it if it was marked incorrect. Each time the student interacts with a particular question inside a particular attempt at a quiz a new state is created. So states are indexed by user id, attempt id and question id.

===Database structure===
All this data needs to be kept in Moodle's database. How this is achieved is explained on a separate page about the '''[[Quiz database structure]]''', which also contains a useful diagram.

As is customary in Moodle, most runtime objects simply represent the data from a particular database record. So for example a $quiz object has fields corresponding to all the fields in the [[Quiz database structure#quiz|quiz table]]. In some cases the objects have some additional fields that are added at runtime. This is particularly the case for $question and $state objects. These additional fields are also described on the page about the '''[[Quiz database structure]]'''. Many functions that are used to process these objects make use of the additional fields and it is therefore necessary to use the correct functions for creating these objects.

===Runtime objects===
Some objects used by the quiz module are purely runtime object and do not correspond to a database table. The structure of these objects is explained in detail on a separate page about the '''[[Quiz runtime objects]]'''.

The main script of the quiz module is attempt.php which will have to deal with all these objects. Studying the '''[[Quiz attempt|explanation of attempt.php]]''' is therefore a good way to start to study the quiz module code.

==Response storage==

The student's responses to a question are stored in <code>$state->responses</code>. Questiontypes are completely free to implement the storage mechanism of their responses (and other state information) the way they want. Still, the standard questiontypes all follow a similar model. The default storage model and the questiontype specific variations are explained below.

The flexibility for the questiontypes to choose their response storage mechanism freely and to convert from the storage model to the runtime model is provided by a set of three functions, which allow to initialise the runtime <code>$state->responses</code> field, to convert from the runtime to the storage model and vice versa:

;<code>create_session_and_responses()</code>
:Initializes the $state object, in particular the <code>$state->responses</code> field

;<code>restore_session_and_responses()</code>
:Loads the question type specific session data from the database into the <code>$state</code> object, in particular it loads the responses that have been saved for the given <code>$state</code> into the <code>$state->responses</code> field.

;<code>save_session_and_responses()</code>
:Saves the question type specific session data from the $state object to the database. In particular, for most questiontypes, it saves the responses from the <code>$state->responses</code> to the database.

The generic quiz module code saves the contents form the <code><nowiki>$state->responses['']</nowiki></code> field to the answer field in the [[Quiz database structure#quiz_states|quiz_states table]] and also automatically restores the contents of this field to <code><nowiki>$state->responses['']</nowiki></code>. This means that any questiontype, which only expects a single value as its response can skip the implementation of the three methods described above. All questiontypes that have multiple value responses need to implement these methods.

The default questiontypes handle this problem by serializing/de-serializing the responses to/from the answer field in the quiz_states table. However, it is also possible (and may be better practice) to extend the quiz_states table with a questiontype specific table, i.e. take the id of the quiz_states record as a foreign key in the questiontype specific table. Because the value of <code><nowiki>$state->responses['']</nowiki></code> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <code>save_session_and_responses()</code>) whatever value the generic code set this field to with their serialized value (usually achieved with a simple set_field).

In the method <code>restore_session_and_responses()</code> the serialized value can be read from <code><nowiki>$state->responses['']</nowiki></code> because this is where the value from answer field of the quiz_states table has been moved. Care needs to be taken that this array value is then unset or the whole array overwritten, so that the array does not accidentally contain a value with the empty string index.

==Response processing==

The runtime model for responses dictates the structure of the $state->responses array. Starting with the names of the form elements this section goes through the relevant processing steps and thus attempts to clarify why the keys of the $state->responses array can differ for different questiontypes; even more, it explains how the array keys are chosen and set.

Although it may initially seem strange to start with the naming convention of the form fields, the reason for this will become clear later on. The controls (i.e. the form fields) of a question get printed by the method <code>print_question_formulation_and_controls()</code>. The convention only dictates that the name of the control element(s) must begin with the value of <code>$question->name_prefix</code>. The <code>$question->name_prefix</code> is a string starting with "resp" followed by the question id and an underscore, e.g. <code>resp56_</code>. In the default case, when there is only a single control element (this includes the case of a list of equally named radio buttons), no postfix is appended to the name prefix. For questiontypes that allow or require multiple form elements, an arbitrary string can be appended to the name prefix to form the name of these form elements. The postfix must not include any relational data (i.e. ids of records in the quiz_answers table), because this can lead to problems with regrading of versioned questions.

After the printing of the question the server only sees it again when it is submitted. So the submitted data will contain several values indexed by strings starting with <code>respXX_</code>. Upon submission, the function <code>quiz_process_responses()</code> is called, which assigns the submitted responses to the state of the question with id XX, using the postfix (i.e. everything after the underscore) as array keys. In the default case with only one control element the name only consists of the name prefix. This explains why the default index of the <code>$state->responses</code> array is the empty string. The value of each array element is obviously the value that was submitted by the form, basically a raw response.

The function <code>quiz_process_responses()</code> in turn calls the questiontype specific method <code>grade_responses()</code> to assign a grade to the submitted responses and <code>compare_responses()</code> to determine whether the response was identical to the previous submission and to avoid regrading the same responses repeatedly. These questiontype specific functions need to be aware of the expected keys of the <code>$state->responses</code> array.

Finally, the methods <code>restore_session_and_responses()</code> and <code>save_session_and_responses()</code> also need to know the questiontype specific layout of the <code>$state->responses array</code> and restore or save the information, e.g. by converting from or to the data representation.

==Question types==
{{Questiontype developer docs}}
The quiz module is itself modular and allows question type plug-ins. For each question type there should be a page, accessible via the menu at the right, which provides at least the dtails about
*Database tables
*Response storage
*Question options object
*State options object

It is hoped that Moodlers will contribute a lot of non-core question types in the future. For this it would be good to start a [[Guide to question type plugins]].

==Grades==

The handling of grades is a bit complicated because there are so many different grades around that get rescaled and combined in various ways. This section should summarize how this is done and why.

The following grade fields are being used:
*$question->defaultgrade
::This is the default value for the maximum grade for this question. This is set up when the teacher creates the question and it is stored in an int(10) field in the [[Quiz database structure#quiz_questions|quiz_questions]] table. However when the question is actually used in a particular quiz the teacher can overrule this default and this is stored in:
*$question->maxgrade
::This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in an int(10) field in the [[Quiz database structure#quiz_question_instances|quiz_question_instances table]].
*$question->penalty

*$state->raw_grade
*$state->grade
*$state->penalty
*$state->sumpenalty

*$attempt->sumgrades

The maximum grades set by the teacher, $question->defaultgrade and $question->maxgrade, are integers. All student-obtained grades are in principle floating point numbers. For historical reasons they are stored in the database as varchar(10) fields. Care has to be taken when writing to the database to make sure all grades are correctly rounded and squeezed into a string of no more than 10 characters, otherwise the writing to database will fail, see bug 4220.

The final outcome of the calculation of the grade for a user at a particular quiz is stored in the 'grade' field of the [[Quiz database structure#quiz_grades|quiz_grades table]]. This field has type double.

==Penalty mechanism==

===What it is for===

When the quiz is run in adaptive mode the student can interact with a question repeatedly. So in particular the student can try again when he gets a wrong answer. Clearly the final mark for the question must reflect the fact that the student did not get it right originally. Therefore a penalty is subtracted from the final mark.

===How the penalty is determined===

First of all penalties are relevant only if a quiz is run in adaptive mode. Only in this case can a student have a second attempt and therefore only in this mode can there be any occasion to subtract a penalty.

Even in adaptive mode the penalty mechanism is only used when it is selected in the quiz options. If "Apply penalties" is set to "No" then the final mark for the question is the mark for the last graded response.

Each question has a 'penalty' field (which should really be called 'penaltyfactor') which is a number between 0 and 1. The penalty for a wrong response is calculated as the product ($quiz->penalty * $quiz->grade), i.e., as the product of the penaltyfactor with the maximum achievable grade for the question. This product is stored in $state->penalty. So $quiz->penalty is the fraction of the maximum grade that is subtracted as a penalty for each wrong response.

The $quiz->penalty field has a default value of 0.1, both in the database and in mod/quiz/defaults.php. This default can of course be overwritten by the admin on the quiz configuration page. This admin-selected default is (as usual for admin defaults) stored in $CFG->quiz_penalty. The teacher can choose a different penalty factor for each individual question when adding or editing a question.

Now if a student makes repeated wrong attempts (or partially correct attempts) the penalties for all these attempts are added up in $state->sumpenalties. The mark for the question is then calculated as the mark for the last graded response minus the sum of the penalties.

One curious fact about $state->sumpenalties is that, for efficiency reasons, it is not stored in the quiz_states table but instead in the 'sumpenalty' field of the quiz_newest_states table. That way it only has to be stored once per attempt rather than once per response.

===Where it is done in the code===

The function quiz_apply_penalty_and_timelimit() subtracts the penalty in $state->sumpenalty from the raw grade in $state->raw_grade to obtain $state->grade for the response. However it is ensured that the grade of a new attempt at the question never falls below the previously achieved grade. This function also increases $state->sumpenalty by the amount in $state->penalty. The assumption is that $state->penalty has just been set appropriately by the code calling this function, e.g., quiz_process_responses.

==Time limit==

A quiz can have a time limit. This is stored in minutes in $quiz->timelimit. So before using this in time calculations it always has to be multiplied by 60 to turn it into seconds like all other timestamps in moodle and php. If $quiz->timelimit is zero it means there is no timelimit.

If a student asks to start an attempt on view.php for a quiz with a timelimit then he is shown a javascript message alerting him to the timelimit and is asked to confirm.

For quizzes with timelimit attempt.php shows a javascript timer that counts down and automatically submits and closes the attempt when the time is up.

Confusingly there are two javascript timers in the quiz module. jsclock.php provides a countdown in the title bar that counts down to the quiz closing time if this is less than a day away. This has nothing to do with the timelimit. jstimer.php provides the countdown timer that implements the timelimit. It in turn uses timer.js.

The time a response was submitted by the student is recorded by attempt.php right at the top of the page and is then passed on to quiz_process_responses in $action->timestamp. This puts it into $state->timestamp. Finally, after the responses have been graded, the function quiz_apply_penalty_and_timelimit() checks that the responses are within the timelimit to within 5% and if not it sets the grade to zero (or the previously obtained grade, if that is higher).

==Pagination==

Quiz attempts can be paginated, i.e., spread over several pages. The student can navigate between the pages using the standard Moodle paging bar. When the student navigates to a different quiz page the answers on the current page are automatically submitted for saving (but not grading).

To do this automatic submission the paging bar needs some javascript. It is therefore not produced with Moodle's standard print_paging_bar() function from weblib.php but with quiz_print_navigation_panel() which is defined in mod/quiz/locallib.php and produces something that looks the same.

The teacher has complete control via the edit interface on edit.php over where the page breaks should occur. He can repaginate the quiz with any chosen number of questions per page. He can also move the page-breaks up and down using the arrows.

Internally page breaks are stored in the $quiz->questions field (which now should really be called $quiz->layout). This field contains a comma separated list of questionids and pagebreaks where the pagebreaks are represented by the id 0. For example 23,12,0,11, 0 means that the two questions with ids 23 and 12 are on the first page and the question with id 11 is on the second page. The last page break is invisible and Moodle sometimes puts it there itself for its own convenience.

Because the quiz has an option $quiz->shufflequestions to shuffle questions the layout that the student sees in a particular attempt does not necessarily have to be the same as that stored in $quiz->questions. Therefore each attempt has its own $attemp->layout field. If $quiz->shufflequestions is false then this just contains a copy of $quiz->questions but if it is true then during the creation of a new attempt by quiz_create_attempt() the function quiz_repaginate() is used to produce a layout with $quiz->questionsperpage number of questions per page that are randomly ordered.

Both attempt.php and review.php use the $attempt->layout field to determine what questions to show on a particular page. That way we can guarantee that the student will, for a particular attempt, always see the questions in the same order and with the same pagination, both while attempting and during review. Also a teacher when reviewing a student's attempt sees the pages the same way they were shown to the student. However the teacher is also given the option to see all questions on one page.

There are some functions in locallib.php dedicated to handling the layout fields: quiz_questions_on_page(), quiz_questions_in_quiz(), quiz_number_of_pages(), quiz_first_questionnumber(), quiz_repaginate(). They are very short functions. The function quiz_first_questionnumber() that determines the number of the first question on a particular page makes use of the $question->length field. To allow this calculation to be fast is the main reason why that field is in the question table even though it could also be determined easily from the question type.

==Question versioning==

'''Note:''' Question versioning is currently disabled until it is re-developed to fix all reported issues.

When questions that were already attempted by a student are edited, it can be important to keep a copy of the question as it was before editing in order to reconstruct the quiz as it was seen by the student. To provide this functionality a question versioning mechanism was implemented.

The first goal, namely keeping around old questions, is easily achieved. They are just not deleted any more. However, this is not enough; it is also necessary to store which questions are versions of others. To achieve this goal, there is an additional table, which stores the versioning information: quiz_question_versions.

When a question is replaced for which there are already student attempts then all the attempt data gets associated to the new version of the question and is re-graded. This requires the question ids in the quiz_attempts, quiz_states and quiz_newest_states tables to be replaced by the new id. However we do also want to be able to reconstruct the quiz the way the student saw it when he gave his answers. For that purpose the id of the original question is always preserved in the 'originalquestion' field of the quiz_states table.

If all old versions of questions are kept around this could horribly clutter the editing interface. Therefore a field called hidden was added to the quiz_questions table and all old versions of edited questions are automatically hidden. When this flag is set to 1 the question is not displayed in the list of available questions, unless the user chooses to show them.

While the mechanism above should work as described, there is some additional complexity in order to minimise the number of versions created. If a question is created and has not been attempted by a student yet (this excludes teacher previews of the individual question and the quiz!), the database record will be reused (i.e. overwritten) and no new version will be created. This is especially important when the question is created and the first 2 or 3 mistakes are only noticed during preview.

On the editing screen for questions an additional set of options was introduced (see image).
Replacement Options
It shows which quizzes use the edited question and how many students have attempted it in a particular quiz. Based on this information it is then possible to choose in which quizzes the new version of the question should be used and in which ones the old one should remain.

By default the 'replace' checkbox for all quizzes that don't have any students' attempts are checked and in addition, if the question is edited out of a quiz context (i.e. not in the category question list), the 'replace' option is checked for that quiz as well.

===Database===

The changes to the database structure are limited to an added field (hidden) in the quiz_questions table and an additional table called quiz_question_versions. However, dealing with the quiz_questions table has become slightly more complicated.

The hidden field in the quiz_questions table has no implications for the core functionality. It is only used to determine, as the name implies, whether the question is shown in the category list or not.

The table quiz_question_versions stores information about the actual change. This information includes the ids of the old question and the new question, the id of the user who did the change and a timestamp. Quite importantly, the id of the quiz, in which the question was replaced is also stored. This means that the versions table provides a history of the different states the quiz went through until it was edited to be at the current state. The information allows to recreate a quiz as it was at any point in time (from a data perspective - this possibility is not used extensively by the code).

===Adjustments to the Data===

When a question is replaced by a newer version, database records are updated in the order shown below (compare with question.php):

* First a new record is inserted into the quiz_question_versions table for each affected quiz (i.e. each quiz in which the question was replaced).
* Then, for each affected quiz, the comma separated list of question ids in the question field is updated by replacing the old question id with the new one.
* In the quiz_question_instances table the record that links the old question to the quiz is also updated to point to the new question.
* In all attempts belonging to the old question the comma-separated list of question ids in the layout field are changed by replacing the old id by the new one.
* All states belonging to the old question are made to belong to the new version by changing the id in the 'question' field. However if we are replacing the original question then the id of this original version is stored in the originalquestion field.
* We have to change the questionid field in quiz_newest_states.
* Finally we have to do any question-type specific changes. For example question types that store student responses by storing the id of the answer in the quiz_answers table will have to recode these ids in all the states to point to the corresponding answers in the new version. This is handled by the function replace_question_in_attempts() in the question type class.

===Affected Code and Functionality===

Note: This section should still be considered under construction until the question mark behind bug #3311 is taken off.

In the file review.php and potentially also in the file attempt.php, if a question is edited during a student's attempt, the data from quiz_question_versions needs to be taken into account. If a student has attempted a quiz and a question was changed afterwards (i.e. a new version of that question was created), the question id of the old version remains in the comma separated list inside the attempt->layout field. However, since the records in the quiz_question_instances table get updated, we need to go forward in the question history, by looping through entries from the quiz_question_versions table, to find out the id of the question version that is currently used in the quiz.

Suggestion: With a fairly simple change to the convention of what is stored in the quiz_question_versions table we could get rid of the requirement of looping through all the versions. If in the newquestion field we store the id of the question that is currently used in the quiz, it would be possible to get the complete history for a question quite simply by selecting by quiz id and newquestion.

It should be fairly simple to write an upgrade script for this change. Additionally, another set_field would need to be added to question.php to change the newquestion field to the new question id. The benefits would be a much simpler handling of the question history, resulting in more efficient code than the current fix for bug #3311 in review.php.

The place where all the versioning actually takes place is question.php. Here the changes described in Adjustments to the Data are carried out.

Obviously the backup and restore scripts also take quiz_question_versions into account, however, they don't need to be concerned with the ways the data is used.

==Changes for Moodle 1.5: adaptive questions==

During the first half of 2005 the quiz module code has undergone a considerable rewrite to allow for adaptive questions in which a question session can consist of several sequential student responses. The question can adapt itself to the student answers. For example in response to certain answers the question could provide feedback or hints and then ask the student to answer again or give the student a simpler or related question.

Unfortunately many changes had to be made to the question type methods. This has however resulted in improved efficiency and has made the writing of question types easier. It also allows question types with more powerful features and has fixed some bugs / annoying behaviour.

For details see:
*[[Quiz rewrite|Quiz module rewrite]]
*[[Quiz conversion|How to convert existing question types]]

Of course there were countless other changes to the quiz module going from Moodle 1.4 to 1.5, especially to the teacher interface. However in spite of the fact that these changes are a lot more visible they were much less drastic from the point of view of the code. Here is a very incomplete list of changes:

* New quiz results overview page
* Reform of the quiz edit page: Changes on the quiz edit page are saved straightaway, not only after Save button is pressed.
* Copying questions: The teacher can create a new question using a previous one as template.
* Moving questions: The teacher can now move selected questions to a different category.
* Re-marking after question editing: if a teacher corrects a question that students have already attempted the teacher can request a remark.
* Teacher preview tab.
* Detailed teacher control over what students can see during review.

==Changes for Moodle 1.6: separating questions from quizzes==

The quiz module is not the only activity module in Moodle that uses questions. The lesson does too and potentially questions could be useful in many modules. Therefore we have started to rewrite some of the quiz module functions and move them from locallib.php to questionlib.php so that eventually they could be moved into a central library and be used by other modules.

Module developers who want to use the
quiz module questions in their own module should take a look at the simple questiondemo module that you can find in CVS at [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/questiondemo contrib/questiondemo]. The idea is that it will be simpler
to understand this demonstration module than the code in the quiz module which
is very complicated due to the many options and features. The interesting code in the questiondemo module is in view.php. There you can see how to
both render and score questions. This module requires the version of the quiz module from Moodle 1.6dev or later.

The details of the changes are explained on the page [[Separating questions from quizzes]].

==Future plans==

The features below are in no particular order:

* Editing questions: This is about editing questions after students have already attempted them. There needs to be a mechanism to keep the old versions of the question around for auditing purposes.
* New quiz statistics pages?: These pages should be built by using functions defined by the individual question types.
* Manual grade override: Teachers should be able to override the automatically calculated grades and should be able to make comments.
* Off-line questions: The answers to these are handed in off-line in the conventional way (e.g., on paper) and teachers enter marks on Moodle.
* Batch printing of quiz sheets: We want to be able to hand out question sheets to students so they can start working on the questions before going to the computer.
* Question preview from question edit page: so the teacher can try the question already before saving the changes.
* Show table of questions on view.php: gives teachers and students a bit of an overview of the quiz.
* Extending deadlines for individual students: for example when a student misses a deadline for good reasons.
* Filtering questions by quiz and by search: More ways to restrict which questions are shown on the quiz editing page.
* Re-open quizzes for revision: After the due date has passed the quiz could allow practice attempts.

[[Category:Developer]]
[[Category:Quiz]]

Help:Editing

2006-02-11T13:48:29Z

Gustav: /* External links */ HTML to MediaWiki converter

== Editing ==

Every wiki page has an "edit" tab at the top plus edit links at the side. These links lets you do exactly what they say i.e. edit the page you're looking at. Please try it in the [[sandbox]]!

=== Show preview ===
This lets you see what the page will look like after your edit, before you actually save. We all make mistakes; this feature lets you catch them immediately. Using Show preview before saving also lets you try format changes and other edits without cluttering up the page history, and has a number of other advantages. Don't forget to save your edits after previewing, though!

=== Edit summary ===
Before saving the page, it's considered good practice to enter a very brief summary of your changes in the summary box below the edit-box.

== Formatting ==

Most '''formatting''' is usually done with Wiki markup - you don't have to learn HTML!

=== Bold and italics ===
'''Bolding''' and ''italicizing'' is done by surrounding a word or phrase with multiple apostrophes (<tt>'</tt>):

:<code><nowiki>''italics''</nowiki></code> appears as ''italics''. (2 apostrophes on both sides)
:<code><nowiki>'''bold'''</nowiki></code> appears as '''bold'''. (3 apostrophes on both sides)
:<code><nowiki>'''''bolded italics'''''</nowiki></code> appears as '''''bolded italics'''''. (5 apostrophes on both sides)

=== Headings and subheadings ===
Headings and subheadings are an easy way to improve the organization of an article.

Headings can be created like this:
:<code><nowiki>==Top level heading==</nowiki></code> (2 equals signs)
:<code><nowiki>===Subheading===</nowiki></code> (3 equals signs)
:<code><nowiki>====Another level down====</nowiki></code> (4 equals signs)

If an article has at least four headings, a table of contents will automatically be generated.

=== Indentations ===
The simplest way of indenting is to place a colon (<code>:</code>) at the beginning of a line. The more colons you put, the further indented the text will be. A newline marks the end of the indented paragraph e.g.
:<code>This is aligned all the way to the left.</code>
:<code><nowiki>:</nowiki>This is indented slightly.</code>
:<code><nowiki>::</nowiki>This is indented more.</code>
is shown as
:This is aligned all the way to the left.
::This is indented slightly.
:::This is indented more.

=== Lists ===
{| border="1" cellpadding="2" cellspacing="0"
|-
!What it looks like
!What you type
|-
|
* ''Unordered lists'' are easy to do:
** start every line with a star
*** more stars means deeper levels
*A newline
*in a list
marks the end of the list.

|<pre><nowiki>* Unordered Lists are easy to do:
** start every line with a star
*** more stars means deeper levels
*A newline
*in a list
marks the end of the list.
</nowiki></pre>
|-
|
# Numbered lists are also good
## very organized
## easy to follow
#A newline
#in a list
marks the end of the list.
|<pre><nowiki># Numbered lists are also good
## very organized
## easy to follow
#A newline
#in a list
marks the end of the list.
</nowiki></pre>
|}

=== Preserving formatting ===

{| border="1" cellpadding="2" cellspacing="0"
|-
!What it looks like
!What you type
|-
|
Leading spaces are another way to preserve formatting.

Putting a space at the beginning of each line
stops the text from being reformatted.
|<pre><nowiki>
Leading spaces are another way to preserve formatting.

Putting a space at the beginning of each line
stops the text from being reformatted.
</nowiki></pre>
|}

== Links ==

=== Wiki links ===
To make a wiki link, simply put the word in double square brackets, like this: <code><nowiki>[[Sandbox]]</nowiki></code>

If you want to use words other than the article title as the text of the link, you can do so by adding the pipe "|" divider (SHIFT + BACKSLASH on English-layout and other keyboards) followed by the alternative name.

For example, if you wanted to make a link to the [[sandbox]], but wanted it to say "my text" you would write it as: <code><nowiki>[[sandbox|my text]]</nowiki>...</code> It would appear as: [[sandbox|my text]]... but would link to the sandbox.

=== External links ===

The easiest way to make an external link is to simply type in the full URL for the page you want to link to e.g. http://www.google.com.

To make the link display something other than the URL, use one square bracket at each end. If you want to make a link to Google, type <code><nowiki>[http://www.google.com/]</nowiki></code>
This will display the link as a number in brackets, like this: [http://www.google.com/].

If you want the link to appear with text that you specify, add an alternative title after the address separated by a '''space''' (''not'' a pipe). So if you want the link to appear as [http://www.google.com Google search engine], just type <code><nowiki>[http://www.google.com Google search engine]</nowiki></code>.

===Categories===

To put a page in a category, just type <code><nowiki>[[Category:]]</nowiki></code>, and put the name of the category between the colon and the brackets.

==External links==
*[http://meta.wikimedia.org/wiki/Help:Editing MediaWiki Help:Editing]
*[http://meta.wikimedia.org/wiki/Help:Image MediaWiki Help:Images and other uploaded files]
*[http://meta.wikimedia.org/wiki/Help:HTML_in_wikitext Help:HTML in wikitext]
*[http://diberri.dyndns.org/html2wiki.html HTML to MediaWiki converter]
*[http://wikipedia.mozdev.org/ Firefox Wikipedia extension] - The Wikipedia extension makes editing of wiki pages easier by adding a new toolbar to your browser and by providing new menu items in the context menu (right mouse key).

[[Category:MoodleDocs]]

Development:Blocks

2006-02-11T13:34:27Z

Gustav: I sent Jon's page through a html to mediawiki converter

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@uom.gr)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Blocks_Howto#appendix_b| Appendix B]]).
The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though. Experienced developers and those who just want a reference text should refer to [[Blocks_Howto#appendix_a| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==
Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required. Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.
Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==
To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory <span class="filename">/blocks/simplehtml/</span> and creating a file named <span class="filename">/blocks/simplehtml/block_simplehtml.php</span> which will hold our code. We then begin coding the block:
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
}
The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.
Our class is then given a small method: [[Blocks_Howto#method_init| init]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.
[[Blocks_Howto#variable_title| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks_Howto#section_eye_candy| how to disable the title's display]].
[[Blocks_Howto#variable_version| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data. In our example,
this is certainly the case so we just set [[Blocks_Howto#variable_version| $this->version]] to '''YYYYMMDD00''' and forget about it.
'''UPDATING:''' Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.
== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
It can't get any simpler than that, can it? Let's dissect this method to see what's going on...
First of all, there is a check that returns the current value of [[Blocks_Howto#variable_content| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.
At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it and after seeing it in action come back to continue our tutorial.
== Configure That Out ==
The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:
function instance_allow_config() {
return true;
}
This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: <span class="filename">/blocks/simplehtml/config_instance.html</span> (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>
<?php use_html_editor(); ?>
It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our <span class="filename">config_instance.html</span> file as instance configuration data. We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.
You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Blocks_Howto#method_init| init]].
In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Blocks_Howto#appendix_a| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Blocks_Howto#variable_config| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in is configuration data. To do that, find this snippet in <span class="filename">/blocks/simplehtml/block_simplehtml.php</span><nowiki>:</nowiki>

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
and change it to:

$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:
<nowiki>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';</nowiki>
After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.
== The Specialists ==
Implementing instance configuration for the block's contents was good enough to whet our apetite, but who wants to stop there? Why not customize the block's title, too?
Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to <span class="filename">/blocks/simplehtml/config_instance.html</span>. Here goes:

<tr valign="top">
<td align="right"><p><?php print_string('configtitle', 'block_simplehtml'); ?>:</td>
<td><input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" /></td>
</tr>
We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.
That's not too wierd, if we think back a bit. Do you remember that [[Blocks_Howto#method_init| init]] method, where we set [[Blocks_Howto#variable_title| $this->title]]? We didn't actually change its value from then, and [[Blocks_Howto#variable_title| $this->title]] is definitely not the same as $this->config->title (to Moodle, at least). What we need is a way to update [[Blocks_Howto#variable_title| $this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks_Howto#variable_config| $this->config]] in all methods ''except'' [[Blocks_Howto#method_init| init]]<nowiki>! So what can we do?</nowiki>
Let's pull out another ace from our sleeve, and add this small method to our block class:

function specialization() {
$this->title = $this->config->title;
}
Aha, here's what we wanted to do all along! But what's going on with the [[Blocks_Howto#method_specialization| specialization]] method?
This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks_Howto#method_init| init]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks_Howto#method_specialization| specialization]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.
== Now You See Me, Now You Don't ==
Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists. However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.
This is indeed possible, and the way to do it is to make sure that after the [[Blocks_Howto#method_get_content| get_content]]<nowiki> method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (''). Moodle performs this check by calling the block's </nowiki>[[Blocks_Howto#method_is_empty| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.
Note that the exact value of the block's title and the presence or absence of a [[Blocks_Howto#method_hide_header| hide_header]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.
== We Are Legion ==
Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

function instance_allow_multiple() {
return true;
}
This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!
There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.
And finally, a nice detail is that as soon as we defined an [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] method, the method [[Blocks_Howto#method_instance_allow_config| instance_allow_config]] that was already defined became obsolete. Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Blocks_Howto#method_instance_allow_config| instance_allow_config]] method now without harm. We had only needed it when multiple instances of the block were not allowed.
== The Effects of Globalization ==
Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with. For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.
This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

function has_config() {
return true;
}
Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file <span class="filename">/blocks/simplehtml/config_global.html</span> which again must be named just so, and copy paste the following into it:

<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict)) echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>
<p><input type="submit" value="<?php print_string('savechanges'); ?>" /></p>
</div>
True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean false) it displays the box as pre-checked (reflecting the current status). Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting. "block_simplehtml_strict" clearly satisfies both requirements.
The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?
Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.
However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.
To round our bag of tricks up, notice that the use of if(!empty($CFG->block_simplehtml_strict)) in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable $CFG->block_simplehtml_strict will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").
Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Blocks_Howto#method_config_save| config_save]], the default implementation of which is as follows:

function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}
else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).
So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?
We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.
Much as we did just before with overriding [[Blocks_Howto#method_config_save| config_save]], what is needed here is overriding the method [[Blocks_Howto#method_instance_config_save| instance_config_save]] which handles the instance configuration. The default implementation is as follows:

function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data['text'] = strip_tags($data['text']);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!
Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed. The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?
We will let this part of the tutorial come to a close with the obligatory excercise for the reader: in order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead. (Hint: do that in the [[Blocks_Howto#method_get_content| get_content]] method)
'''UPDATING'''<nowiki>: Prior to version 1.5, the file </nowiki><span class="filename">config_global.html</span> was named simply <span class="filename">config.html</span>. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.
== Eye Candy ==
Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.
First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

function hide_header() {
return true;
}
One more note here: we cannot just set an empty title inside the block's [[Blocks_Howto#method_init| init]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks_Howto#method_init| init]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.
Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.
To instruct Moodle about our block's preferred width, we add one more method to the block class:

function preferred_width() {
// The preferred value is in pixels
return 200;
}
This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.
Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).
The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").
To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => 'alert("Mouseover on our block!");'
);
}
will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required). And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Blocks_Howto#method_name| name]] method to make it dynamically match our block's name.
== Authorized Personnel Only ==
It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.
Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.
Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.
The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:
#* The format name for the front page of Moodle is '''site-index'''.
#* The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
#* Even though there is no such page, the format name '''all''' can be used as a catch-all option.
We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":
#* Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
#* The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
#* The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
#* The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

function applicable_formats() {
return array('site' => true);
}
Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to true, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).
For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

function applicable_formats() {
return array('course-view' => true, 'course-view-social' => false);
}
This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

function applicable_formats() {
return array('site-index' => true,
'course-view' => true, 'course-view-social' => false,
'mod' => true, 'mod-quiz' => false);
}
It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.
'''UPDATING:''' Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.
== Lists and Icons ==
In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.
As we have seen so far, blocks of use two properties of [[Blocks_Howto#variable_content| $this->content]]<nowiki>: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.</nowiki>
Instead, Moodle expects such blocks to set two other properties when the [[Blocks_Howto#method_get_content| get_content]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.
In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

class block_my_menu extends block_list {
// The init() method does not need to change at all
}
In addition to making this change, we must of course also modify the [[Blocks_Howto#method_get_content| get_content]] method to construct the [[Blocks_Howto#variable_content| $this->content]] variable as discussed above:

function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" width="16" height="16" alt="" />';

// Add more list items here

return $this->content;
}
To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks_Howto#method_get_content| get_content]] method. Adding the mandatory [[Blocks_Howto#method_init| init]] method as discussed earlier will then give us our first list block in no time!

== Appendix A: Reference ==

This Appendix will discuss the base class '''block_base''' from which all other block classes derive, and present each and every method that can be overridden by block developers in detail. Methods that should '''not''' be overridden are explicitly referred to as such. After reading this Appendix, you will have a clear understanding of every method which you should or could override to implement functionality for your block.

The methods are divided into three categories: those you may use and override in your block, those that you may '''not''' override but might want to use, and those internal methods that should '''neither''' be used '''nor''' overridden. In each category, methods are presented in alphabetical order.

=== Methods you can freely use and override: ===
** <div class="function_title">applicable_formats</div>

function applicable_formats() {
// Default case: the block can be used in courses and site index, but not in activities
return array('all' => true, 'mod' => false);
}
This method allows you to control which pages your block can be added to. Page formats are formulated from the full path of the script that is used to display that page. You should return an array with the keys being page format names and the values being booleans (true or false). Your block is only allowed to appear in those formats where the value is true.
Example format names are: '''course-view''', '''site-index''' (this is an exception, referring front page of the Moodle site), '''course-format-weeks''' (referring to a specific course format), '''mod-quiz''' (referring to the quiz module) and '''all''' (this will be used for those formats you have not explicitly allowed or disallowed).
The full matching rules are:
*** Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
*** The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
*** The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
*** The order that the format names appear does not make any difference.
** <div class="function_title">config_print</div>
<nowiki>
function config_print() {
// Default behavior: print the config_global.html file
// You don't need to override this if you're satisfied with the above
if (!$this->has_config()) {
return false;
}
global $CFG, $THEME;
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html');
print_simple_box_end();
return true;
}</nowiki>
This method allows you to choose how to display the global configuration screen for your block. This is the screen that the administrator is presented with when he chooses "Settings..." for a specific block. Override it if you need something much more complex than the default implementation allows you to do. However, keep these points in mind:
**# If you save your configuration options in $CFG, you will probably need to use global $CFG; before including any HTML configuration screens.
**# The HTML <input> elements that you include in your method's output will be automatically enclosed in a <form> element. You do not need to worry about where and how that form is submitted; however, you '''must''' provide a way to submit it (i.e., an <input type="submit" />.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">config_save</div>

function config_save($data) {
// Default behavior: save all variables as $CFG properties
// You don't need to override this if you 're satisfied with the above
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
This method allows you to override the storage mechanism for your global configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values. The default implementation saves everything as Moodle $CFG variables.
Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">get_content</div>

function get_content() {
// This should be implemented by the derived class.
return NULL;
}
This method should, when called, populate the [[Blocks_Howto#variable_content| $this->content]] variable of your block. Populating the variable means:
'''EITHER'''<br />defining $this->content->text and $this->content->footer if your block derives from '''block_base'''. Both of these should be strings, and can contain arbitrary HTML.
'''OR'''<br />defining $this->content->items, $this->content->icons and $this->content->footer if your block derives from '''block_list'''. The first two should be numerically indexed arrays having the exact same number of elements. $this->content->items is an array of strings that can contain arbitrary HTML while $this->content->icons also contains should strings, but those must be fully-qualified HTML <img> tags '''and nothing else'''. $this->content->footer is a string, as above.
If you set ''all'' of these variables to their default "empty" values (empty arrays for the arrays and empty strings for the strings), the block will '''not''' be displayed at all except to editing users. This is a good way of having your block hide itself to unclutter the screen if there is no reason to have it displayed.
Before starting to populate [[Blocks_Howto#variable_content| $this->content]], you should also include a simple caching check. If [[Blocks_Howto#variable_content| $this->content]] is exactly equal to NULL then proceed as normally, while if it is not, return the existing value instead of calculating it once more. If you fail to do this, Moodle will suffer a performance hit.
In any case, your method should return the fully constructed [[Blocks_Howto#variable_content| $this->content]] variable.
** <div class="function_title">has_config</div>

function has_config() {
return false;
}
This method should return a boolean value that denotes whether your block wants to present a configuration interface to site admins or not. The configuration that this interface offers will impact all instances of the block equally.
To actually implement the configuration interface, you will either need to rely on the default [[Blocks_Howto#method_instance_config_print| config_print]] method or override it. The full guide contains [[Blocks_Howto#section_effects_of_globalization| more information on this]].
** <div class="function_title">hide_header</div>

function hide_header() {
//Default, false--> the header is shown
return false;
}
This method should return a boolean value that denotes whether your block wants to hide its header (or title). Thus, if you override it to return true, your block will not display a title unless the current user is in editing mode.
** <div class="function_title">html_attributes</div>

function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.
If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:

function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
** <div class="function_title">init</div>

function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
This method must be implemented for all blocks. It has to assign meaningful values to the object variables [[Blocks_Howto#variable_title| $this->title]] and [[Blocks_Howto#variable_version| $this->version]] (which is used by Moodle for performing automatic updates when available).
No return value is expected from this method.
** <div class="function_title">instance_allow_config</div>

function instance_allow_config() {
return false;
}
This method should return a boolean value. True indicates that your block wants to have per-instance configuration, while false means it does not. If you do want to implement instance configuration, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
This method's return value is irrelevant if [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] returns true; it is assumed that if you want multiple instances then each instance needs its own configuration.
** <div class="function_title">instance_allow_multiple</div>

function instance_allow_multiple() {
// Are you going to allow multiple instances of each block?
// If yes, then it is assumed that the block WILL USE per-instance configuration
return false;
}
This method should return a boolean value, indicating whether you want to allow multiple instances of this block in the same page or not. If you do allow multiple instances, it is assumed that you will also be providing per-instance configuration for the block. Thus, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
** <div class="function_title">instance_config_print</div>
<nowiki>
function instance_config_print() {
// Default behavior: print the config_instance.html file
// You don't need to override this if you're satisfied with the above
if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
return false;
}
global $CFG, $THEME;

if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
print_simple_box_end();
} else {
notice(get_string('blockconfigbad'),
str_replace('blockaction=', 'dummy=', qualified_me()));
}

return true;
}</nowiki>
This method allows you to choose how to display the instance configuration screen for your block. Override it if you need something much more complex than the default implementation allows you to do. Keep in mind that whatever you do output from [[Blocks_Howto#method_instance_config_print| config_print]], it will be enclosed in a HTML form automatically. You only need to provide a way to submit that form.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">instance_config_save</div>

function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
This method allows you to override the storage mechanism for your instance configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values.
The configuration must be stored in the "configdata" field of your instance record in the database so that Moodle can auto-load it when your block is constructed. However, you may still want to override this method if you need to take some additional action apart from saving the data. In that case, you really should do what data processing you want and then call parent::instance_config_save($data) with your new $data array. This will keep your block from becoming broken if the default implementation of instance_config_save changes in the future.
Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
If you want to update the stored copy of the configuration data at run time (for example to persist some changes you made programmatically), you should not use this method. The correct procedure for that purpose is to call [[Blocks_Howto#method_instance_config_commit| instance_config_commit]].
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">preferred_width</div>

function preferred_width() {
// Default case: the block wants to be 180 pixels wide
return 180;
}
This method should return an integer value, which is the number of pixels of width your block wants to take up when displayed. Moodle will try to honor your request, but this is actually up to the implementation of the format of the page your block is being displayed in and therefore no guarantee is given. You might get exactly what you want or any other width the format decides to give you, although obviously an effort to accomodate your block will be made.
Most display logic at this point allocates the maximum width requested by the blocks that are going to be displayed, bounding it both downwards and upwards to avoid having a bad-behaving block break the format.
** <div class="function_title">refresh_content</div>

function refresh_content() {
// Nothing special here, depends on content()
$this->content = NULL;
return $this->get_content();
}
This method should cause your block to recalculate its content immediately. If you follow the guidelines for [[Blocks_Howto#get_content| get_content]], which say to respect the current content value unless it is NULL, then the default implementation will do the job just fine.
You should return the new value of [[Blocks_Howto#variable_content| $this->content]] after refreshing it.
** <div class="function_title">specialization</div>

function specialization() {
// Just to make sure that this method exists.
}
This method is automatically called by the framework immediately after your instance data (which includes the page type and id and all instance configuration data) is loaded from the database. If there is some action that you need to take as soon as this data becomes available and which cannot be taken earlier, you should override this method.
The instance data will be available in the variables [[Blocks_Howto#variable_instance| $this->instance]] and [[Blocks_Howto#variable_config| $this->config]].
This method should not return anything at all.
=== Methods which you should ''not'' override but may want to use: ===
** <div class="function_title">instance_config_commit</div>

function instance_config_commit() {
return set_field('block_instance',
'configdata', base64_encode(serialize($this->config)),
'id', $this->instance->id);
}
This method saves the current contents of [[Blocks_Howto#variable_config| $this->config]] to the database. If you need to make a change to the configuration settings of a block instance at run time (and not through the usual avenue of letting the user change it), just make the changes you want to [[Blocks_Howto#variable_config| $this->config]] and then call this method.
** <div class="function_title">get_content_type</div>

function get_content_type() {
return $this->content_type;
}
This method returns the value of [[Blocks_Howto#variable_content_type| $this->content_type]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">get_title</div>

function get_title() {
return $this->title;
}
This method returns the value of [[Blocks_Howto#variable_title| $this->title]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">get_version</div>

function get_version() {
return $this->version;
}
This method returns the value of [[Blocks_Howto#variable_version| $this->version]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">is_empty</div>
For blocks that extend class '''block_base'''<nowiki>:</nowiki>

function is_empty() {
$this->get_content();
return(empty($this->content->text) && empty($this->content->footer));
}
For blocks that extend class '''block_list'''<nowiki>:</nowiki>

function is_empty() {
$this->get_content();
return (empty($this->content->items) && empty($this->content->footer));
}
This method returns the a boolean true/false value, depending on whether the block has any content at all to display. Blocks without content are not displayed by the framework.
** <div class="function_title">name</div>

function name() {
static $myname;
if ($myname === NULL) {
$myname = strtolower(get_class($this));
$myname = substr($myname, strpos($myname, '_') + 1);
}
return $myname;
}
This method returns the internal name of your block inside Moodle, without the '''block_''' prefix. Obtaining the name of a block object is sometimes useful because it can be used to write code that is agnostic to the actual block's name (and thus more generic and reusable). For an example of this technique, see the [[Blocks_Howto#method_config_print| config_print]] method.
=== Methods which you should ''not'' override and ''not'' use at all: ===
** <div class="function_title">_self_test</div>
This is a private method; no description is given.
** <div class="function_title">_add_edit_controls</div>
This is a private method; no description is given.
** <div class="function_title">_load_instance</div>
This is a private method; no description is given.
** <div class="function_title">_print_block</div>
This is a private method; no description is given.
** <div class="function_title">_print_shadow</div>
This is a private method; no description is given.

The class '''block_base''' also has a few standard member variables which its methods manipulate. These variables, the purpose of each and the type of data they are expected to hold is explained in the next section of this Appendix.

=== Class variables: ===

* <div class="variable_title">$this->config</div>
This variable holds all the specialized instance configuration data that have been provided for this specific block instance (object). It is an object of type stdClass, with member variables directly corresponding to the HTML <input> elements in the block's <span class="filename">config_instance.html</span> file.
The variable is initialized just after the block object is constructed, immediately before [[Blocks_Howto#method_specialization| specialization]] is called for the object. It is possible that the block has no instance configuration, in which case the variable will be NULL.
It is obvious that there is a direct relationship between this variable and the configdata field in the mdl_block_instance table. However, it is ''strongly'' advised that you refrain from accessing the configdata field yourself. If you absolutely must update its value at any time, it is recommended that you call the method [[Blocks_Howto#method_instance_config_commit| instance_config_commit]] to do the actual work.
* <div class="variable_title">$this->content_type</div>
This variable instructs Moodle on what type of content it should assume the block has, and is used to differentiate text blocks from list blocks. It is essential that it has a meaningful value, as Moodle depends on this for correctly displaying the block on screen. Consequently, this variable is closely tied with the variable [[Blocks_Howto#variable_content| $this->content]]. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
The only valid values for this variable are the two named constants [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]] and [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]].
* <div class="variable_title">$this->content</div>
This variable holds all the actual content that is displayed inside each block. Valid values for it are either NULL or an object of class stdClass, which must have specific member variables set as explained below. Normally, it begins life with a value of NULL and it becomes fully constructed (i.e., an object) when [[Blocks_Howto#method_get_content| get_content]] is called.
After it is fully constructed, this object is expected to have certain properties, depending on the value of [[Blocks_Howto#variable_content_type| $this->content_type]]. Specifically:
** If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
*** <div>'''text'''</div>This is a string of arbitrary length and content. It is displayed inside the main area of the block, and can contain HTML.
*** <div>'''footer'''</div>This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
** If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
*** <div>'''items'''</div>This is a numerically indexed array of strings which holds the title for each item in the list that will be displayed in the block's area. Since usually such lists function like menus, the title for each item is normally a fully qualified HTML <a> tag.
*** <div>'''icons'''</div>This is a numerically indexed array of strings which represent the images displayed before each item of the list. It therefore follows that it should have the exact number of elements as the items member variable. Each item in this array should be a fully qualified HTML <img> tag.
*** <div>'''footer'''</div>This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
* <div class="variable_title">$this->instance</div>
This member variable holds all the specific information that differentiates one block instance (i.e., the PHP object that embodies it) from another. It is an object of type stdClass retrieved by calling get_record on the table mdl_block_instance. Its member variables, then, directly correspond to the fields of that table. It is initialized immediately after the block object itself is constructed.
* <div class="variable_title">$this->title</div>
This variable is a string that contains the human-readable name of the block. It is used to refer to blocks of that type throughout Moodle, for example in the administrator's block configuration screen and in the editing teacher's add block menu. It is also the title that is printed when the block is displayed on screen, although blocks can specifically change this title to something else if they wish (see below). The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each object.
In the case of blocks which may want to configure their title dynamically through instance configuration, it is still essential to provide a valid title inside [[Blocks_Howto#method_init| init]]. This title may then be overridden when the [[Blocks_Howto#method_specialization| specialization]] method is called by the framework:

function specialization() {
// At this point, $this->instance and $this->config are available
// for use. We can now change the title to whatever we want.
$this->title = $this->config->variable_holding_the_title;
}
* <div class="variable_title">$this->version</div>
This variable should hold each block's version number in the form '''YYYYMMDDXX''', as per the convention throughout Moodle. The version number is used by Moodle to detect when a block has been upgraded and it consequently needs to run the block's upgrade code to bring the "old" version of the block's data up to date. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
Most blocks do not keep complex data of their own in the database the way that modules do, so in most cases nothing actually happens during a block version upgrade. However, the version number is displayed in the administration interface for blocks. It is good practice therefore to change your block's version number when it gains new functionality or receives important bug fixes, to enable site administrators to easily identify the exact version of the block they are working with.

Appearing throughout the code related to the Blocks API, there is a number of predefined constants that are utilized to avoid the use of "magic numbers" in the code. These constants are:

=== Named constants: ===

* <div class="named_constant">BLOCK_TYPE_LIST</div>
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].
* <div class="named_constant">BLOCK_TYPE_TEXT</div>
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].

== Appendix B: Differences in the Blocks API for Moodle versions prior to 1.5 ==

This Appendix will discuss what changes in the Blocks API were introduced by Moodle 1.5 and what steps developers need to take to update their blocks to be fully compatible with Moodle 1.5. Unfortunately, with these changes backward compatibility is broken; this means that blocks from Moodle 1.4 will never work with 1.5 and vice versa.

=== Class naming conventions changed ===
In Moodle 1.4, all block classes were required to have a name like '''CourseBlock_something''' and the base class from which the derived was '''MoodleBlock'''. This has changed in Moodle 1.5, to bring the naming conventions in line with other object-oriented aspects of Moodle (for example there are classes enrolment_base, resource_base etc). The new block classes should instead be named like '''block_something''' and derive from '''block_base'''. This means that in order to make a block compatible with Moodle 1.5, you need to change the class definition

class CourseBlock_online_users extends MoodleBlock { ... }
to

class block_online_users extends block_base { ... }
An exception to the above is the special case where the block is intended to display a list of items instead of arbitrary text; in this case the block class must derive from class '''block_list''' instead, like this:

class block_admin extends block_list { ... }

=== Constructor versus init() ===

In Moodle 1.4, in each block class it was mandatory to define a constructor which accepted a course data record as an argument (the example is from the actual Online Users block):

function CourseBlock_online_users ($course) {
$this->title = get_string('blockname','block_online_users');
$this->content_type = BLOCK_TYPE_TEXT;
$this->course = $course;
$this->version = 2004052700;
}
In contrast, Moodle 1.5 does away with the constructor and instead requires you to define an init() method that takes no arguments:

function init() {
$this->title = get_string('blockname','block_online_users');
$this->version = 2004111600;
}
Of course, this leaves you without access to the $course object, which you might actually need. Since that's probably going to be needed inside [[Blocks_Howto#method_get_content| get_content]], the way to retrieve it is by using this code:

$course = get_record('course', 'id', $this->instance->pageid);
If you are going to need access to $course from inside other methods in addition to [[Blocks_Howto#method_get_content| get_content]], you might fetch the $course object inside the [[Blocks_Howto#method_specialization| specialization]] method and save it as a class variable for later use, in order to avoid executing the same query multiple times:

function specialization() {
$this->course = get_record('course', 'id', $this->instance->pageid);
}

=== Blocks with configuration ===
In Moodle 1.4, blocks could only have what are now (in Moodle 1.5) called "global configuration" options, to differentiate from the new "instance configuration" options. If your block has support for configuration, you will need to take these steps:
## Rename your <span class="filename">config.html</span> file to <span class="filename">config_global.html</span>.
## Edit the newly renamed file and completely remove the <form> tag (Moodle now wraps your configuration in a form automatically).
## If you are using any HTML <input> tags other than those that directly affect your configuration (for example, "sesskey"), REMOVE those too (Moodle will add them automatically as required).
## If you have overridden '''print_config''', rename your method to '''config_print'''.
## If you have overridden '''handle_config''', rename your method to '''config_save'''.
=== Blocks with customized applicable formats ===
The correct way to specify the formats you want to allow or disallow your block to exist has been reworked for Moodle 1.5 to take account of the fact that blocks are no longer restricted to just courses. To have a block retain its intended behavior, you must change these format names (array keys in the return value of [[Blocks_Howto#method_applicable_formats| applicable_formats]]) if they are used in your block:
#* '''social''' should become '''course-view-social'''
#* '''topics''' should become '''course-view-topics'''
#* '''weeks''' should become '''course-view-weeks'''
You should also keep in mind that there is now the possibility of blocks being displayed in other pages too, like the introductory page that users see when they enter an activity module. You might therefore need to make the specification for applicable formats more restrictive to keep your block out of pages it is not supposed to be shown in. Also, there are subtle changes to the way that the final decision to allow or disallow a block is made. For the technical details refer to the definition of [[Blocks_Howto#method_applicable_formats| applicable_formats]], and for a more extended example read [[Blocks_Howto#section_authorized_personnel_only| the section dedicated to this subject]].
That's everything; your block will now be ready for use in Moodle 1.5!

Development:Question type plugin how to

2006-02-08T19:46:45Z

Gustav:

{{Quiz developer docs}}
There is no Guide yet. The code is the only documentation. The quickest way we are going to get a Guide is if everyone who gains some experience with the questiontypes shares this experience here as they go along. After a while we will be able to assemble the combined wisdom into a guide.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz

2006-02-08T00:34:16Z

Gustav: /* Code documentation */

{{Quiz developer docs}}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. This page aims to collect useful documentation on how the module works.

==Terminology==

When talking about the quiz module there are certain terms that can cause confusion because they can be used with different meanings. In Moodle we have adopted a certain terminology that will be explained below.

===Questions===

A '''question''' in the context of the quiz module is the set of definitions (question name, question text, possible answers, grading rules, feedback, etc.) that constitute a reusable assessment item. So it is much more than what one would in everyday language understand under a question and which in Moodle is just on field (the questiontext field) of the question object.

What in Moodle we refer to as a 'question' is what in the terminology of the QTI specification ismore appropriately called an '''assessment item''' or just 'item' for short.

There are different types of questions, like for example multiple-choice questions or numerical questions. These are referred to as '''[[Quiz developer docs#Question types|question types]]''' in Moodle.

Since version 1.5 Moodle is able to handle so-called '''[[Adaptive questions]]''', also known as 'adaptive items' in QTI speak. These are qustions that walk the user through a directed graph of question states depending on the user's responses. For example 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. Quizzes can be run in 'adaptive mode', which provides buttons to mark each question individually.

===Answers===

In Moodle the term ''''answer'''' is used exclusively for the '''teacher-defined answers''' of a question. When talking about the quiz module it is easy to get confused between these teacher-defined answers and the answers that the students actually give. We have therefore adopted the convention to refer to the student-supplied answers as 'responses' and to reserve the term 'answers' to apply to teacher-defined answers. In question types that rely on teacher-supplied answers these are used in the grading process by comparing them with the student responses. Of course not all question types use teacher-defined answers but use some more intelligent way to process the student responses.

Perhaps one should also stress that 'answer' is not always used in the sense of 'correct answer'. For example every choice in a multiple-choice question is referred to as an answer. Other systems use the term 'distractor' for wrong answers.

In Moodle we always use the term ''''responses'''' to refer to the students' responses to a question because term 'answers' that one might also be tempted to use for this is already used to refer to the teacher-defined answers, see above. This term is always used in plural, although for some questiontypes there is only one possible response.

There is unfortunately, for historical reasons, one exception to the above rule: The [[Quiz database structure#quiz_states|quiz_states table]] has a field 'answer' whose purpose it actually is to hold the student's responses.

===Attempts===

In Moodle 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 ''''attempts at a question'''', never just as 'attempts'.

Because a student can have several attempts at a question within the same attempt at the quiz, there is a lot of data that needs to be stored as the student takes the question through several ''''states'''' by repeated interactions with the question. A state object holds the most recent state of the question and whenever a student submits a response or a similar ''''event'''' occurs, the question goes to a new state. The complete history of question states that the question is taken through is saved and this is referred to as the question ''''session''''. Usually only the most recent state and the last graded state are of interest though.

==Code documentation==

The code is documented according to phpdoc conventions. The explanations here in the wiki are meant to complement this.

Inline comments should be used liberally in the code. The following conventions make it easier to search for comments with special meaning:
* use TODO in comments about things that need to be done
* use ??? in comments that are questions about the code

There are three function libraries:

;questionlib.php
:All functions that need to be available to any module wanting to use questions. This is New in Moodle 1.6, in Moodle 1.5 this was part of locallib.php. This instantiates all questiontype classes by loading the questiontype.php files

;lib.php
:All the functions that are sometimes called by the Moodle core. This loads constants from '''constants.php'''

;locallib.php
:All functions that are used only by the quiz module. This loads lib.php and questionlib.php

The default questiontype class is defined in '''questiontypes/questiontype.php''' (in Moodle 1.5 this was still in locallib.php). The individual questiontypes extend this class in their own questiontype.php file. For documentation of the questiontype classes one should often look at the documentation of the default question type because much of the documentation that is in the default class is not repeated in the other questiontype classes

Constants are defined in '''constants.php'''.

While questiontypes are realized as classes, the quiz module is not written in a truly object-oriented way. Instead it follows the Moodle model of using objects mostly only as alternatives to arrays to hold database records. So none of the quiz, question, attempt, and state objects that play a central role in the module have any methods. Only the questiontype objects have methods. Strangely enough the quiz module instantiates on object of each questiontype class at the start and then reuses their methods for the different questions. If one is used to the Moodle way of programming then this is easy enough to handle.

==Objects and data structures==

Key to understanding how the quiz module works is to understand the different kinds of object work together. The most important ones are:

*Quizzes
*Questions
*Attempts
*States

Quizzes and Questions are data created by the teacher when setting up and editing a quiz. Attempts and States are data created by the student when interacting with a quiz.

Moodle allows students to make several attempts at a quiz. Data about such an attempt is stored in an attempt object. This holds for example how the quiz was randomized for this attempt and the ordering of the questions and answers. So attempts are indexed by user id and quiz id.

Moodle allows students to interact repeatedly with a single question. So for example the student might initially just save an answer, later mark it, then correct it if it was marked incorrect. Each time the student interacts with a particular question inside a particular attempt at a quiz a new state is created. So states are indexed by user id, attempt id and question id.

===Database structure===
All this data needs to be kept in Moodle's database. How this is achieved is explained on a separate page about the '''[[Quiz database structure]]''', which also contains a useful diagram.

As is customary in Moodle, most runtime objects simply represent the data from a particular database record. So for example a $quiz object has fields corresponding to all the fields in the [[Quiz database structure#quiz|quiz table]]. In some cases the objects have some additional fields that are added at runtime. This is particularly the case for $question and $state objects. These additional fields are also described on the page about the '''[[Quiz database structure]]'''. Many functions that are used to process these objects make use of the additional fields and it is therefore necessary to use the correct functions for creating these objects.

===Runtime objects===
Some objects used by the quiz module are purely runtime object and do not correspond to a database table. The structure of these objects is explained in detail on a separate page about the '''[[Quiz runtime objects]]'''.

The main script of the quiz module is attempt.php which will have to deal with all these objects. Studying the '''[[Quiz attempt|explanation of attempt.php]]''' is therefore a good way to start to study the quiz module code.

==Response storage==

The student's responses to a question are stored in <code>$state->responses</code>. Questiontypes are completely free to implement the storage mechanism of their responses (and other state information) the way they want. Still, the standard questiontypes all follow a similar model. The default storage model and the questiontype specific variations are explained below.

The flexibility for the questiontypes to choose their response storage mechanism freely and to convert from the storage model to the runtime model is provided by a set of three functions, which allow to initialise the runtime <code>$state->responses</code> field, to convert from the runtime to the storage model and vice versa:

;<code>create_session_and_responses()</code>
:Initializes the $state object, in particular the <code>$state->responses</code> field

;<code>restore_session_and_responses()</code>
:Loads the question type specific session data from the database into the <code>$state</code> object, in particular it loads the responses that have been saved for the given <code>$state</code> into the <code>$state->responses</code> field.

;<code>save_session_and_responses()</code>
:Saves the question type specific session data from the $state object to the database. In particular, for most questiontypes, it saves the responses from the <code>$state->responses</code> to the database.

The generic quiz module code saves the contents form the <code><nowiki>$state->responses['']</nowiki></code> field to the answer field in the [[Quiz database structure#quiz_states|quiz_states table]] and also automatically restores the contents of this field to <code><nowiki>$state->responses['']</nowiki></code>. This means that any questiontype, which only expects a single value as its response can skip the implementation of the three methods described above. All questiontypes that have multiple value responses need to implement these methods.

The default questiontypes handle this problem by serializing/de-serializing the responses to/from the answer field in the quiz_states table. However, it is also possible (and may be better practice) to extend the quiz_states table with a questiontype specific table, i.e. take the id of the quiz_states record as a foreign key in the questiontype specific table. Because the value of <code><nowiki>$state->responses['']</nowiki></code> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <code>save_session_and_responses()</code>) whatever value the generic code set this field to with their serialized value (usually achieved with a simple set_field).

In the method <code>restore_session_and_responses()</code> the serialized value can be read from <code><nowiki>$state->responses['']</nowiki></code> because this is where the value from answer field of the quiz_states table has been moved. Care needs to be taken that this array value is then unset or the whole array overwritten, so that the array does not accidentally contain a value with the empty string index.

==Response processing==

The runtime model for responses dictates the structure of the $state->responses array. Starting with the names of the form elements this section goes through the relevant processing steps and thus attempts to clarify why the keys of the $state->responses array can differ for different questiontypes; even more, it explains how the array keys are chosen and set.

Although it may initially seem strange to start with the naming convention of the form fields, the reason for this will become clear later on. The controls (i.e. the form fields) of a question get printed by the method <code>print_question_formulation_and_controls()</code>. The convention only dictates that the name of the control element(s) must begin with the value of <code>$question->name_prefix</code>. The <code>$question->name_prefix</code> is a string starting with "resp" followed by the question id and an underscore, e.g. <code>resp56_</code>. In the default case, when there is only a single control element (this includes the case of a list of equally named radio buttons), no postfix is appended to the name prefix. For questiontypes that allow or require multiple form elements, an arbitrary string can be appended to the name prefix to form the name of these form elements. The postfix must not include any relational data (i.e. ids of records in the quiz_answers table), because this can lead to problems with regrading of versioned questions.

After the printing of the question the server only sees it again when it is submitted. So the submitted data will contain several values indexed by strings starting with <code>respXX_</code>. Upon submission, the function <code>quiz_process_responses()</code> is called, which assigns the submitted responses to the state of the question with id XX, using the postfix (i.e. everything after the underscore) as array keys. In the default case with only one control element the name only consists of the name prefix. This explains why the default index of the <code>$state->responses</code> array is the empty string. The value of each array element is obviously the value that was submitted by the form, basically a raw response.

The function <code>quiz_process_responses()</code> in turn calls the questiontype specific method <code>grade_responses()</code> to assign a grade to the submitted responses and <code>compare_responses()</code> to determine whether the response was identical to the previous submission and to avoid regrading the same responses repeatedly. These questiontype specific functions need to be aware of the expected keys of the <code>$state->responses</code> array.

Finally, the methods <code>restore_session_and_responses()</code> and <code>save_session_and_responses()</code> also need to know the questiontype specific layout of the <code>$state->responses array</code> and restore or save the information, e.g. by converting from or to the data representation.

==Question types==
{{Questiontype developer docs}}
The quiz module is itself modular and allows question type plug-ins. For each question type there should be a page, accessible via the menu at the right, which provides at least the dtails about
*Database tables
*Response storage
*Question options object
*State options object

It is hoped that Moodlers will contribute a lot of non-core question types in the future. For this it would be good to start a [[Guide to question type plugins]].

==Grades==

The handling of grades is a bit complicated because there are so many different grades around that get rescaled and combined in various ways. This section should summarize how this is done and why.

The following grade fields are being used:
*$question->defaultgrade
::This is the default value for the maximum grade for this question. This is set up when the teacher creates the question and it is stored in an int(10) field in the [[Quiz database structure#quiz_questions|quiz_questions]] table. However when the question is actually used in a particular quiz the teacher can overrule this default and this is stored in:
*$question->maxgrade
::This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in an int(10) field in the [[Quiz database structure#quiz_question_instances|quiz_question_instances table]].
*$question->penalty

*$state->raw_grade
*$state->grade
*$state->penalty
*$state->sumpenalty

*$attempt->sumgrades

The maximum grades set by the teacher, $question->defaultgrade and $question->maxgrade, are integers. All student-obtained grades are in principle floating point numbers. For historical reasons they are stored in the database as varchar(10) fields. Care has to be taken when writing to the database to make sure all grades are correctly rounded and squeezed into a string of no more than 10 characters, otherwise the writing to database will fail, see bug 4220.

The final outcome of the calculation of the grade for a user at a particular quiz is stored in the 'grade' field of the [[Quiz database structure#quiz_grades|quiz_grades table]]. This field has type double.

==Penalty mechanism==

===What it is for===

When the quiz is run in adaptive mode the student can interact with a question repeatedly. So in particular the student can try again when he gets a wrong answer. Clearly the final mark for the question must reflect the fact that the student did not get it right originally. Therefore a penalty is subtracted from the final mark.

===How the penalty is determined===

First of all penalties are relevant only if a quiz is run in adaptive mode. Only in this case can a student have a second attempt and therefore only in this mode can there be any occasion to subtract a penalty.

Even in adaptive mode the penalty mechanism is only used when it is selected in the quiz options. If "Apply penalties" is set to "No" then the final mark for the question is the mark for the last graded response.

Each question has a 'penalty' field (which should really be called 'penaltyfactor') which is a number between 0 and 1. The penalty for a wrong response is calculated as the product ($quiz->penalty * $quiz->grade), i.e., as the product of the penaltyfactor with the maximum achievable grade for the question. This product is stored in $state->penalty. So $quiz->penalty is the fraction of the maximum grade that is subtracted as a penalty for each wrong response.

The $quiz->penalty field has a default value of 0.1, both in the database and in mod/quiz/defaults.php. This default can of course be overwritten by the admin on the quiz configuration page. This admin-selected default is (as usual for admin defaults) stored in $CFG->quiz_penalty. The teacher can choose a different penalty factor for each individual question when adding or editing a question.

Now if a student makes repeated wrong attempts (or partially correct attempts) the penalties for all these attempts are added up in $state->sumpenalties. The mark for the question is then calculated as the mark for the last graded response minus the sum of the penalties.

One curious fact about $state->sumpenalties is that, for efficiency reasons, it is not stored in the quiz_states table but instead in the 'sumpenalty' field of the quiz_newest_states table. That way it only has to be stored once per attempt rather than once per response.

===Where it is done in the code===

The function quiz_apply_penalty_and_timelimit() subtracts the penalty in $state->sumpenalty from the raw grade in $state->raw_grade to obtain $state->grade for the response. However it is ensured that the grade of a new attempt at the question never falls below the previously achieved grade. This function also increases $state->sumpenalty by the amount in $state->penalty. The assumption is that $state->penalty has just been set appropriately by the code calling this function, e.g., quiz_process_responses.

==Time limit==

A quiz can have a time limit. This is stored in minutes in $quiz->timelimit. So before using this in time calculations it always has to be multiplied by 60 to turn it into seconds like all other timestamps in moodle and php. If $quiz->timelimit is zero it means there is no timelimit.

If a student asks to start an attempt on view.php for a quiz with a timelimit then he is shown a javascript message alerting him to the timelimit and is asked to confirm.

For quizzes with timelimit attempt.php shows a javascript timer that counts down and automatically submits and closes the attempt when the time is up.

Confusingly there are two javascript timers in the quiz module. jsclock.php provides a countdown in the title bar that counts down to the quiz closing time if this is less than a day away. This has nothing to do with the timelimit. jstimer.php provides the countdown timer that implements the timelimit. It in turn uses timer.js.

The time a response was submitted by the student is recorded by attempt.php right at the top of the page and is then passed on to quiz_process_responses in $action->timestamp. This puts it into $state->timestamp. Finally, after the responses have been graded, the function quiz_apply_penalty_and_timelimit() checks that the responses are within the timelimit to within 5% and if not it sets the grade to zero (or the previously obtained grade, if that is higher).

==Pagination==

Quiz attempts can be paginated, i.e., spread over several pages. The student can navigate between the pages using the standard Moodle paging bar. When the student navigates to a different quiz page the answers on the current page are automatically submitted for saving (but not grading).

To do this automatic submission the paging bar needs some javascript. It is therefore not produced with Moodle's standard print_paging_bar() function from weblib.php but with quiz_print_navigation_panel() which is defined in mod/quiz/locallib.php and produces something that looks the same.

The teacher has complete control via the edit interface on edit.php over where the page breaks should occur. He can repaginate the quiz with any chosen number of questions per page. He can also move the page-breaks up and down using the arrows.

Internally page breaks are stored in the $quiz->questions field (which now should really be called $quiz->layout). This field contains a comma separated list of questionids and pagebreaks where the pagebreaks are represented by the id 0. For example 23,12,0,11, 0 means that the two questions with ids 23 and 12 are on the first page and the question with id 11 is on the second page. The last page break is invisible and Moodle sometimes puts it there itself for its own convenience.

Because the quiz has an option $quiz->shufflequestions to shuffle questions the layout that the student sees in a particular attempt does not necessarily have to be the same as that stored in $quiz->questions. Therefore each attempt has its own $attemp->layout field. If $quiz->shufflequestions is false then this just contains a copy of $quiz->questions but if it is true then during the creation of a new attempt by quiz_create_attempt() the function quiz_repaginate() is used to produce a layout with $quiz->questionsperpage number of questions per page that are randomly ordered.

Both attempt.php and review.php use the $attempt->layout field to determine what questions to show on a particular page. That way we can guarantee that the student will, for a particular attempt, always see the questions in the same order and with the same pagination, both while attempting and during review. Also a teacher when reviewing a student's attempt sees the pages the same way they were shown to the student. However the teacher is also given the option to see all questions on one page.

There are some functions in locallib.php dedicated to handling the layout fields: quiz_questions_on_page(), quiz_questions_in_quiz(), quiz_number_of_pages(), quiz_first_questionnumber(), quiz_repaginate(). They are very short functions. The function quiz_first_questionnumber() that determines the number of the first question on a particular page makes use of the $question->length field. To allow this calculation to be fast is the main reason why that field is in the question table even though it could also be determined easily from the question type.

==Question versioning==

'''Note:''' Question versioning is currently disabled until it is re-developed to fix all reported issues.

When questions that were already attempted by a student are edited, it can be important to keep a copy of the question as it was before editing in order to reconstruct the quiz as it was seen by the student. To provide this functionality a question versioning mechanism was implemented.

The first goal, namely keeping around old questions, is easily achieved. They are just not deleted any more. However, this is not enough; it is also necessary to store which questions are versions of others. To achieve this goal, there is an additional table, which stores the versioning information: quiz_question_versions.

When a question is replaced for which there are already student attempts then all the attempt data gets associated to the new version of the question and is re-graded. This requires the question ids in the quiz_attempts, quiz_states and quiz_newest_states tables to be replaced by the new id. However we do also want to be able to reconstruct the quiz the way the student saw it when he gave his answers. For that purpose the id of the original question is always preserved in the 'originalquestion' field of the quiz_states table.

If all old versions of questions are kept around this could horribly clutter the editing interface. Therefore a field called hidden was added to the quiz_questions table and all old versions of edited questions are automatically hidden. When this flag is set to 1 the question is not displayed in the list of available questions, unless the user chooses to show them.

While the mechanism above should work as described, there is some additional complexity in order to minimise the number of versions created. If a question is created and has not been attempted by a student yet (this excludes teacher previews of the individual question and the quiz!), the database record will be reused (i.e. overwritten) and no new version will be created. This is especially important when the question is created and the first 2 or 3 mistakes are only noticed during preview.

On the editing screen for questions an additional set of options was introduced (see image).
Replacement Options
It shows which quizzes use the edited question and how many students have attempted it in a particular quiz. Based on this information it is then possible to choose in which quizzes the new version of the question should be used and in which ones the old one should remain.

By default the 'replace' checkbox for all quizzes that don't have any students' attempts are checked and in addition, if the question is edited out of a quiz context (i.e. not in the category question list), the 'replace' option is checked for that quiz as well.

===Database===

The changes to the database structure are limited to an added field (hidden) in the quiz_questions table and an additional table called quiz_question_versions. However, dealing with the quiz_questions table has become slightly more complicated.

The hidden field in the quiz_questions table has no implications for the core functionality. It is only used to determine, as the name implies, whether the question is shown in the category list or not.

The table quiz_question_versions stores information about the actual change. This information includes the ids of the old question and the new question, the id of the user who did the change and a timestamp. Quite importantly, the id of the quiz, in which the question was replaced is also stored. This means that the versions table provides a history of the different states the quiz went through until it was edited to be at the current state. The information allows to recreate a quiz as it was at any point in time (from a data perspective - this possibility is not used extensively by the code).

===Adjustments to the Data===

When a question is replaced by a newer version, database records are updated in the order shown below (compare with question.php):

* First a new record is inserted into the quiz_question_versions table for each affected quiz (i.e. each quiz in which the question was replaced).
* Then, for each affected quiz, the comma separated list of question ids in the question field is updated by replacing the old question id with the new one.
* In the quiz_question_instances table the record that links the old question to the quiz is also updated to point to the new question.
* In all attempts belonging to the old question the comma-separated list of question ids in the layout field are changed by replacing the old id by the new one.
* All states belonging to the old question are made to belong to the new version by changing the id in the 'question' field. However if we are replacing the original question then the id of this original version is stored in the originalquestion field.
* We have to change the questionid field in quiz_newest_states.
* Finally we have to do any question-type specific changes. For example question types that store student responses by storing the id of the answer in the quiz_answers table will have to recode these ids in all the states to point to the corresponding answers in the new version. This is handled by the function replace_question_in_attempts() in the question type class.

===Affected Code and Functionality===

Note: This section should still be considered under construction until the question mark behind bug #3311 is taken off.

In the file review.php and potentially also in the file attempt.php, if a question is edited during a student's attempt, the data from quiz_question_versions needs to be taken into account. If a student has attempted a quiz and a question was changed afterwards (i.e. a new version of that question was created), the question id of the old version remains in the comma separated list inside the attempt->layout field. However, since the records in the quiz_question_instances table get updated, we need to go forward in the question history, by looping through entries from the quiz_question_versions table, to find out the id of the question version that is currently used in the quiz.

Suggestion: With a fairly simple change to the convention of what is stored in the quiz_question_versions table we could get rid of the requirement of looping through all the versions. If in the newquestion field we store the id of the question that is currently used in the quiz, it would be possible to get the complete history for a question quite simply by selecting by quiz id and newquestion.

It should be fairly simple to write an upgrade script for this change. Additionally, another set_field would need to be added to question.php to change the newquestion field to the new question id. The benefits would be a much simpler handling of the question history, resulting in more efficient code than the current fix for bug #3311 in review.php.

The place where all the versioning actually takes place is question.php. Here the changes described in Adjustments to the Data are carried out.

Obviously the backup and restore scripts also take quiz_question_versions into account, however, they don't need to be concerned with the ways the data is used.

==Changes for Moodle 1.5: adaptive questions==

During the first half of 2005 the quiz module code has undergone a considerable rewrite to allow for adaptive questions in which a question session can consist of several sequential student responses. The question can adapt itself to the student answers. For example in response to certain answers the question could provide feedback or hints and then ask the student to answer again or give the student a simpler or related question.

Unfortunately many changes had to be made to the question type methods. This has however resulted in improved efficiency and has made the writing of question types easier. It also allows question types with more powerful features and has fixed some bugs / annoying behaviour.

For details see:
*[[Quiz rewrite|Quiz module rewrite]]
*[[Quiz conversion|How to convert existing question types]]

Of course there were countless other changes to the quiz module going from Moodle 1.4 to 1.5, especially to the teacher interface. However in spite of the fact that these changes are a lot more visible they were much less drastic from the point of view of the code. Here is a very incomplete list of changes:

* New quiz results overview page
* Reform of the quiz edit page: Changes on the quiz edit page are saved straightaway, not only after Save button is pressed.
* Copying questions: The teacher can create a new question using a previous one as template.
* Moving questions: The teacher can now move selected questions to a different category.
* Re-marking after question editing: if a teacher corrects a question that students have already attempted the teacher can request a remark.
* Teacher preview tab.
* Detailed teacher control over what students can see during review.

==Changes for Moodle 1.6: separating questions from quizzes==

The quiz module is not the only activity module in Moodle that uses questions. The lesson does too and potentially questions could be useful in many modules. Therefore we have started to rewrite some of the quiz module functions and move them from locallib.php to questionlib.php so that eventually they could be moved into a central library and be used by other modules.

Module developers who want to use the
quiz module questions in their own module should take a look at the simple questiondemo module that you can find in CVS at [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/questiondemo contrib/questiondemo]. The idea is that it will be simpler
to understand this demonstration module than the code in the quiz module which
is very complicated due to the many options and features. The interesting code in the questiondemo module is in view.php. There you can see how to
both render and score questions. This module requires the version of the quiz module from Moodle 1.6dev or later.

The details of the changes are explained on the page [[Separating questions from quizzes]].

==Future plans==

The features below are in no particular order:

* Editing questions: This is about editing questions after students have already attempted them. There needs to be a mechanism to keep the old versions of the question around for auditing purposes.
* New quiz statistics pages?: These pages should be built by using functions defined by the individual question types.
* Manual grade override: Teachers should be able to override the automatically calculated grades and should be able to make comments.
* Off-line questions: The answers to these are handed in off-line in the conventional way (e.g., on paper) and teachers enter marks on Moodle.
* Batch printing of quiz sheets: We want to be able to hand out question sheets to students so they can start working on the questions before going to the computer.
* Question preview from question edit page: so the teacher can try the question already before saving the changes.
* Show table of questions on view.php: gives teachers and students a bit of an overview of the quiz.
* Extending deadlines for individual students: for example when a student misses a deadline for good reasons.
* Filtering questions by quiz and by search: More ways to restrict which questions are shown on the quiz editing page.
* Re-open quizzes for revision: After the due date has passed the quiz could allow practice attempts.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz

2006-02-08T00:32:18Z

Gustav: Reverted edit of Gbrackett, changed back to last version by Gustav

{{Quiz developer docs}}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. This page aims to collect useful documentation on how the module works.

==Terminology==

When talking about the quiz module there are certain terms that can cause confusion because they can be used with different meanings. In Moodle we have adopted a certain terminology that will be explained below.

===Questions===

A '''question''' in the context of the quiz module is the set of definitions (question name, question text, possible answers, grading rules, feedback, etc.) that constitute a reusable assessment item. So it is much more than what one would in everyday language understand under a question and which in Moodle is just on field (the questiontext field) of the question object.

What in Moodle we refer to as a 'question' is what in the terminology of the QTI specification ismore appropriately called an '''assessment item''' or just 'item' for short.

There are different types of questions, like for example multiple-choice questions or numerical questions. These are referred to as '''[[Quiz developer docs#Question types|question types]]''' in Moodle.

Since version 1.5 Moodle is able to handle so-called '''[[Adaptive questions]]''', also known as 'adaptive items' in QTI speak. These are qustions that walk the user through a directed graph of question states depending on the user's responses. For example 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. Quizzes can be run in 'adaptive mode', which provides buttons to mark each question individually.

===Answers===

In Moodle the term ''''answer'''' is used exclusively for the '''teacher-defined answers''' of a question. When talking about the quiz module it is easy to get confused between these teacher-defined answers and the answers that the students actually give. We have therefore adopted the convention to refer to the student-supplied answers as 'responses' and to reserve the term 'answers' to apply to teacher-defined answers. In question types that rely on teacher-supplied answers these are used in the grading process by comparing them with the student responses. Of course not all question types use teacher-defined answers but use some more intelligent way to process the student responses.

Perhaps one should also stress that 'answer' is not always used in the sense of 'correct answer'. For example every choice in a multiple-choice question is referred to as an answer. Other systems use the term 'distractor' for wrong answers.

In Moodle we always use the term ''''responses'''' to refer to the students' responses to a question because term 'answers' that one might also be tempted to use for this is already used to refer to the teacher-defined answers, see above. This term is always used in plural, although for some questiontypes there is only one possible response.

There is unfortunately, for historical reasons, one exception to the above rule: The [[Quiz database structure#quiz_states|quiz_states table]] has a field 'answer' whose purpose it actually is to hold the student's responses.

===Attempts===

In Moodle 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 ''''attempts at a question'''', never just as 'attempts'.

Because a student can have several attempts at a question within the same attempt at the quiz, there is a lot of data that needs to be stored as the student takes the question through several ''''states'''' by repeated interactions with the question. A state object holds the most recent state of the question and whenever a student submits a response or a similar ''''event'''' occurs, the question goes to a new state. The complete history of question states that the question is taken through is saved and this is referred to as the question ''''session''''. Usually only the most recent state and the last graded state are of interest though.

==Code documentation==

The code is documented according to phpdoc conventions. The explanations here in the wiki are meant to complement this.

Inline comments should be used liberally in the code. The following conventions make it easier to search for comments with special meaning:
* use TODO in comments about things that need to be done
* use ??? in comments that are questions about the code

There are three function libraries:

;questionlib.php
:All functions that need to be available to any module wanting to use questions. This is New in Moodle 1.6, in Moodle 1.5 this was part of locallib.php. This instantiates all questiontype classes by loading the questiontype.php files

;lib.php
:All the functions that are sometimes called by the Moodle core. This loads constants from '''constants.php'''

;locallib.php
:All functions that are used only by the quiz module. This loads lib.php and questionlib.php

The default questiontype class is defined in '''questiontypes/questiontype.php'''. The individual questiontypes extend this class in their own questiontype.php file. For documentation of the questiontype classes one should often look at the documentation of the default question type because much of the documentation that is in the default class is not repeated in the other questiontype classes

Constants are defined in .

While questiontypes are realized as classes, the quiz module is not written in a truly object-oriented way. Instead it follows the Moodle model of using objects mostly only as alternatives to arrays to hold database records. So none of the quiz, question, attempt, and state objects that play a central role in the module have any methods. Only the questiontype objects have methods. Strangely enough the quiz module instantiates on object of each questiontype class at the start and then reuses their methods for the different questions. If one is used to the Moodle way of programming then this is easy enough to handle.

==Objects and data structures==

Key to understanding how the quiz module works is to understand the different kinds of object work together. The most important ones are:

*Quizzes
*Questions
*Attempts
*States

Quizzes and Questions are data created by the teacher when setting up and editing a quiz. Attempts and States are data created by the student when interacting with a quiz.

Moodle allows students to make several attempts at a quiz. Data about such an attempt is stored in an attempt object. This holds for example how the quiz was randomized for this attempt and the ordering of the questions and answers. So attempts are indexed by user id and quiz id.

Moodle allows students to interact repeatedly with a single question. So for example the student might initially just save an answer, later mark it, then correct it if it was marked incorrect. Each time the student interacts with a particular question inside a particular attempt at a quiz a new state is created. So states are indexed by user id, attempt id and question id.

===Database structure===
All this data needs to be kept in Moodle's database. How this is achieved is explained on a separate page about the '''[[Quiz database structure]]''', which also contains a useful diagram.

As is customary in Moodle, most runtime objects simply represent the data from a particular database record. So for example a $quiz object has fields corresponding to all the fields in the [[Quiz database structure#quiz|quiz table]]. In some cases the objects have some additional fields that are added at runtime. This is particularly the case for $question and $state objects. These additional fields are also described on the page about the '''[[Quiz database structure]]'''. Many functions that are used to process these objects make use of the additional fields and it is therefore necessary to use the correct functions for creating these objects.

===Runtime objects===
Some objects used by the quiz module are purely runtime object and do not correspond to a database table. The structure of these objects is explained in detail on a separate page about the '''[[Quiz runtime objects]]'''.

The main script of the quiz module is attempt.php which will have to deal with all these objects. Studying the '''[[Quiz attempt|explanation of attempt.php]]''' is therefore a good way to start to study the quiz module code.

==Response storage==

The student's responses to a question are stored in <code>$state->responses</code>. Questiontypes are completely free to implement the storage mechanism of their responses (and other state information) the way they want. Still, the standard questiontypes all follow a similar model. The default storage model and the questiontype specific variations are explained below.

The flexibility for the questiontypes to choose their response storage mechanism freely and to convert from the storage model to the runtime model is provided by a set of three functions, which allow to initialise the runtime <code>$state->responses</code> field, to convert from the runtime to the storage model and vice versa:

;<code>create_session_and_responses()</code>
:Initializes the $state object, in particular the <code>$state->responses</code> field

;<code>restore_session_and_responses()</code>
:Loads the question type specific session data from the database into the <code>$state</code> object, in particular it loads the responses that have been saved for the given <code>$state</code> into the <code>$state->responses</code> field.

;<code>save_session_and_responses()</code>
:Saves the question type specific session data from the $state object to the database. In particular, for most questiontypes, it saves the responses from the <code>$state->responses</code> to the database.

The generic quiz module code saves the contents form the <code><nowiki>$state->responses['']</nowiki></code> field to the answer field in the [[Quiz database structure#quiz_states|quiz_states table]] and also automatically restores the contents of this field to <code><nowiki>$state->responses['']</nowiki></code>. This means that any questiontype, which only expects a single value as its response can skip the implementation of the three methods described above. All questiontypes that have multiple value responses need to implement these methods.

The default questiontypes handle this problem by serializing/de-serializing the responses to/from the answer field in the quiz_states table. However, it is also possible (and may be better practice) to extend the quiz_states table with a questiontype specific table, i.e. take the id of the quiz_states record as a foreign key in the questiontype specific table. Because the value of <code><nowiki>$state->responses['']</nowiki></code> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <code>save_session_and_responses()</code>) whatever value the generic code set this field to with their serialized value (usually achieved with a simple set_field).

In the method <code>restore_session_and_responses()</code> the serialized value can be read from <code><nowiki>$state->responses['']</nowiki></code> because this is where the value from answer field of the quiz_states table has been moved. Care needs to be taken that this array value is then unset or the whole array overwritten, so that the array does not accidentally contain a value with the empty string index.

==Response processing==

The runtime model for responses dictates the structure of the $state->responses array. Starting with the names of the form elements this section goes through the relevant processing steps and thus attempts to clarify why the keys of the $state->responses array can differ for different questiontypes; even more, it explains how the array keys are chosen and set.

Although it may initially seem strange to start with the naming convention of the form fields, the reason for this will become clear later on. The controls (i.e. the form fields) of a question get printed by the method <code>print_question_formulation_and_controls()</code>. The convention only dictates that the name of the control element(s) must begin with the value of <code>$question->name_prefix</code>. The <code>$question->name_prefix</code> is a string starting with "resp" followed by the question id and an underscore, e.g. <code>resp56_</code>. In the default case, when there is only a single control element (this includes the case of a list of equally named radio buttons), no postfix is appended to the name prefix. For questiontypes that allow or require multiple form elements, an arbitrary string can be appended to the name prefix to form the name of these form elements. The postfix must not include any relational data (i.e. ids of records in the quiz_answers table), because this can lead to problems with regrading of versioned questions.

After the printing of the question the server only sees it again when it is submitted. So the submitted data will contain several values indexed by strings starting with <code>respXX_</code>. Upon submission, the function <code>quiz_process_responses()</code> is called, which assigns the submitted responses to the state of the question with id XX, using the postfix (i.e. everything after the underscore) as array keys. In the default case with only one control element the name only consists of the name prefix. This explains why the default index of the <code>$state->responses</code> array is the empty string. The value of each array element is obviously the value that was submitted by the form, basically a raw response.

The function <code>quiz_process_responses()</code> in turn calls the questiontype specific method <code>grade_responses()</code> to assign a grade to the submitted responses and <code>compare_responses()</code> to determine whether the response was identical to the previous submission and to avoid regrading the same responses repeatedly. These questiontype specific functions need to be aware of the expected keys of the <code>$state->responses</code> array.

Finally, the methods <code>restore_session_and_responses()</code> and <code>save_session_and_responses()</code> also need to know the questiontype specific layout of the <code>$state->responses array</code> and restore or save the information, e.g. by converting from or to the data representation.

==Question types==
{{Questiontype developer docs}}
The quiz module is itself modular and allows question type plug-ins. For each question type there should be a page, accessible via the menu at the right, which provides at least the dtails about
*Database tables
*Response storage
*Question options object
*State options object

It is hoped that Moodlers will contribute a lot of non-core question types in the future. For this it would be good to start a [[Guide to question type plugins]].

==Grades==

The handling of grades is a bit complicated because there are so many different grades around that get rescaled and combined in various ways. This section should summarize how this is done and why.

The following grade fields are being used:
*$question->defaultgrade
::This is the default value for the maximum grade for this question. This is set up when the teacher creates the question and it is stored in an int(10) field in the [[Quiz database structure#quiz_questions|quiz_questions]] table. However when the question is actually used in a particular quiz the teacher can overrule this default and this is stored in:
*$question->maxgrade
::This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in an int(10) field in the [[Quiz database structure#quiz_question_instances|quiz_question_instances table]].
*$question->penalty

*$state->raw_grade
*$state->grade
*$state->penalty
*$state->sumpenalty

*$attempt->sumgrades

The maximum grades set by the teacher, $question->defaultgrade and $question->maxgrade, are integers. All student-obtained grades are in principle floating point numbers. For historical reasons they are stored in the database as varchar(10) fields. Care has to be taken when writing to the database to make sure all grades are correctly rounded and squeezed into a string of no more than 10 characters, otherwise the writing to database will fail, see bug 4220.

The final outcome of the calculation of the grade for a user at a particular quiz is stored in the 'grade' field of the [[Quiz database structure#quiz_grades|quiz_grades table]]. This field has type double.

==Penalty mechanism==

===What it is for===

When the quiz is run in adaptive mode the student can interact with a question repeatedly. So in particular the student can try again when he gets a wrong answer. Clearly the final mark for the question must reflect the fact that the student did not get it right originally. Therefore a penalty is subtracted from the final mark.

===How the penalty is determined===

First of all penalties are relevant only if a quiz is run in adaptive mode. Only in this case can a student have a second attempt and therefore only in this mode can there be any occasion to subtract a penalty.

Even in adaptive mode the penalty mechanism is only used when it is selected in the quiz options. If "Apply penalties" is set to "No" then the final mark for the question is the mark for the last graded response.

Each question has a 'penalty' field (which should really be called 'penaltyfactor') which is a number between 0 and 1. The penalty for a wrong response is calculated as the product ($quiz->penalty * $quiz->grade), i.e., as the product of the penaltyfactor with the maximum achievable grade for the question. This product is stored in $state->penalty. So $quiz->penalty is the fraction of the maximum grade that is subtracted as a penalty for each wrong response.

The $quiz->penalty field has a default value of 0.1, both in the database and in mod/quiz/defaults.php. This default can of course be overwritten by the admin on the quiz configuration page. This admin-selected default is (as usual for admin defaults) stored in $CFG->quiz_penalty. The teacher can choose a different penalty factor for each individual question when adding or editing a question.

Now if a student makes repeated wrong attempts (or partially correct attempts) the penalties for all these attempts are added up in $state->sumpenalties. The mark for the question is then calculated as the mark for the last graded response minus the sum of the penalties.

One curious fact about $state->sumpenalties is that, for efficiency reasons, it is not stored in the quiz_states table but instead in the 'sumpenalty' field of the quiz_newest_states table. That way it only has to be stored once per attempt rather than once per response.

===Where it is done in the code===

The function quiz_apply_penalty_and_timelimit() subtracts the penalty in $state->sumpenalty from the raw grade in $state->raw_grade to obtain $state->grade for the response. However it is ensured that the grade of a new attempt at the question never falls below the previously achieved grade. This function also increases $state->sumpenalty by the amount in $state->penalty. The assumption is that $state->penalty has just been set appropriately by the code calling this function, e.g., quiz_process_responses.

==Time limit==

A quiz can have a time limit. This is stored in minutes in $quiz->timelimit. So before using this in time calculations it always has to be multiplied by 60 to turn it into seconds like all other timestamps in moodle and php. If $quiz->timelimit is zero it means there is no timelimit.

If a student asks to start an attempt on view.php for a quiz with a timelimit then he is shown a javascript message alerting him to the timelimit and is asked to confirm.

For quizzes with timelimit attempt.php shows a javascript timer that counts down and automatically submits and closes the attempt when the time is up.

Confusingly there are two javascript timers in the quiz module. jsclock.php provides a countdown in the title bar that counts down to the quiz closing time if this is less than a day away. This has nothing to do with the timelimit. jstimer.php provides the countdown timer that implements the timelimit. It in turn uses timer.js.

The time a response was submitted by the student is recorded by attempt.php right at the top of the page and is then passed on to quiz_process_responses in $action->timestamp. This puts it into $state->timestamp. Finally, after the responses have been graded, the function quiz_apply_penalty_and_timelimit() checks that the responses are within the timelimit to within 5% and if not it sets the grade to zero (or the previously obtained grade, if that is higher).

==Pagination==

Quiz attempts can be paginated, i.e., spread over several pages. The student can navigate between the pages using the standard Moodle paging bar. When the student navigates to a different quiz page the answers on the current page are automatically submitted for saving (but not grading).

To do this automatic submission the paging bar needs some javascript. It is therefore not produced with Moodle's standard print_paging_bar() function from weblib.php but with quiz_print_navigation_panel() which is defined in mod/quiz/locallib.php and produces something that looks the same.

The teacher has complete control via the edit interface on edit.php over where the page breaks should occur. He can repaginate the quiz with any chosen number of questions per page. He can also move the page-breaks up and down using the arrows.

Internally page breaks are stored in the $quiz->questions field (which now should really be called $quiz->layout). This field contains a comma separated list of questionids and pagebreaks where the pagebreaks are represented by the id 0. For example 23,12,0,11, 0 means that the two questions with ids 23 and 12 are on the first page and the question with id 11 is on the second page. The last page break is invisible and Moodle sometimes puts it there itself for its own convenience.

Because the quiz has an option $quiz->shufflequestions to shuffle questions the layout that the student sees in a particular attempt does not necessarily have to be the same as that stored in $quiz->questions. Therefore each attempt has its own $attemp->layout field. If $quiz->shufflequestions is false then this just contains a copy of $quiz->questions but if it is true then during the creation of a new attempt by quiz_create_attempt() the function quiz_repaginate() is used to produce a layout with $quiz->questionsperpage number of questions per page that are randomly ordered.

Both attempt.php and review.php use the $attempt->layout field to determine what questions to show on a particular page. That way we can guarantee that the student will, for a particular attempt, always see the questions in the same order and with the same pagination, both while attempting and during review. Also a teacher when reviewing a student's attempt sees the pages the same way they were shown to the student. However the teacher is also given the option to see all questions on one page.

There are some functions in locallib.php dedicated to handling the layout fields: quiz_questions_on_page(), quiz_questions_in_quiz(), quiz_number_of_pages(), quiz_first_questionnumber(), quiz_repaginate(). They are very short functions. The function quiz_first_questionnumber() that determines the number of the first question on a particular page makes use of the $question->length field. To allow this calculation to be fast is the main reason why that field is in the question table even though it could also be determined easily from the question type.

==Question versioning==

'''Note:''' Question versioning is currently disabled until it is re-developed to fix all reported issues.

When questions that were already attempted by a student are edited, it can be important to keep a copy of the question as it was before editing in order to reconstruct the quiz as it was seen by the student. To provide this functionality a question versioning mechanism was implemented.

The first goal, namely keeping around old questions, is easily achieved. They are just not deleted any more. However, this is not enough; it is also necessary to store which questions are versions of others. To achieve this goal, there is an additional table, which stores the versioning information: quiz_question_versions.

When a question is replaced for which there are already student attempts then all the attempt data gets associated to the new version of the question and is re-graded. This requires the question ids in the quiz_attempts, quiz_states and quiz_newest_states tables to be replaced by the new id. However we do also want to be able to reconstruct the quiz the way the student saw it when he gave his answers. For that purpose the id of the original question is always preserved in the 'originalquestion' field of the quiz_states table.

If all old versions of questions are kept around this could horribly clutter the editing interface. Therefore a field called hidden was added to the quiz_questions table and all old versions of edited questions are automatically hidden. When this flag is set to 1 the question is not displayed in the list of available questions, unless the user chooses to show them.

While the mechanism above should work as described, there is some additional complexity in order to minimise the number of versions created. If a question is created and has not been attempted by a student yet (this excludes teacher previews of the individual question and the quiz!), the database record will be reused (i.e. overwritten) and no new version will be created. This is especially important when the question is created and the first 2 or 3 mistakes are only noticed during preview.

On the editing screen for questions an additional set of options was introduced (see image).
Replacement Options
It shows which quizzes use the edited question and how many students have attempted it in a particular quiz. Based on this information it is then possible to choose in which quizzes the new version of the question should be used and in which ones the old one should remain.

By default the 'replace' checkbox for all quizzes that don't have any students' attempts are checked and in addition, if the question is edited out of a quiz context (i.e. not in the category question list), the 'replace' option is checked for that quiz as well.

===Database===

The changes to the database structure are limited to an added field (hidden) in the quiz_questions table and an additional table called quiz_question_versions. However, dealing with the quiz_questions table has become slightly more complicated.

The hidden field in the quiz_questions table has no implications for the core functionality. It is only used to determine, as the name implies, whether the question is shown in the category list or not.

The table quiz_question_versions stores information about the actual change. This information includes the ids of the old question and the new question, the id of the user who did the change and a timestamp. Quite importantly, the id of the quiz, in which the question was replaced is also stored. This means that the versions table provides a history of the different states the quiz went through until it was edited to be at the current state. The information allows to recreate a quiz as it was at any point in time (from a data perspective - this possibility is not used extensively by the code).

===Adjustments to the Data===

When a question is replaced by a newer version, database records are updated in the order shown below (compare with question.php):

* First a new record is inserted into the quiz_question_versions table for each affected quiz (i.e. each quiz in which the question was replaced).
* Then, for each affected quiz, the comma separated list of question ids in the question field is updated by replacing the old question id with the new one.
* In the quiz_question_instances table the record that links the old question to the quiz is also updated to point to the new question.
* In all attempts belonging to the old question the comma-separated list of question ids in the layout field are changed by replacing the old id by the new one.
* All states belonging to the old question are made to belong to the new version by changing the id in the 'question' field. However if we are replacing the original question then the id of this original version is stored in the originalquestion field.
* We have to change the questionid field in quiz_newest_states.
* Finally we have to do any question-type specific changes. For example question types that store student responses by storing the id of the answer in the quiz_answers table will have to recode these ids in all the states to point to the corresponding answers in the new version. This is handled by the function replace_question_in_attempts() in the question type class.

===Affected Code and Functionality===

Note: This section should still be considered under construction until the question mark behind bug #3311 is taken off.

In the file review.php and potentially also in the file attempt.php, if a question is edited during a student's attempt, the data from quiz_question_versions needs to be taken into account. If a student has attempted a quiz and a question was changed afterwards (i.e. a new version of that question was created), the question id of the old version remains in the comma separated list inside the attempt->layout field. However, since the records in the quiz_question_instances table get updated, we need to go forward in the question history, by looping through entries from the quiz_question_versions table, to find out the id of the question version that is currently used in the quiz.

Suggestion: With a fairly simple change to the convention of what is stored in the quiz_question_versions table we could get rid of the requirement of looping through all the versions. If in the newquestion field we store the id of the question that is currently used in the quiz, it would be possible to get the complete history for a question quite simply by selecting by quiz id and newquestion.

It should be fairly simple to write an upgrade script for this change. Additionally, another set_field would need to be added to question.php to change the newquestion field to the new question id. The benefits would be a much simpler handling of the question history, resulting in more efficient code than the current fix for bug #3311 in review.php.

The place where all the versioning actually takes place is question.php. Here the changes described in Adjustments to the Data are carried out.

Obviously the backup and restore scripts also take quiz_question_versions into account, however, they don't need to be concerned with the ways the data is used.

==Changes for Moodle 1.5: adaptive questions==

During the first half of 2005 the quiz module code has undergone a considerable rewrite to allow for adaptive questions in which a question session can consist of several sequential student responses. The question can adapt itself to the student answers. For example in response to certain answers the question could provide feedback or hints and then ask the student to answer again or give the student a simpler or related question.

Unfortunately many changes had to be made to the question type methods. This has however resulted in improved efficiency and has made the writing of question types easier. It also allows question types with more powerful features and has fixed some bugs / annoying behaviour.

For details see:
*[[Quiz rewrite|Quiz module rewrite]]
*[[Quiz conversion|How to convert existing question types]]

Of course there were countless other changes to the quiz module going from Moodle 1.4 to 1.5, especially to the teacher interface. However in spite of the fact that these changes are a lot more visible they were much less drastic from the point of view of the code. Here is a very incomplete list of changes:

* New quiz results overview page
* Reform of the quiz edit page: Changes on the quiz edit page are saved straightaway, not only after Save button is pressed.
* Copying questions: The teacher can create a new question using a previous one as template.
* Moving questions: The teacher can now move selected questions to a different category.
* Re-marking after question editing: if a teacher corrects a question that students have already attempted the teacher can request a remark.
* Teacher preview tab.
* Detailed teacher control over what students can see during review.

==Changes for Moodle 1.6: separating questions from quizzes==

The quiz module is not the only activity module in Moodle that uses questions. The lesson does too and potentially questions could be useful in many modules. Therefore we have started to rewrite some of the quiz module functions and move them from locallib.php to questionlib.php so that eventually they could be moved into a central library and be used by other modules.

Module developers who want to use the
quiz module questions in their own module should take a look at the simple questiondemo module that you can find in CVS at [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/questiondemo contrib/questiondemo]. The idea is that it will be simpler
to understand this demonstration module than the code in the quiz module which
is very complicated due to the many options and features. The interesting code in the questiondemo module is in view.php. There you can see how to
both render and score questions. This module requires the version of the quiz module from Moodle 1.6dev or later.

The details of the changes are explained on the page [[Separating questions from quizzes]].

==Future plans==

The features below are in no particular order:

* Editing questions: This is about editing questions after students have already attempted them. There needs to be a mechanism to keep the old versions of the question around for auditing purposes.
* New quiz statistics pages?: These pages should be built by using functions defined by the individual question types.
* Manual grade override: Teachers should be able to override the automatically calculated grades and should be able to make comments.
* Off-line questions: The answers to these are handed in off-line in the conventional way (e.g., on paper) and teachers enter marks on Moodle.
* Batch printing of quiz sheets: We want to be able to hand out question sheets to students so they can start working on the questions before going to the computer.
* Question preview from question edit page: so the teacher can try the question already before saving the changes.
* Show table of questions on view.php: gives teachers and students a bit of an overview of the quiz.
* Extending deadlines for individual students: for example when a student misses a deadline for good reasons.
* Filtering questions by quiz and by search: More ways to restrict which questions are shown on the quiz editing page.
* Re-open quizzes for revision: After the due date has passed the quiz could allow practice attempts.

[[Category:Developer]]
[[Category:Quiz]]

Development:RQP question type

2006-02-07T00:18:37Z

Gustav: /* Database tables */

{{Questiontype developer docs}}

==Database tables==

===quiz_rqp===

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
;type :int(10) unsigned NOT NULL default '0',
;source :longblob NOT NULL default '',
;format :varchar(255) NOT NULL default '',
;flags :tinyint(3) unsigned NOT NULL default '0',
;maxscore :int(10) unsigned NOT NULL default '1',

===quiz_rqp_servers===

;id :int(10) unsigned NOT NULL auto_increment,
;typeid :int(10) unsigned NOT NULL default '0',
;url :varchar(255) NOT NULL default '',
;can_render :tinyint(2) unsigned NOT NULL default '0',
;can_author :tinyint(2) unsigned NOT NULL default '0',

===quiz_rqp_states===

;id :int(10) unsigned NOT NULL auto_increment,
;stateid :int(10) unsigned NOT NULL default '0',
;responses :text NOT NULL default '',
;persistent_data :text NOT NULL default '',
;template_vars :text NOT NULL default '',

===quiz_rqp_types===

;id int(10) :unsigned NOT NULL auto_increment,
;name :varchar(255) NOT NULL default '',

==Response storage==

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Development:Dataset dependent

2006-02-07T00:11:49Z

Gustav: /* quiz_dataset_items */

{{Questiontype developer docs}}

==Database tables==

===quiz_dataset_definitions===
This table is an indirect extension to the quiz_questions table, because the quiz_question_datasets table can link a question to one or more datasets. Each dataset represents a variable, that is used either in the questiontext or in the answer to a dataset dependent question.

;id :int(10) unsigned NOT NULL auto_increment,
;category :int(10) unsigned NOT NULL default '0',
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
;itemcount :int(10) unsigned NOT NULL default '0',

===quiz_dataset_items===

Dataset items can be created for each dataset. The quiz_dataset_items table stores these possible values for the variables defined in the quiz_dataset_definitions table.

;id :int(10) unsigned NOT NULL auto_increment,
;definition :int(10) unsigned NOT NULL default '0',
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===quiz_question_datasets===

The quiz_question_datasets table is used by dataset dependent questionypes (i.e. calculated) to link datasets to questions.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
;datasetdefinition :int(10) unsigned NOT NULL default '0',

==Response storage==

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Development:Dataset dependent

2006-02-07T00:09:32Z

Gustav: /* quiz_dataset_definitions */

{{Questiontype developer docs}}

==Database tables==

===quiz_dataset_definitions===
This table is an indirect extension to the quiz_questions table, because the quiz_question_datasets table can link a question to one or more datasets. Each dataset represents a variable, that is used either in the questiontext or in the answer to a dataset dependent question.

;id :int(10) unsigned NOT NULL auto_increment,
;category :int(10) unsigned NOT NULL default '0',
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
;itemcount :int(10) unsigned NOT NULL default '0',

===quiz_dataset_items===

Dataset items can be created for each dataset. The quiz_dataset_items table stores these possible values for the variables defined in the quiz_dataset_definitions table.

===quiz_question_datasets===

The quiz_question_datasets table is used by dataset dependent questionypes (i.e. calculated) to link datasets to questions.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
;datasetdefinition :int(10) unsigned NOT NULL default '0',

==Response storage==

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Development:Dataset dependent

2006-02-07T00:07:03Z

Gustav: /* quiz_question_datasets */

Development:Numerical question type

2006-02-06T23:59:07Z

Gustav: /* Database tables */

{{Questiontype developer docs}}

==Database tables==

===quiz_numerical===

The quiz_numerical table is an extension of the quiz_answers table, defining a tolerance value for each answer.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
;answer :int(10) unsigned NOT NULL default '0',
;tolerance :varchar(255) NOT NULL default '0.0',

===quiz_numerical_units===

The quiz_numerical_units table is used by the numerical questiontype and the calculated questionype. It extends the quiz_questions table, defining an arbitrary number of units that can be used in the responses.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
;multiplier :decimal(40,20) NOT NULL default '1.00000000000000000000',
;unit :varchar(50) NOT NULL default '',

==Response storage==

The numerical questiontype, which inherits the function print_question_formulation_and_controls() from the shortanswer questiontype, has only one response field, so its responses are handled by the default questiontype. The response is stored without any modifications in the answer field of the table quiz_states.

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz database structure

2006-02-06T23:58:13Z

Gustav: moved numerical tables to the numerical questiontype

{{Quiz developer docs}}The quiz data model has a fairly large pool of database tables, so the first step in explaining them is to provide some order. Conceptually it is possible to distinguish between the tables holding the teacher-supplied data, defining quizzes and questions, and the tables storing all the data that is generated when students interact with the quizzes and questions.

A further simplification is possible by separating out the questiontype specific tables. They are logical extensions to other tables and therefore are not necessary for understanding the general basic model. They are therefore explained on the developer documentation page for the individual [[Quiz developer docs#Question types|question types]].

The diagram below shows how the most important tables are linked to one another.

[[image:Quiz_database_tables.gif]]

==Teacher-supplied data==

===quiz===

The quiz table contains the definition for all the quizzes. Each quiz belongs to a course, reflected by the course id, has a name and a short descriptive text (intro), an opening and a closing time and several fields that store the settings of various quiz options, each of which is explained in the quiz help that is linked to from the quiz settings page.

The only field that requires additional information is the optionsflag, which... I will put an explanation here eventually --[[User:Gustav|Gustav]] 06:02, 5 February 2006 (WST)

For quizzes that contain random questions the $quiz object may acquire an additional property
;questionsinuse
:A comma separated list of questions that are being used in the quiz. This is used by the random questiontype to avoid choosing a question that is already being used.

===quiz_questions===

This table constitutes the item or question bank, i.e. the repository of defined questions. The quiz_questions table defines the data that is common to questions of all types.

;id
:int(10) NOT NULL auto_increment,
:Primary key. This is used as a foreign key in many other tables. for example the quiz_answers table allows to define an arbitrary number of answers that are part of the question. And many questiontypes have their own tables that hold more information about the question.

;category
:int(10) NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_categories|quiz_categories]]

;parent
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. This field is set to zero except in the case of wrapped questions as they are used for example in the multianswer questiontype. When a question wraps around any number of subquestions the subquestions will have their parent id field set to the id of the main question, thus allowing the question to find all its sub-questions (or wrapped questions). If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself. This is also used for hiding random questions from the question list. Their parent field is simply set to their own id.

;name
:varchar(255) NOT NULL default '',
:Question name that is used in question lists on the quiz editing pages

;questiontext
:text NOT NULL,
:Main text of the question

;questiontextformat
:tinyint(2) NOT NULL default '0',

;image
:varchar(255) NOT NULL default '',

;defaultgrade
:int(10) unsigned NOT NULL default '1',
:Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.

;penalty
:float NOT NULL default '0.1',
:The penalty that is applied (if the respective quiz option is set) for an incorrect attempt at the question.

;qtype
:smallint(6) NOT NULL default '0',
:The questiontype of the question. (Constants are defined in locallib.php)

;length
:int(10) unsigned NOT NULL default '1',
:This defines how many question numbers are required for this question. It is generally set to "1", but the description questiontype, for example, sets it to "0", reflecting the fact that it doesn't have a question number.

;stamp
:varchar(255) NOT NULL default '',
:Unique identifier

;version
:int(10) NOT NULL default '1',
:A number representing how often the question was edited.

;hidden
:int(1) unsigned NOT NULL default '0',
:Controls whether to display a question in the question bank list in edit.php. Hiding questions is a mechanism to "delete" questions without removing them from the database and thus to allow them to be restored or "unhidden" at a later stage. Also the (unfinished and disabled) [[Quiz_developer_docs#Question_versioning|versioning feature]] uses the hidden field to prevent older versions of a question from cluttering the user interface.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of the static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these later fields can differ when a question is used in different quizzes.

The runtime fields are added to question objects with the function <code>quiz_get_questions_options()</code> is called. This in turn calls the questiontype specific <code>get_question_options()</code> method for to add the options field.

;maxgrade
:This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in the [[#quiz_question_instances|quiz_question_instances table]].

;instance
:Foreign key: refers to an id in the table [[#quiz_question_instances|quiz_question_instances]]

;options
:Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the <code>get_question_options</code> method.

;name_prefix
:The prefix to be used on all interactions printed as part of the question.

We now deal in alphabetical order with the remaining tables for the teacher-provided data.

===quiz_answers===

This table allows a common way to store one or more teacher-defined answers for each question. It is not mandatory for a questiontype to make use of this table however. A questiontype may choose to store it's teacher-defined answers in an entirely different way, or even to do away with teacher-defined answers and use some other method to mark the student-supplied answer. For example it could calculate the correct answer on the fly.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to [[#quiz_questions|quiz_questions]] table.

;answer
:text NOT NULL,
:The string that represents the teacher-defined answer that will be compared to the student responses for grading and feedback purposes. The format of this field is entirely up to the question type.

;fraction
:varchar(10) NOT NULL default '0.0',
:The fraction of the total mark that the student should earn for giving this particular answer. This could be a negative number for wrong answers. Note that it is stored in a varchar(10) field.

;feedback
:text NOT NULL,
:Text that can be displayed to student as feedback when the student's responses match this particular answer.

In the past there was also a sequence number field was sometimes used to store the order of the different answers and was set to '0' if the order was of no importance.

===quiz_categories===

Categories are provided as a way to organize questions. Each category has a name and a descriptive text (info) and the sortorder as metadata. Categories allow hierarchical nesting via the parent id and can be private or published, i.e. they can be made available to teachers in other courses.

Since categories are simply a means for organising questions they are not vital for understanding how the quiz module works.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;course
:int(10) unsigned NOT NULL default '0',
:Foreign key to the course table

;name
varchar(255) NOT NULL default '',

;info
:text NOT NULL,

;publish
:tinyint(4) NOT NULL default '0',

;stamp
:varchar(255) NOT NULL default '',

;parent int(10)
:unsigned NOT NULL default '0',

;sortorder int(10)
:unsigned NOT NULL default '999',

===quiz_question_instances===

Questions can be assigned different grades in different quizzes. These are stored in this table.

While, after a small extension, this table could also fulfill the purpose of storing the order of the questions in a quiz, this is currently still done in the questions field in the [[#quiz|quiz]] table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz|quiz]] table.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz_questions|quiz_questions]] table.

;grade
:smallint(6) NOT NULL default '0',
:The maximum grade assigned to this question in this quiz. This grade was set by the teacher on the [[mod/quiz/edit|quiz editing page]]. At runtime this information is stored in the $question->maxgrade field.

===quiz_question_versions===

This feature is not finished and disabled. The table structure may still change. See [[Quiz developer docs#Question versioning]] for a discussion.

;id
:int(10) unsigned NOT NULL auto_increment,

;quiz
:int(10) unsigned NOT NULL default '0',

;oldquestion
:int(10) unsigned NOT NULL default '0',

;newquestion
:int(10) unsigned NOT NULL default '0',

;userid
:int(10) unsigned NOT NULL default '0',

;timestamp
:int(10) unsigned NOT NULL default '0',

==Student-created data==

===quiz_attempts===

In the quiz_attempts table a record is created each time a user starts an attempt at a quiz. This is one of the important tables and the corresponding $attempt object is passed between many of the quiz module functions and methods.

;quiz
:int(10) unsigned NOT NULL default '0',<br />The id of the quiz that is attempted
;userid
:int(10) unsigned NOT NULL default '0',<br />The id of the user who is attempting the quiz
;attempt
:smallint(6) NOT NULL default '0',<br>It is possible for a user to attempt a quiz several times, therefore the number of the attempt is stored in this field.
;sumgrades
:varchar(10) NOT NULL default '0.0',<br>The (unscaled) grade for the attempt, i.e. if the grades assigned to the questions add up to 8, but the maximum grade for the quiz is set to 10, then the sumgrades field can contain 8 at maximum.
;timestart
:int(10) unsigned NOT NULL default '0',<br>The timestart field is set to the current time when an attempt is started and is never changed afterwards.
;timefinish
:int(10) unsigned NOT NULL default '0',<br>The timefinish field is set to "0" initially and to the current time when the attempt is closed. This is exploited at several places in the code to determine whether an attempt has been closed or not (i.e. closed = timefinish > 0). For all other modifications of an attempt record the timemodified field should be changed as well.
;timemodified
:int(10) unsigned NOT NULL default '0',<br>This should be changed each time data in the record is modified.
;layout
:text NOT NULL,<br>a comma separated list of question ids, with a "0" denoting a page break. Usually the comma separated list ends with ",0".
;preview
:tinyint(3) unsigned NOT NULL default '0',<br>A flag that marks a teacher preview (i.e. an attempt by a user with teacher privileges) that may be automatically deleted when the quiz is previewed again, and which is not taken into account when viewing statistics.

===quiz_states===

States are saved for each interaction with a question. This allows a review of the complete history of a user's interactions with individual questions. The current state is the most important object used by the quiz module runtime code. This $state runtime object has a few additional fields not in the database that will be explained further down. The database fields are:

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;attempt
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_attempts|quiz_attempts]]

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. The attempt id and the question id together sufficiently identify a question instance that a state belongs to.

;originalquestion
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table quiz_questions. It identifies which question was in use when the student attempted the question. This is part of the [[Quiz_developer_docs#Question_versioning|question versioning]] code.

;seq_number
:int(6) unsigned NOT NULL default '0',
:A counter that provides information about the sequence in which the states were created.

;answer
:text NOT NULL,
:This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses. Questiontypes are allowed to deviate from this and handle their response storage in any desired way. Some questiontypes do not use this field but instead store the student response in their own table extending this table.

;timestamp
:int(10) unsigned NOT NULL default '0',
:A timestamp to record when the state was created. This could mainly be useful for audit purposes.

;event
:int(4) unsigned NOT NULL default '0',
:Records the event or interaction type that lead from the previouse state to the current one. The field can take the value of any of the following constants (defined in locallib.php):
:*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.

;grade
:varchar(10) NOT NULL default '0.0',
:Calculated from the raw grade by deducting the penalty and rescaling to the defaultgrade value of the question. Note that this is a varchar(10) field like most grade-related fields in the quiz module.

;raw_grade
:varchar(10) NOT NULL default '',
:The grade that was achieved for the question scaled to the question's weight or grade as assigned in the quiz_question_instances table

;penalty
:varchar(10) NOT NULL default '0.0',
:The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous marking events.

In addition to the database fields a few fields are added to the states at runtime. They are dealt with by the questiontypes with the methods <code>create_session_and_responses</code>, <code>restore_session_and_responses</code> and <code>save_session_and_responses</code> and are defined as follows.

;sumpenalty
:The cumulative penalty, which can be calculated by adding up all the penalties from previous marking events. For efficiency these cumulative penalties are stored in the table [[#quiz_newest_states|quiz_newest_states]] so that they do not need to be re-calculated each time.

;changed
:This records whether a change has taken place to the runtime state. This is set to false when the state is restored from the database. Any code which changes the question state must set this field to true amd must increment seq_number. The <code>quiz_save_question_session()</code> function will save the new state object to the database if the field is set to true.

;responses
:This is automatically set to the value of the database field <code>answer</code> before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indicies are determined by the name of the elements after the name_prefix is stripped.

;last_graded
:This field contains another state object representing the most recent graded state in the history of this question attempt. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.

;options
:Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

We now deal in alphabetical order with the remaining tables holding the student-created data.

===quiz_grades===

The quiz_grades table merely stores a student's awarded grade for a quiz. Since it is possible to allow several attempts on a quiz, the grade stored is calculated depending on the quiz setting grademethod. This table exists mainly for convenience, because the values of its fields can be recalculated.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the [[#quiz|quiz]] table

;userid
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the user table

;grade
:double NOT NULL default '0',
:The grade awarded for this quiz to this user

;timemodified
:int(10) unsigned NOT NULL default '0',
:Unix timestamp to be updated each time the grade is changed

===quiz_newest_states===

This table exists only for efficiency reasons:
#Via its 'newest' and 'newgraded' fields it gives attempt.php a way to quickly find the newest state and the newest graded state for an attempt. It allows the construction of SQL to select all the states that need to be loaded on attempt.php or review.php.
#Via its 'sumpenalty' field it gives quiz_apply_penalty() a quick way for getting at the accumulated penalty that needs to be applied. Without this field the penalties from all previous graded states would have to be added up each time. Not a big deal actually because this could be achieved with a single SQL query (using SUM) but this field was introduced when we still had the multiplicative penalty scheme around which would have been more difficult to recompute.

This table was introduced in Moodle 1.5 and is not populated for all states during the upgrade because on sites with a lot of existing states that could take too long. Rather it is done whenever needed by quiz_upgrade_states().

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;attemptid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_attempts|quiz_attempts]] table

;questionid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_questions|quiz_questions]] table

;newest
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state for this attempt and this question.

;newgraded
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state created by a grading event.

;sumpenalty
:varchar(10) NOT NULL default '0.0',
This stores the total penalty that this user has accumulated over previous graded responses to this question in this attempt.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz

2006-02-06T23:00:03Z

Gustav: /* Answers */ commented on misnamed answer field in states table

{{Quiz developer docs}}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. This page aims to collect useful documentation on how the module works.

==Terminology==

When talking about the quiz module there are certain terms that can cause confusion because they can be used with different meanings. In Moodle we have adopted a certain terminology that will be explained below.

===Questions===

A '''question''' in the context of the quiz module is the set of definitions (question name, question text, possible answers, grading rules, feedback, etc.) that constitute a reusable assessment item. So it is much more than what one would in everyday language understand under a question and which in Moodle is just on field (the questiontext field) of the question object.

What in Moodle we refer to as a 'question' is what in the terminology of the QTI specification ismore appropriately called an '''assessment item''' or just 'item' for short.

There are different types of questions, like for example multiple-choice questions or numerical questions. These are referred to as '''[[Quiz developer docs#Question types|question types]]''' in Moodle.

Since version 1.5 Moodle is able to handle so-called '''[[Adaptive questions]]''', also known as 'adaptive items' in QTI speak. These are qustions that walk the user through a directed graph of question states depending on the user's responses. For example 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. Quizzes can be run in 'adaptive mode', which provides buttons to mark each question individually.

===Answers===

In Moodle the term ''''answer'''' is used exclusively for the '''teacher-defined answers''' of a question. When talking about the quiz module it is easy to get confused between these teacher-defined answers and the answers that the students actually give. We have therefore adopted the convention to refer to the student-supplied answers as 'responses' and to reserve the term 'answers' to apply to teacher-defined answers. In question types that rely on teacher-supplied answers these are used in the grading process by comparing them with the student responses. Of course not all question types use teacher-defined answers but use some more intelligent way to process the student responses.

Perhaps one should also stress that 'answer' is not always used in the sense of 'correct answer'. For example every choice in a multiple-choice question is referred to as an answer. Other systems use the term 'distractor' for wrong answers.

In Moodle we always use the term ''''responses'''' to refer to the students' responses to a question because term 'answers' that one might also be tempted to use for this is already used to refer to the teacher-defined answers, see above. This term is always used in plural, although for some questiontypes there is only one possible response.

There is unfortunately, for historical reasons, one exception to the above rule: The [[Quiz database structure#quiz_states|quiz_states table]] has a field 'answer' whose purpose it actually is to hold the student's responses.

===Attempts===

In Moodle 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 ''''attempts at a question'''', never just as 'attempts'.

Because a student can have several attempts at a question within the same attempt at the quiz, there is a lot of data that needs to be stored as the student takes the question through several ''''states'''' by repeated interactions with the question. A state object holds the most recent state of the question and whenever a student submits a response or a similar ''''event'''' occurs, the question goes to a new state. The complete history of question states that the question is taken through is saved and this is referred to as the question ''''session''''. Usually only the most recent state and the last graded state are of interest though.

==Code documentation==

The code is documented according to phpdoc conventions. The explanations here in the wiki are meant to complement this.

Inline comments should be used liberally in the code. The following conventions make it easier to search for comments with special meaning:
* use TODO in comments about things that need to be done
* use ??? in comments that are questions about the code

There are three function libraries:

;questionlib.php
:All functions that need to be available to any module wanting to use questions. This is New in Moodle 1.6, in Moodle 1.5 this was part of locallib.php. This instantiates all questiontype classes by loading the questiontype.php files

;lib.php
:All the functions that are sometimes called by the Moodle core. This loads constants from '''constants.php'''

;locallib.php
:All functions that are used only by the quiz module. This loads lib.php and questionlib.php

The default questiontype class is defined in '''questiontypes/questiontype.php'''. The individual questiontypes extend this class in their own questiontype.php file. For documentation of the questiontype classes one should often look at the documentation of the default question type because much of the documentation that is in the default class is not repeated in the other questiontype classes

Constants are defined in .

While questiontypes are realized as classes, the quiz module is not written in a truly object-oriented way. Instead it follows the Moodle model of using objects mostly only as alternatives to arrays to hold database records. So none of the quiz, question, attempt, and state objects that play a central role in the module have any methods. Only the questiontype objects have methods. Strangely enough the quiz module instantiates on object of each questiontype class at the start and then reuses their methods for the different questions. If one is used to the Moodle way of programming then this is easy enough to handle.

==Objects and data structures==

Key to understanding how the quiz module works is to understand the different kinds of object work together. The most important ones are:

*Quizzes
*Questions
*Attempts
*States

Quizzes and Questions are data created by the teacher when setting up and editing a quiz. Attempts and States are data created by the student when interacting with a quiz.

Moodle allows students to make several attempts at a quiz. Data about such an attempt is stored in an attempt object. This holds for example how the quiz was randomized for this attempt and the ordering of the questions and answers. So attempts are indexed by user id and quiz id.

Moodle allows students to interact repeatedly with a single question. So for example the student might initially just save an answer, later mark it, then correct it if it was marked incorrect. Each time the student interacts with a particular question inside a particular attempt at a quiz a new state is created. So states are indexed by user id, attempt id and question id.

===Database structure===
All this data needs to be kept in Moodle's database. How this is achieved is explained on a separate page about the '''[[Quiz database structure]]''', which also contains a useful diagram.

As is customary in Moodle, most runtime objects simply represent the data from a particular database record. So for example a $quiz object has fields corresponding to all the fields in the [[Quiz database structure#quiz|quiz table]]. In some cases the objects have some additional fields that are added at runtime. This is particularly the case for $question and $state objects. These additional fields are also described on the page about the '''[[Quiz database structure]]'''. Many functions that are used to process these objects make use of the additional fields and it is therefore necessary to use the correct functions for creating these objects.

===Runtime objects===
Some objects used by the quiz module are purely runtime object and do not correspond to a database table. The structure of these objects is explained in detail on a separate page about the '''[[Quiz runtime objects]]'''.

The main script of the quiz module is attempt.php which will have to deal with all these objects. Studying the '''[[Quiz attempt|explanation of attempt.php]]''' is therefore a good way to start to study the quiz module code.

==Response storage==

The student's responses to a question are stored in <code>$state->responses</code>. Questiontypes are completely free to implement the storage mechanism of their responses (and other state information) the way they want. Still, the standard questiontypes all follow a similar model. The default storage model and the questiontype specific variations are explained below.

The flexibility for the questiontypes to choose their response storage mechanism freely and to convert from the storage model to the runtime model is provided by a set of three functions, which allow to initialise the runtime <code>$state->responses</code> field, to convert from the runtime to the storage model and vice versa:

;<code>create_session_and_responses()</code>
:Initializes the $state object, in particular the <code>$state->responses</code> field

;<code>restore_session_and_responses()</code>
:Loads the question type specific session data from the database into the <code>$state</code> object, in particular it loads the responses that have been saved for the given <code>$state</code> into the <code>$state->responses</code> field.

;<code>save_session_and_responses()</code>
:Saves the question type specific session data from the $state object to the database. In particular, for most questiontypes, it saves the responses from the <code>$state->responses</code> to the database.

The generic quiz module code saves the contents form the <code><nowiki>$state->responses['']</nowiki></code> field to the answer field in the [[Quiz database structure#quiz_states|quiz_states table]] and also automatically restores the contents of this field to <code><nowiki>$state->responses['']</nowiki></code>. This means that any questiontype, which only expects a single value as its response can skip the implementation of the three methods described above. All questiontypes that have multiple value responses need to implement these methods.

The default questiontypes handle this problem by serializing/de-serializing the responses to/from the answer field in the quiz_states table. However, it is also possible (and may be better practice) to extend the quiz_states table with a questiontype specific table, i.e. take the id of the quiz_states record as a foreign key in the questiontype specific table. Because the value of <code><nowiki>$state->responses['']</nowiki></code> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <code>save_session_and_responses()</code>) whatever value the generic code set this field to with their serialized value (usually achieved with a simple set_field).

In the method <code>restore_session_and_responses()</code> the serialized value can be read from <code><nowiki>$state->responses['']</nowiki></code> because this is where the value from answer field of the quiz_states table has been moved. Care needs to be taken that this array value is then unset or the whole array overwritten, so that the array does not accidentally contain a value with the empty string index.

==Response processing==

The runtime model for responses dictates the structure of the $state->responses array. Starting with the names of the form elements this section goes through the relevant processing steps and thus attempts to clarify why the keys of the $state->responses array can differ for different questiontypes; even more, it explains how the array keys are chosen and set.

Although it may initially seem strange to start with the naming convention of the form fields, the reason for this will become clear later on. The controls (i.e. the form fields) of a question get printed by the method <code>print_question_formulation_and_controls()</code>. The convention only dictates that the name of the control element(s) must begin with the value of <code>$question->name_prefix</code>. The <code>$question->name_prefix</code> is a string starting with "resp" followed by the question id and an underscore, e.g. <code>resp56_</code>. In the default case, when there is only a single control element (this includes the case of a list of equally named radio buttons), no postfix is appended to the name prefix. For questiontypes that allow or require multiple form elements, an arbitrary string can be appended to the name prefix to form the name of these form elements. The postfix must not include any relational data (i.e. ids of records in the quiz_answers table), because this can lead to problems with regrading of versioned questions.

After the printing of the question the server only sees it again when it is submitted. So the submitted data will contain several values indexed by strings starting with <code>respXX_</code>. Upon submission, the function <code>quiz_process_responses()</code> is called, which assigns the submitted responses to the state of the question with id XX, using the postfix (i.e. everything after the underscore) as array keys. In the default case with only one control element the name only consists of the name prefix. This explains why the default index of the <code>$state->responses</code> array is the empty string. The value of each array element is obviously the value that was submitted by the form, basically a raw response.

The function <code>quiz_process_responses()</code> in turn calls the questiontype specific method <code>grade_responses()</code> to assign a grade to the submitted responses and <code>compare_responses()</code> to determine whether the response was identical to the previous submission and to avoid regrading the same responses repeatedly. These questiontype specific functions need to be aware of the expected keys of the <code>$state->responses</code> array.

Finally, the methods <code>restore_session_and_responses()</code> and <code>save_session_and_responses()</code> also need to know the questiontype specific layout of the <code>$state->responses array</code> and restore or save the information, e.g. by converting from or to the data representation.

==Question types==
{{Questiontype developer docs}}
The quiz module is itself modular and allows question type plug-ins. For each question type there should be a page, accessible via the menu at the right, which provides at least the dtails about
*Database tables
*Response storage
*Question options object
*State options object

It is hoped that Moodlers will contribute a lot of non-core question types in the future. For this it would be good to start a [[Guide to question type plugins]].

==Grades==

The handling of grades is a bit complicated because there are so many different grades around that get rescaled and combined in various ways. This section should summarize how this is done and why.

The following grade fields are being used:
*$question->defaultgrade
::This is the default value for the maximum grade for this question. This is set up when the teacher creates the question and it is stored in an int(10) field in the [[Quiz database structure#quiz_questions|quiz_questions]] table. However when the question is actually used in a particular quiz the teacher can overrule this default and this is stored in:
*$question->maxgrade
::This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in an int(10) field in the [[Quiz database structure#quiz_question_instances|quiz_question_instances table]].
*$question->penalty

*$state->raw_grade
*$state->grade
*$state->penalty
*$state->sumpenalty

*$attempt->sumgrades

The maximum grades set by the teacher, $question->defaultgrade and $question->maxgrade, are integers. All student-obtained grades are in principle floating point numbers. For historical reasons they are stored in the database as varchar(10) fields. Care has to be taken when writing to the database to make sure all grades are correctly rounded and squeezed into a string of no more than 10 characters, otherwise the writing to database will fail, see bug 4220.

The final outcome of the calculation of the grade for a user at a particular quiz is stored in the 'grade' field of the [[Quiz database structure#quiz_grades|quiz_grades table]]. This field has type double.

==Penalty mechanism==

===What it is for===

When the quiz is run in adaptive mode the student can interact with a question repeatedly. So in particular the student can try again when he gets a wrong answer. Clearly the final mark for the question must reflect the fact that the student did not get it right originally. Therefore a penalty is subtracted from the final mark.

===How the penalty is determined===

First of all penalties are relevant only if a quiz is run in adaptive mode. Only in this case can a student have a second attempt and therefore only in this mode can there be any occasion to subtract a penalty.

Even in adaptive mode the penalty mechanism is only used when it is selected in the quiz options. If "Apply penalties" is set to "No" then the final mark for the question is the mark for the last graded response.

Each question has a 'penalty' field (which should really be called 'penaltyfactor') which is a number between 0 and 1. The penalty for a wrong response is calculated as the product ($quiz->penalty * $quiz->grade), i.e., as the product of the penaltyfactor with the maximum achievable grade for the question. This product is stored in $state->penalty. So $quiz->penalty is the fraction of the maximum grade that is subtracted as a penalty for each wrong response.

The $quiz->penalty field has a default value of 0.1, both in the database and in mod/quiz/defaults.php. This default can of course be overwritten by the admin on the quiz configuration page. This admin-selected default is (as usual for admin defaults) stored in $CFG->quiz_penalty. The teacher can choose a different penalty factor for each individual question when adding or editing a question.

Now if a student makes repeated wrong attempts (or partially correct attempts) the penalties for all these attempts are added up in $state->sumpenalties. The mark for the question is then calculated as the mark for the last graded response minus the sum of the penalties.

One curious fact about $state->sumpenalties is that, for efficiency reasons, it is not stored in the quiz_states table but instead in the 'sumpenalty' field of the quiz_newest_states table. That way it only has to be stored once per attempt rather than once per response.

===Where it is done in the code===

The function quiz_apply_penalty_and_timelimit() subtracts the penalty in $state->sumpenalty from the raw grade in $state->raw_grade to obtain $state->grade for the response. However it is ensured that the grade of a new attempt at the question never falls below the previously achieved grade. This function also increases $state->sumpenalty by the amount in $state->penalty. The assumption is that $state->penalty has just been set appropriately by the code calling this function, e.g., quiz_process_responses.

==Time limit==

A quiz can have a time limit. This is stored in minutes in $quiz->timelimit. So before using this in time calculations it always has to be multiplied by 60 to turn it into seconds like all other timestamps in moodle and php. If $quiz->timelimit is zero it means there is no timelimit.

If a student asks to start an attempt on view.php for a quiz with a timelimit then he is shown a javascript message alerting him to the timelimit and is asked to confirm.

For quizzes with timelimit attempt.php shows a javascript timer that counts down and automatically submits and closes the attempt when the time is up.

Confusingly there are two javascript timers in the quiz module. jsclock.php provides a countdown in the title bar that counts down to the quiz closing time if this is less than a day away. This has nothing to do with the timelimit. jstimer.php provides the countdown timer that implements the timelimit. It in turn uses timer.js.

The time a response was submitted by the student is recorded by attempt.php right at the top of the page and is then passed on to quiz_process_responses in $action->timestamp. This puts it into $state->timestamp. Finally, after the responses have been graded, the function quiz_apply_penalty_and_timelimit() checks that the responses are within the timelimit to within 5% and if not it sets the grade to zero (or the previously obtained grade, if that is higher).

==Pagination==

Quiz attempts can be paginated, i.e., spread over several pages. The student can navigate between the pages using the standard Moodle paging bar. When the student navigates to a different quiz page the answers on the current page are automatically submitted for saving (but not grading).

To do this automatic submission the paging bar needs some javascript. It is therefore not produced with Moodle's standard print_paging_bar() function from weblib.php but with quiz_print_navigation_panel() which is defined in mod/quiz/locallib.php and produces something that looks the same.

The teacher has complete control via the edit interface on edit.php over where the page breaks should occur. He can repaginate the quiz with any chosen number of questions per page. He can also move the page-breaks up and down using the arrows.

Internally page breaks are stored in the $quiz->questions field (which now should really be called $quiz->layout). This field contains a comma separated list of questionids and pagebreaks where the pagebreaks are represented by the id 0. For example 23,12,0,11, 0 means that the two questions with ids 23 and 12 are on the first page and the question with id 11 is on the second page. The last page break is invisible and Moodle sometimes puts it there itself for its own convenience.

Because the quiz has an option $quiz->shufflequestions to shuffle questions the layout that the student sees in a particular attempt does not necessarily have to be the same as that stored in $quiz->questions. Therefore each attempt has its own $attemp->layout field. If $quiz->shufflequestions is false then this just contains a copy of $quiz->questions but if it is true then during the creation of a new attempt by quiz_create_attempt() the function quiz_repaginate() is used to produce a layout with $quiz->questionsperpage number of questions per page that are randomly ordered.

Both attempt.php and review.php use the $attempt->layout field to determine what questions to show on a particular page. That way we can guarantee that the student will, for a particular attempt, always see the questions in the same order and with the same pagination, both while attempting and during review. Also a teacher when reviewing a student's attempt sees the pages the same way they were shown to the student. However the teacher is also given the option to see all questions on one page.

There are some functions in locallib.php dedicated to handling the layout fields: quiz_questions_on_page(), quiz_questions_in_quiz(), quiz_number_of_pages(), quiz_first_questionnumber(), quiz_repaginate(). They are very short functions. The function quiz_first_questionnumber() that determines the number of the first question on a particular page makes use of the $question->length field. To allow this calculation to be fast is the main reason why that field is in the question table even though it could also be determined easily from the question type.

==Question versioning==

'''Note:''' Question versioning is currently disabled until it is re-developed to fix all reported issues.

When questions that were already attempted by a student are edited, it can be important to keep a copy of the question as it was before editing in order to reconstruct the quiz as it was seen by the student. To provide this functionality a question versioning mechanism was implemented.

The first goal, namely keeping around old questions, is easily achieved. They are just not deleted any more. However, this is not enough; it is also necessary to store which questions are versions of others. To achieve this goal, there is an additional table, which stores the versioning information: quiz_question_versions.

When a question is replaced for which there are already student attempts then all the attempt data gets associated to the new version of the question and is re-graded. This requires the question ids in the quiz_attempts, quiz_states and quiz_newest_states tables to be replaced by the new id. However we do also want to be able to reconstruct the quiz the way the student saw it when he gave his answers. For that purpose the id of the original question is always preserved in the 'originalquestion' field of the quiz_states table.

If all old versions of questions are kept around this could horribly clutter the editing interface. Therefore a field called hidden was added to the quiz_questions table and all old versions of edited questions are automatically hidden. When this flag is set to 1 the question is not displayed in the list of available questions, unless the user chooses to show them.

While the mechanism above should work as described, there is some additional complexity in order to minimise the number of versions created. If a question is created and has not been attempted by a student yet (this excludes teacher previews of the individual question and the quiz!), the database record will be reused (i.e. overwritten) and no new version will be created. This is especially important when the question is created and the first 2 or 3 mistakes are only noticed during preview.

On the editing screen for questions an additional set of options was introduced (see image).
Replacement Options
It shows which quizzes use the edited question and how many students have attempted it in a particular quiz. Based on this information it is then possible to choose in which quizzes the new version of the question should be used and in which ones the old one should remain.

By default the 'replace' checkbox for all quizzes that don't have any students' attempts are checked and in addition, if the question is edited out of a quiz context (i.e. not in the category question list), the 'replace' option is checked for that quiz as well.

===Database===

The changes to the database structure are limited to an added field (hidden) in the quiz_questions table and an additional table called quiz_question_versions. However, dealing with the quiz_questions table has become slightly more complicated.

The hidden field in the quiz_questions table has no implications for the core functionality. It is only used to determine, as the name implies, whether the question is shown in the category list or not.

The table quiz_question_versions stores information about the actual change. This information includes the ids of the old question and the new question, the id of the user who did the change and a timestamp. Quite importantly, the id of the quiz, in which the question was replaced is also stored. This means that the versions table provides a history of the different states the quiz went through until it was edited to be at the current state. The information allows to recreate a quiz as it was at any point in time (from a data perspective - this possibility is not used extensively by the code).

===Adjustments to the Data===

When a question is replaced by a newer version, database records are updated in the order shown below (compare with question.php):

* First a new record is inserted into the quiz_question_versions table for each affected quiz (i.e. each quiz in which the question was replaced).
* Then, for each affected quiz, the comma separated list of question ids in the question field is updated by replacing the old question id with the new one.
* In the quiz_question_instances table the record that links the old question to the quiz is also updated to point to the new question.
* In all attempts belonging to the old question the comma-separated list of question ids in the layout field are changed by replacing the old id by the new one.
* All states belonging to the old question are made to belong to the new version by changing the id in the 'question' field. However if we are replacing the original question then the id of this original version is stored in the originalquestion field.
* We have to change the questionid field in quiz_newest_states.
* Finally we have to do any question-type specific changes. For example question types that store student responses by storing the id of the answer in the quiz_answers table will have to recode these ids in all the states to point to the corresponding answers in the new version. This is handled by the function replace_question_in_attempts() in the question type class.

===Affected Code and Functionality===

Note: This section should still be considered under construction until the question mark behind bug #3311 is taken off.

In the file review.php and potentially also in the file attempt.php, if a question is edited during a student's attempt, the data from quiz_question_versions needs to be taken into account. If a student has attempted a quiz and a question was changed afterwards (i.e. a new version of that question was created), the question id of the old version remains in the comma separated list inside the attempt->layout field. However, since the records in the quiz_question_instances table get updated, we need to go forward in the question history, by looping through entries from the quiz_question_versions table, to find out the id of the question version that is currently used in the quiz.

Suggestion: With a fairly simple change to the convention of what is stored in the quiz_question_versions table we could get rid of the requirement of looping through all the versions. If in the newquestion field we store the id of the question that is currently used in the quiz, it would be possible to get the complete history for a question quite simply by selecting by quiz id and newquestion.

It should be fairly simple to write an upgrade script for this change. Additionally, another set_field would need to be added to question.php to change the newquestion field to the new question id. The benefits would be a much simpler handling of the question history, resulting in more efficient code than the current fix for bug #3311 in review.php.

The place where all the versioning actually takes place is question.php. Here the changes described in Adjustments to the Data are carried out.

Obviously the backup and restore scripts also take quiz_question_versions into account, however, they don't need to be concerned with the ways the data is used.

==Changes for Moodle 1.5: adaptive questions==

During the first half of 2005 the quiz module code has undergone a considerable rewrite to allow for adaptive questions in which a question session can consist of several sequential student responses. The question can adapt itself to the student answers. For example in response to certain answers the question could provide feedback or hints and then ask the student to answer again or give the student a simpler or related question.

Unfortunately many changes had to be made to the question type methods. This has however resulted in improved efficiency and has made the writing of question types easier. It also allows question types with more powerful features and has fixed some bugs / annoying behaviour.

For details see:
*[[Quiz rewrite|Quiz module rewrite]]
*[[Quiz conversion|How to convert existing question types]]

Of course there were countless other changes to the quiz module going from Moodle 1.4 to 1.5, especially to the teacher interface. However in spite of the fact that these changes are a lot more visible they were much less drastic from the point of view of the code. Here is a very incomplete list of changes:

* New quiz results overview page
* Reform of the quiz edit page: Changes on the quiz edit page are saved straightaway, not only after Save button is pressed.
* Copying questions: The teacher can create a new question using a previous one as template.
* Moving questions: The teacher can now move selected questions to a different category.
* Re-marking after question editing: if a teacher corrects a question that students have already attempted the teacher can request a remark.
* Teacher preview tab.
* Detailed teacher control over what students can see during review.

==Changes for Moodle 1.6: separating questions from quizzes==

The quiz module is not the only activity module in Moodle that uses questions. The lesson does too and potentially questions could be useful in many modules. Therefore we have started to rewrite some of the quiz module functions and move them from locallib.php to questionlib.php so that eventually they could be moved into a central library and be used by other modules.

Module developers who want to use the
quiz module questions in their own module should take a look at the simple questiondemo module that you can find in CVS at [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/questiondemo contrib/questiondemo]. The idea is that it will be simpler
to understand this demonstration module than the code in the quiz module which
is very complicated due to the many options and features. The interesting code in the questiondemo module is in view.php. There you can see how to
both render and score questions. This module requires the version of the quiz module from Moodle 1.6dev or later.

The details of the changes are explained on the page [[Separating questions from quizzes]].

==Future plans==

The features below are in no particular order:

* Editing questions: This is about editing questions after students have already attempted them. There needs to be a mechanism to keep the old versions of the question around for auditing purposes.
* New quiz statistics pages?: These pages should be built by using functions defined by the individual question types.
* Manual grade override: Teachers should be able to override the automatically calculated grades and should be able to make comments.
* Off-line questions: The answers to these are handed in off-line in the conventional way (e.g., on paper) and teachers enter marks on Moodle.
* Batch printing of quiz sheets: We want to be able to hand out question sheets to students so they can start working on the questions before going to the computer.
* Question preview from question edit page: so the teacher can try the question already before saving the changes.
* Show table of questions on view.php: gives teachers and students a bit of an overview of the quiz.
* Extending deadlines for individual students: for example when a student misses a deadline for good reasons.
* Filtering questions by quiz and by search: More ways to restrict which questions are shown on the quiz editing page.
* Re-open quizzes for revision: After the due date has passed the quiz could allow practice attempts.

[[Category:Developer]]
[[Category:Quiz]]

Development:Quiz

2006-02-06T15:51:29Z

Gustav: /* Answers */ comment about wrong/correct answers

{{Quiz developer docs}}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. This page aims to collect useful documentation on how the module works.

==Terminology==

When talking about the quiz module there are certain terms that can cause confusion because they can be used with different meanings. In Moodle we have adopted a certain terminology that will be explained below.

===Questions===

A '''question''' in the context of the quiz module is the set of definitions (question name, question text, possible answers, grading rules, feedback, etc.) that constitute a reusable assessment item. So it is much more than what one would in everyday language understand under a question and which in Moodle is just on field (the questiontext field) of the question object.

What in Moodle we refer to as a 'question' is what in the terminology of the QTI specification ismore appropriately called an '''assessment item''' or just 'item' for short.

There are different types of questions, like for example multiple-choice questions or numerical questions. These are referred to as '''[[Quiz developer docs#Question types|question types]]''' in Moodle.

Since version 1.5 Moodle is able to handle so-called '''[[Adaptive questions]]''', also known as 'adaptive items' in QTI speak. These are qustions that walk the user through a directed graph of question states depending on the user's responses. For example 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. Quizzes can be run in 'adaptive mode', which provides buttons to mark each question individually.

===Answers===

In Moodle the term ''''answer'''' is used exclusively for the '''teacher-defined answers''' of a question. When talking about the quiz module it is easy to get confused between these teacher-defined answers and the answers that the students actually give. We have therefore adopted the convention to refer to the student-supplied answers as 'responses' and to reserve the term 'answers' to apply to teacher-defined answers. In question types that rely on teacher-supplied answers these are used in the grading process by comparing them with the student responses. Of course not all question types use teacher-defined answers but use some more intelligent way to process the student responses.

Perhaps one should also stress that 'answer' is not always used in the sense of 'correct answer'. For example every choice in a multiple-choice question is referred to as an answer. Other systems use the term 'distractor' for wrong answers.

In Moodle we always use the term ''''responses'''' to refer to the students' responses to a question because term 'answers' that one might also be tempted to use for this is already used to refer to the teacher-defined answers, see above. This term is always used in plural, although for some questiontypes there is only one possible response.

===Attempts===

In Moodle 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 ''''attempts at a question'''', never just as 'attempts'.

Because a student can have several attempts at a question within the same attempt at the quiz, there is a lot of data that needs to be stored as the student takes the question through several ''''states'''' by repeated interactions with the question. A state object holds the most recent state of the question and whenever a student submits a response or a similar ''''event'''' occurs, the question goes to a new state. The complete history of question states that the question is taken through is saved and this is referred to as the question ''''session''''. Usually only the most recent state and the last graded state are of interest though.

==Code documentation==

The code is documented according to phpdoc conventions. The explanations here in the wiki are meant to complement this.

Inline comments should be used liberally in the code. The following conventions make it easier to search for comments with special meaning:
* use TODO in comments about things that need to be done
* use ??? in comments that are questions about the code

There are three function libraries:

;questionlib.php
:All functions that need to be available to any module wanting to use questions. This is New in Moodle 1.6, in Moodle 1.5 this was part of locallib.php. This instantiates all questiontype classes by loading the questiontype.php files

;lib.php
:All the functions that are sometimes called by the Moodle core. This loads constants from '''constants.php'''

;locallib.php
:All functions that are used only by the quiz module. This loads lib.php and questionlib.php

The default questiontype class is defined in '''questiontypes/questiontype.php'''. The individual questiontypes extend this class in their own questiontype.php file. For documentation of the questiontype classes one should often look at the documentation of the default question type because much of the documentation that is in the default class is not repeated in the other questiontype classes

Constants are defined in .

While questiontypes are realized as classes, the quiz module is not written in a truly object-oriented way. Instead it follows the Moodle model of using objects mostly only as alternatives to arrays to hold database records. So none of the quiz, question, attempt, and state objects that play a central role in the module have any methods. Only the questiontype objects have methods. Strangely enough the quiz module instantiates on object of each questiontype class at the start and then reuses their methods for the different questions. If one is used to the Moodle way of programming then this is easy enough to handle.

==Objects and data structures==

Key to understanding how the quiz module works is to understand the different kinds of object work together. The most important ones are:

*Quizzes
*Questions
*Attempts
*States

Quizzes and Questions are data created by the teacher when setting up and editing a quiz. Attempts and States are data created by the student when interacting with a quiz.

Moodle allows students to make several attempts at a quiz. Data about such an attempt is stored in an attempt object. This holds for example how the quiz was randomized for this attempt and the ordering of the questions and answers. So attempts are indexed by user id and quiz id.

Moodle allows students to interact repeatedly with a single question. So for example the student might initially just save an answer, later mark it, then correct it if it was marked incorrect. Each time the student interacts with a particular question inside a particular attempt at a quiz a new state is created. So states are indexed by user id, attempt id and question id.

===Database structure===
All this data needs to be kept in Moodle's database. How this is achieved is explained on a separate page about the '''[[Quiz database structure]]''', which also contains a useful diagram.

As is customary in Moodle, most runtime objects simply represent the data from a particular database record. So for example a $quiz object has fields corresponding to all the fields in the [[Quiz database structure#quiz|quiz table]]. In some cases the objects have some additional fields that are added at runtime. This is particularly the case for $question and $state objects. These additional fields are also described on the page about the '''[[Quiz database structure]]'''. Many functions that are used to process these objects make use of the additional fields and it is therefore necessary to use the correct functions for creating these objects.

===Runtime objects===
Some objects used by the quiz module are purely runtime object and do not correspond to a database table. The structure of these objects is explained in detail on a separate page about the '''[[Quiz runtime objects]]'''.

The main script of the quiz module is attempt.php which will have to deal with all these objects. Studying the '''[[Quiz attempt|explanation of attempt.php]]''' is therefore a good way to start to study the quiz module code.

==Response storage==

The student's responses to a question are stored in <code>$state->responses</code>. Questiontypes are completely free to implement the storage mechanism of their responses (and other state information) the way they want. Still, the standard questiontypes all follow a similar model. The default storage model and the questiontype specific variations are explained below.

The flexibility for the questiontypes to choose their response storage mechanism freely and to convert from the storage model to the runtime model is provided by a set of three functions, which allow to initialise the runtime <code>$state->responses</code> field, to convert from the runtime to the storage model and vice versa:

;<code>create_session_and_responses()</code>
:Initializes the $state object, in particular the <code>$state->responses</code> field

;<code>restore_session_and_responses()</code>
:Loads the question type specific session data from the database into the <code>$state</code> object, in particular it loads the responses that have been saved for the given <code>$state</code> into the <code>$state->responses</code> field.

;<code>save_session_and_responses()</code>
:Saves the question type specific session data from the $state object to the database. In particular, for most questiontypes, it saves the responses from the <code>$state->responses</code> to the database.

The generic quiz module code saves the contents form the <code><nowiki>$state->responses['']</nowiki></code> field to the answer field in the [[Quiz database structure#quiz_states|quiz_states table]] and also automatically restores the contents of this field to <code><nowiki>$state->responses['']</nowiki></code>. This means that any questiontype, which only expects a single value as its response can skip the implementation of the three methods described above. All questiontypes that have multiple value responses need to implement these methods.

The default questiontypes handle this problem by serializing/de-serializing the responses to/from the answer field in the quiz_states table. However, it is also possible (and may be better practice) to extend the quiz_states table with a questiontype specific table, i.e. take the id of the quiz_states record as a foreign key in the questiontype specific table. Because the value of <code><nowiki>$state->responses['']</nowiki></code> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <code>save_session_and_responses()</code>) whatever value the generic code set this field to with their serialized value (usually achieved with a simple set_field).

In the method <code>restore_session_and_responses()</code> the serialized value can be read from <code><nowiki>$state->responses['']</nowiki></code> because this is where the value from answer field of the quiz_states table has been moved. Care needs to be taken that this array value is then unset or the whole array overwritten, so that the array does not accidentally contain a value with the empty string index.

==Response processing==

The runtime model for responses dictates the structure of the $state->responses array. Starting with the names of the form elements this section goes through the relevant processing steps and thus attempts to clarify why the keys of the $state->responses array can differ for different questiontypes; even more, it explains how the array keys are chosen and set.

Although it may initially seem strange to start with the naming convention of the form fields, the reason for this will become clear later on. The controls (i.e. the form fields) of a question get printed by the method <code>print_question_formulation_and_controls()</code>. The convention only dictates that the name of the control element(s) must begin with the value of <code>$question->name_prefix</code>. The <code>$question->name_prefix</code> is a string starting with "resp" followed by the question id and an underscore, e.g. <code>resp56_</code>. In the default case, when there is only a single control element (this includes the case of a list of equally named radio buttons), no postfix is appended to the name prefix. For questiontypes that allow or require multiple form elements, an arbitrary string can be appended to the name prefix to form the name of these form elements. The postfix must not include any relational data (i.e. ids of records in the quiz_answers table), because this can lead to problems with regrading of versioned questions.

After the printing of the question the server only sees it again when it is submitted. So the submitted data will contain several values indexed by strings starting with <code>respXX_</code>. Upon submission, the function <code>quiz_process_responses()</code> is called, which assigns the submitted responses to the state of the question with id XX, using the postfix (i.e. everything after the underscore) as array keys. In the default case with only one control element the name only consists of the name prefix. This explains why the default index of the <code>$state->responses</code> array is the empty string. The value of each array element is obviously the value that was submitted by the form, basically a raw response.

The function <code>quiz_process_responses()</code> in turn calls the questiontype specific method <code>grade_responses()</code> to assign a grade to the submitted responses and <code>compare_responses()</code> to determine whether the response was identical to the previous submission and to avoid regrading the same responses repeatedly. These questiontype specific functions need to be aware of the expected keys of the <code>$state->responses</code> array.

Finally, the methods <code>restore_session_and_responses()</code> and <code>save_session_and_responses()</code> also need to know the questiontype specific layout of the <code>$state->responses array</code> and restore or save the information, e.g. by converting from or to the data representation.

==Question types==
{{Questiontype developer docs}}
The quiz module is itself modular and allows question type plug-ins. For each question type there should be a page, accessible via the menu at the right, which provides at least the dtails about
*Database tables
*Response storage
*Question options object
*State options object

It is hoped that Moodlers will contribute a lot of non-core question types in the future. For this it would be good to start a [[Guide to question type plugins]].

==Grades==

The handling of grades is a bit complicated because there are so many different grades around that get rescaled and combined in various ways. This section should summarize how this is done and why.

The following grade fields are being used:
*$question->defaultgrade
::This is the default value for the maximum grade for this question. This is set up when the teacher creates the question and it is stored in an int(10) field in the [[Quiz database structure#quiz_questions|quiz_questions]] table. However when the question is actually used in a particular quiz the teacher can overrule this default and this is stored in:
*$question->maxgrade
::This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in an int(10) field in the [[Quiz database structure#quiz_question_instances|quiz_question_instances table]].
*$question->penalty

*$state->raw_grade
*$state->grade
*$state->penalty
*$state->sumpenalty

*$attempt->sumgrades

The maximum grades set by the teacher, $question->defaultgrade and $question->maxgrade, are integers. All student-obtained grades are in principle floating point numbers. For historical reasons they are stored in the database as varchar(10) fields. Care has to be taken when writing to the database to make sure all grades are correctly rounded and squeezed into a string of no more than 10 characters, otherwise the writing to database will fail, see bug 4220.

The final outcome of the calculation of the grade for a user at a particular quiz is stored in the 'grade' field of the [[Quiz database structure#quiz_grades|quiz_grades table]]. This field has type double.

==Penalty mechanism==

===What it is for===

When the quiz is run in adaptive mode the student can interact with a question repeatedly. So in particular the student can try again when he gets a wrong answer. Clearly the final mark for the question must reflect the fact that the student did not get it right originally. Therefore a penalty is subtracted from the final mark.

===How the penalty is determined===

First of all penalties are relevant only if a quiz is run in adaptive mode. Only in this case can a student have a second attempt and therefore only in this mode can there be any occasion to subtract a penalty.

Even in adaptive mode the penalty mechanism is only used when it is selected in the quiz options. If "Apply penalties" is set to "No" then the final mark for the question is the mark for the last graded response.

Each question has a 'penalty' field (which should really be called 'penaltyfactor') which is a number between 0 and 1. The penalty for a wrong response is calculated as the product ($quiz->penalty * $quiz->grade), i.e., as the product of the penaltyfactor with the maximum achievable grade for the question. This product is stored in $state->penalty. So $quiz->penalty is the fraction of the maximum grade that is subtracted as a penalty for each wrong response.

The $quiz->penalty field has a default value of 0.1, both in the database and in mod/quiz/defaults.php. This default can of course be overwritten by the admin on the quiz configuration page. This admin-selected default is (as usual for admin defaults) stored in $CFG->quiz_penalty. The teacher can choose a different penalty factor for each individual question when adding or editing a question.

Now if a student makes repeated wrong attempts (or partially correct attempts) the penalties for all these attempts are added up in $state->sumpenalties. The mark for the question is then calculated as the mark for the last graded response minus the sum of the penalties.

One curious fact about $state->sumpenalties is that, for efficiency reasons, it is not stored in the quiz_states table but instead in the 'sumpenalty' field of the quiz_newest_states table. That way it only has to be stored once per attempt rather than once per response.

===Where it is done in the code===

The function quiz_apply_penalty_and_timelimit() subtracts the penalty in $state->sumpenalty from the raw grade in $state->raw_grade to obtain $state->grade for the response. However it is ensured that the grade of a new attempt at the question never falls below the previously achieved grade. This function also increases $state->sumpenalty by the amount in $state->penalty. The assumption is that $state->penalty has just been set appropriately by the code calling this function, e.g., quiz_process_responses.

==Time limit==

A quiz can have a time limit. This is stored in minutes in $quiz->timelimit. So before using this in time calculations it always has to be multiplied by 60 to turn it into seconds like all other timestamps in moodle and php. If $quiz->timelimit is zero it means there is no timelimit.

If a student asks to start an attempt on view.php for a quiz with a timelimit then he is shown a javascript message alerting him to the timelimit and is asked to confirm.

For quizzes with timelimit attempt.php shows a javascript timer that counts down and automatically submits and closes the attempt when the time is up.

Confusingly there are two javascript timers in the quiz module. jsclock.php provides a countdown in the title bar that counts down to the quiz closing time if this is less than a day away. This has nothing to do with the timelimit. jstimer.php provides the countdown timer that implements the timelimit. It in turn uses timer.js.

The time a response was submitted by the student is recorded by attempt.php right at the top of the page and is then passed on to quiz_process_responses in $action->timestamp. This puts it into $state->timestamp. Finally, after the responses have been graded, the function quiz_apply_penalty_and_timelimit() checks that the responses are within the timelimit to within 5% and if not it sets the grade to zero (or the previously obtained grade, if that is higher).

==Pagination==

Quiz attempts can be paginated, i.e., spread over several pages. The student can navigate between the pages using the standard Moodle paging bar. When the student navigates to a different quiz page the answers on the current page are automatically submitted for saving (but not grading).

To do this automatic submission the paging bar needs some javascript. It is therefore not produced with Moodle's standard print_paging_bar() function from weblib.php but with quiz_print_navigation_panel() which is defined in mod/quiz/locallib.php and produces something that looks the same.

The teacher has complete control via the edit interface on edit.php over where the page breaks should occur. He can repaginate the quiz with any chosen number of questions per page. He can also move the page-breaks up and down using the arrows.

Internally page breaks are stored in the $quiz->questions field (which now should really be called $quiz->layout). This field contains a comma separated list of questionids and pagebreaks where the pagebreaks are represented by the id 0. For example 23,12,0,11, 0 means that the two questions with ids 23 and 12 are on the first page and the question with id 11 is on the second page. The last page break is invisible and Moodle sometimes puts it there itself for its own convenience.

Because the quiz has an option $quiz->shufflequestions to shuffle questions the layout that the student sees in a particular attempt does not necessarily have to be the same as that stored in $quiz->questions. Therefore each attempt has its own $attemp->layout field. If $quiz->shufflequestions is false then this just contains a copy of $quiz->questions but if it is true then during the creation of a new attempt by quiz_create_attempt() the function quiz_repaginate() is used to produce a layout with $quiz->questionsperpage number of questions per page that are randomly ordered.

Both attempt.php and review.php use the $attempt->layout field to determine what questions to show on a particular page. That way we can guarantee that the student will, for a particular attempt, always see the questions in the same order and with the same pagination, both while attempting and during review. Also a teacher when reviewing a student's attempt sees the pages the same way they were shown to the student. However the teacher is also given the option to see all questions on one page.

There are some functions in locallib.php dedicated to handling the layout fields: quiz_questions_on_page(), quiz_questions_in_quiz(), quiz_number_of_pages(), quiz_first_questionnumber(), quiz_repaginate(). They are very short functions. The function quiz_first_questionnumber() that determines the number of the first question on a particular page makes use of the $question->length field. To allow this calculation to be fast is the main reason why that field is in the question table even though it could also be determined easily from the question type.

==Question versioning==

'''Note:''' Question versioning is currently disabled until it is re-developed to fix all reported issues.

When questions that were already attempted by a student are edited, it can be important to keep a copy of the question as it was before editing in order to reconstruct the quiz as it was seen by the student. To provide this functionality a question versioning mechanism was implemented.

The first goal, namely keeping around old questions, is easily achieved. They are just not deleted any more. However, this is not enough; it is also necessary to store which questions are versions of others. To achieve this goal, there is an additional table, which stores the versioning information: quiz_question_versions.

When a question is replaced for which there are already student attempts then all the attempt data gets associated to the new version of the question and is re-graded. This requires the question ids in the quiz_attempts, quiz_states and quiz_newest_states tables to be replaced by the new id. However we do also want to be able to reconstruct the quiz the way the student saw it when he gave his answers. For that purpose the id of the original question is always preserved in the 'originalquestion' field of the quiz_states table.

If all old versions of questions are kept around this could horribly clutter the editing interface. Therefore a field called hidden was added to the quiz_questions table and all old versions of edited questions are automatically hidden. When this flag is set to 1 the question is not displayed in the list of available questions, unless the user chooses to show them.

While the mechanism above should work as described, there is some additional complexity in order to minimise the number of versions created. If a question is created and has not been attempted by a student yet (this excludes teacher previews of the individual question and the quiz!), the database record will be reused (i.e. overwritten) and no new version will be created. This is especially important when the question is created and the first 2 or 3 mistakes are only noticed during preview.

On the editing screen for questions an additional set of options was introduced (see image).
Replacement Options
It shows which quizzes use the edited question and how many students have attempted it in a particular quiz. Based on this information it is then possible to choose in which quizzes the new version of the question should be used and in which ones the old one should remain.

By default the 'replace' checkbox for all quizzes that don't have any students' attempts are checked and in addition, if the question is edited out of a quiz context (i.e. not in the category question list), the 'replace' option is checked for that quiz as well.

===Database===

The changes to the database structure are limited to an added field (hidden) in the quiz_questions table and an additional table called quiz_question_versions. However, dealing with the quiz_questions table has become slightly more complicated.

The hidden field in the quiz_questions table has no implications for the core functionality. It is only used to determine, as the name implies, whether the question is shown in the category list or not.

The table quiz_question_versions stores information about the actual change. This information includes the ids of the old question and the new question, the id of the user who did the change and a timestamp. Quite importantly, the id of the quiz, in which the question was replaced is also stored. This means that the versions table provides a history of the different states the quiz went through until it was edited to be at the current state. The information allows to recreate a quiz as it was at any point in time (from a data perspective - this possibility is not used extensively by the code).

===Adjustments to the Data===

When a question is replaced by a newer version, database records are updated in the order shown below (compare with question.php):

* First a new record is inserted into the quiz_question_versions table for each affected quiz (i.e. each quiz in which the question was replaced).
* Then, for each affected quiz, the comma separated list of question ids in the question field is updated by replacing the old question id with the new one.
* In the quiz_question_instances table the record that links the old question to the quiz is also updated to point to the new question.
* In all attempts belonging to the old question the comma-separated list of question ids in the layout field are changed by replacing the old id by the new one.
* All states belonging to the old question are made to belong to the new version by changing the id in the 'question' field. However if we are replacing the original question then the id of this original version is stored in the originalquestion field.
* We have to change the questionid field in quiz_newest_states.
* Finally we have to do any question-type specific changes. For example question types that store student responses by storing the id of the answer in the quiz_answers table will have to recode these ids in all the states to point to the corresponding answers in the new version. This is handled by the function replace_question_in_attempts() in the question type class.

===Affected Code and Functionality===

Note: This section should still be considered under construction until the question mark behind bug #3311 is taken off.

In the file review.php and potentially also in the file attempt.php, if a question is edited during a student's attempt, the data from quiz_question_versions needs to be taken into account. If a student has attempted a quiz and a question was changed afterwards (i.e. a new version of that question was created), the question id of the old version remains in the comma separated list inside the attempt->layout field. However, since the records in the quiz_question_instances table get updated, we need to go forward in the question history, by looping through entries from the quiz_question_versions table, to find out the id of the question version that is currently used in the quiz.

Suggestion: With a fairly simple change to the convention of what is stored in the quiz_question_versions table we could get rid of the requirement of looping through all the versions. If in the newquestion field we store the id of the question that is currently used in the quiz, it would be possible to get the complete history for a question quite simply by selecting by quiz id and newquestion.

It should be fairly simple to write an upgrade script for this change. Additionally, another set_field would need to be added to question.php to change the newquestion field to the new question id. The benefits would be a much simpler handling of the question history, resulting in more efficient code than the current fix for bug #3311 in review.php.

The place where all the versioning actually takes place is question.php. Here the changes described in Adjustments to the Data are carried out.

Obviously the backup and restore scripts also take quiz_question_versions into account, however, they don't need to be concerned with the ways the data is used.

==Changes for Moodle 1.5: adaptive questions==

During the first half of 2005 the quiz module code has undergone a considerable rewrite to allow for adaptive questions in which a question session can consist of several sequential student responses. The question can adapt itself to the student answers. For example in response to certain answers the question could provide feedback or hints and then ask the student to answer again or give the student a simpler or related question.

Unfortunately many changes had to be made to the question type methods. This has however resulted in improved efficiency and has made the writing of question types easier. It also allows question types with more powerful features and has fixed some bugs / annoying behaviour.

For details see:
*[[Quiz rewrite|Quiz module rewrite]]
*[[Quiz conversion|How to convert existing question types]]

Of course there were countless other changes to the quiz module going from Moodle 1.4 to 1.5, especially to the teacher interface. However in spite of the fact that these changes are a lot more visible they were much less drastic from the point of view of the code. Here is a very incomplete list of changes:

* New quiz results overview page
* Reform of the quiz edit page: Changes on the quiz edit page are saved straightaway, not only after Save button is pressed.
* Copying questions: The teacher can create a new question using a previous one as template.
* Moving questions: The teacher can now move selected questions to a different category.
* Re-marking after question editing: if a teacher corrects a question that students have already attempted the teacher can request a remark.
* Teacher preview tab.
* Detailed teacher control over what students can see during review.

==Changes for Moodle 1.6: separating questions from quizzes==

The quiz module is not the only activity module in Moodle that uses questions. The lesson does too and potentially questions could be useful in many modules. Therefore we have started to rewrite some of the quiz module functions and move them from locallib.php to questionlib.php so that eventually they could be moved into a central library and be used by other modules.

Module developers who want to use the
quiz module questions in their own module should take a look at the simple questiondemo module that you can find in CVS at [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/questiondemo contrib/questiondemo]. The idea is that it will be simpler
to understand this demonstration module than the code in the quiz module which
is very complicated due to the many options and features. The interesting code in the questiondemo module is in view.php. There you can see how to
both render and score questions. This module requires the version of the quiz module from Moodle 1.6dev or later.

The details of the changes are explained on the page [[Separating questions from quizzes]].

==Future plans==

The features below are in no particular order:

* Editing questions: This is about editing questions after students have already attempted them. There needs to be a mechanism to keep the old versions of the question around for auditing purposes.
* New quiz statistics pages?: These pages should be built by using functions defined by the individual question types.
* Manual grade override: Teachers should be able to override the automatically calculated grades and should be able to make comments.
* Off-line questions: The answers to these are handed in off-line in the conventional way (e.g., on paper) and teachers enter marks on Moodle.
* Batch printing of quiz sheets: We want to be able to hand out question sheets to students so they can start working on the questions before going to the computer.
* Question preview from question edit page: so the teacher can try the question already before saving the changes.
* Show table of questions on view.php: gives teachers and students a bit of an overview of the quiz.
* Extending deadlines for individual students: for example when a student misses a deadline for good reasons.
* Filtering questions by quiz and by search: More ways to restrict which questions are shown on the quiz editing page.
* Re-open quizzes for revision: After the due date has passed the quiz could allow practice attempts.

[[Category:Developer]]
[[Category:Quiz]]

Quiz preview

2006-02-06T09:52:48Z

Gustav: Asking for volunteers

{{Quizzes}}

=Quiz attempt=

==For Students==

Any volunteers for writing a help text here that could later become part of the standard Moodle documentation and be made accessible to students via a question mark icon on their attempt page?

==For Teachers==
This section needs serious editing.

=== Quiz preview ===
This will show you the quiz the way the student will see it. The only difference is that you will see a little link below each question number that you can click to be taken directly to the question editing page for that question. This makes it convenient for you to correct mistakes in questions straight from the preview page.

The '''quiz preview''' enables you to try the quiz. In a preview it will say 'Preview check'. Attempting a quiz, it will say which attempt at the test it is. Also, all the questions will have a mark index, i.e. the number of points gained per the number of points that could be gained for doing a given question. You will find it under the question number. Also, each question is given a Submit button.

The quiz questions being answered, you will find three options to go for:

# '''Save without submitting''' - which, as its name says, saves the answers without submitting them
# '''Submit page''' (optional) - which submits only a given quiz page
# '''Submit all and finish''' - which saves the whole quiz

[[Category:Teacher]]

Development:True/False question type

2006-02-06T08:32:36Z

Gustav: /* Response storage */

{{Questiontype developer docs}}

==Database tables==
An extension of the quiz_questions table the quiz_truefalse table stores the answer ids for the true and for the false answers.
;id
:int(10) unsigned NOT NULL auto_increment,
;question
:int(10) unsigned NOT NULL default '0',
;trueanswer
:int(10) unsigned NOT NULL default '0',
;falseanswer
:int(10) unsigned NOT NULL default '0',
==Response storage==
The true/false questiontype stores a single answer id (from the table quiz_answers) in the answer field. Each true/false question defines two answer records, one for the 'true' option, one for the 'false' option, so either of these two ids gets stored as response.

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Development:Short Answer question type

2006-02-06T08:32:08Z

Gustav: /* Response storage */

{{Questiontype developer docs}}

==Database tables==
The quiz_shortanswer table is an extension of the quiz_questions table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key
;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field of the quiz_questions table
;answers
:varchar(255) NOT NULL default '',
:A comma separated list of answer ids. This is redundant
;usecase
:tinyint(2) NOT NULL default '0',
:used to decide whether to do a case sensitive or case insensitive comparison for grading.

==Response storage==
The shortanswer questiontype is the ideal example of the default case. It does not overwrite any of the default implementations of the three methods mentioned above, because it uses the default $state->responses array indexed with the empty string. The value entered into the shortanswer input field is entered directly into the answer field.

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Development:Random Short-Answer Matching question type

2006-02-06T08:31:32Z

Gustav: /* Response storage */

{{Questiontype developer docs}}

==Database tables==
The '''quiz_randomsamatch''' table is an extension of the quiz_questions table

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key
;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id field of the quiz_questions table
;choose
:int(10) unsigned NOT NULL default '4',
:The number of shortanswer questions should be randomly chosen to build this randomsamatch question.

==Response storage==
The random shortanswer matching questiontype reuses the save_session_and_responses method of the matching questiontype and therefore stores its responses in the same format. The difference is that the first id in the pair is the question id (quiz_questions) of the selected shortanswer and the second id is the id of the first correct answer that is found ofr that shortanswer question in the quiz_answers table.

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Development:Numerical question type

2006-02-06T08:31:04Z

Gustav: /* Response storage */

{{Questiontype developer docs}}

==Database tables==

==Response storage==

The numerical questiontype, which inherits the function print_question_formulation_and_controls() from the shortanswer questiontype, has only one response field, so its responses are handled by the default questiontype. The response is stored without any modifications in the answer field of the table quiz_states.

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]

Roadmap

2006-02-05T23:58:20Z

Gustav: link to UTF-8_migration

This roadmap collects the best information about upcoming features in Moodle. It is not 100% certain - features may change according to available funding and developers.

== Version 1.6 - Beta expected late February 2006 ==

* [[UTF-8_migration|Unicode]] - Moodle.com, Eloy Lafuente and Koen Roggemans
::Moodle is now 100% Unicode, which means any language can be mixed together and an end to a number of problems that different character sets caused us.
* [[MoodleDocs development|Documentation]] - Moodle.com and Helen Foster
::A new one-stop wiki site for ALL Moodle documentation, including links from Moodle itself
* [[Database]] - Moodle.com
::A new activity module that allows collaborative collection of structured data, useful for many things!
* [[LAMS]] - LAMS Foundation
::Integrated via a course format and an activity module
* [[Blogs]] - Daryl Hawes and Moodle.com
::Allows reflection on an ongoing basis. Entries are marked and can be viewed by user, course, group, site etc. Contains new keyword support.
* [[Site stats]] - Catalyst
::Provides statistics at a higher level than before (by course etc.)
* [[My Moodle]] - Catalyst
::A dashboard interface that allows an overview for each user of all their courses etc.
* [[Hive integration]] - Moodle.com and Harvest Road
::This initial integration with Hive allows teachers to upload, browse, search and select [[mod/resource/index|Resources]] within the external repository.
* [[Multiple groups]] - Moodle.com and Arab Open University
::Users can be part of multiple groups within a course
* [[IMS resource]] - Eloy Lafuente and Alton College
::Supports the loading of any content package as a resource, plus special support for a repository of NLN materials
* [[Learning Design export]] - Moodle.com and Open University of The Netherlands
::We plan to have a very simple export for any Moodle course into IMS LD format, as a proof of concept and to help the community start learning about IMS LD.
* [[Granularised backup]] - Catalyst and Eloy Lafuente
* [[Chameleon|Chameleon theme]] - Andy Walker and Urs Hunkler
:: An interactive Moodle theme
* [[Multi Authentication]] - Iñaki Arenaza?
* [[Multi Enrolment]] - Catalyst

== Version 2.0 - Expected end of 2006 ==

* [[IMS Learning Design]] - Moodle.com
::Support for importing/exporting LD, converting Moodle activities and sequences of activities into a standard format for sharing, and importing standard sequences into Moodle courses
* [[Conditional activities]] - Moodle.com
::Allowing dependencies and forced paths through the content
* [[Roles]] - Moodle.com
::This new system will allow the creation of custom roles at site, course and activity level
* [[Metadata]] - Moodle.com
::Build on the keywords in 1.6 to provide metadata for all activities and courses, linkable to standard lists of metadata such as State-based learning outomes and curricula
* [[Accessibility]] - Moodle.com
::Full compliance with all major accessibility standards
* [[Web Services API]]
::Providing remote control and access of Moodle services by other systems, as well as sharing of information between Moodle sites with trust relationships.
* [[Repository API]] - Moodle.com
::Abstract all file operations to an API that allows plugins for different external repositories
* [[Student Information API]]
::API for integrating external systems for managing student information
* [[Community hub]] - Moodle.com
::Leverage above improvements into a system to network Moodles together

== Version 2.1 ==

* [[Groups]]
::Groups can also be defined at the site level, and activities can be assigned to course groups
* [[Portfolio API]]
::Interface Moodle activities and repositories to help produce portfolios for internal assessment AND external publication

[[Category:Developer]]

Development:Quiz database structure

2006-02-05T23:52:57Z

Gustav: Question type specific tables have been move to questiontype pages

{{Quiz developer docs}}The quiz data model has a fairly large pool of database tables, so the first step in explaining them is to provide some order. Conceptually it is possible to distinguish between the tables holding the teacher-supplied data, defining quizzes and questions, and the tables storing all the data that is generated when students interact with the quizzes and questions.

A further simplification is possible by separating out the questiontype specific tables. They are logical extensions to other tables and therefore are not necessary for understanding the general basic model. They are therefore explained on the developer documentation page for the individual [[Quiz developer docs#Question types|question types]].

The diagram below shows how the most important tables are linked to one another.

[[image:Quiz_database_tables.gif]]

==Teacher-supplied data==

===quiz===

The quiz table contains the definition for all the quizzes. Each quiz belongs to a course, reflected by the course id, has a name and a short descriptive text (intro), an opening and a closing time and several fields that store the settings of various quiz options, each of which is explained in the quiz help that is linked to from the quiz settings page.

The only field that requires additional information is the optionsflag, which... I will put an explanation here eventually --[[User:Gustav|Gustav]] 06:02, 5 February 2006 (WST)

For quizzes that contain random questions the $quiz object may acquire an additional property
;questionsinuse
:A comma separated list of questions that are being used in the quiz. This is used by the random questiontype to avoid choosing a question that is already being used.

===quiz_questions===

This table constitutes the item or question bank, i.e. the repository of defined questions. The quiz_questions table defines the data that is common to questions of all types.

;id
:int(10) NOT NULL auto_increment,
:Primary key. This is used as a foreign key in many other tables. for example the quiz_answers table allows to define an arbitrary number of answers that are part of the question. And many questiontypes have their own tables that hold more information about the question.

;category
:int(10) NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_categories|quiz_categories]]

;parent
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. This field is set to zero except in the case of wrapped questions as they are used for example in the multianswer questiontype. When a question wraps around any number of subquestions the subquestions will have their parent id field set to the id of the main question, thus allowing the question to find all its sub-questions (or wrapped questions). If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself. This is also used for hiding random questions from the question list. Their parent field is simply set to their own id.

;name
:varchar(255) NOT NULL default '',
:Question name that is used in question lists on the quiz editing pages

;questiontext
:text NOT NULL,
:Main text of the question

;questiontextformat
:tinyint(2) NOT NULL default '0',

;image
:varchar(255) NOT NULL default '',

;defaultgrade
:int(10) unsigned NOT NULL default '1',
:Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.

;penalty
:float NOT NULL default '0.1',
:The penalty that is applied (if the respective quiz option is set) for an incorrect attempt at the question.

;qtype
:smallint(6) NOT NULL default '0',
:The questiontype of the question. (Constants are defined in locallib.php)

;length
:int(10) unsigned NOT NULL default '1',
:This defines how many question numbers are required for this question. It is generally set to "1", but the description questiontype, for example, sets it to "0", reflecting the fact that it doesn't have a question number.

;stamp
:varchar(255) NOT NULL default '',
:Unique identifier

;version
:int(10) NOT NULL default '1',
:A number representing how often the question was edited.

;hidden
:int(1) unsigned NOT NULL default '0',
:Controls whether to display a question in the question bank list in edit.php. Hiding questions is a mechanism to "delete" questions without removing them from the database and thus to allow them to be restored or "unhidden" at a later stage. Also the (unfinished and disabled) [[Quiz_developer_docs#Question_versioning|versioning feature]] uses the hidden field to prevent older versions of a question from cluttering the user interface.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of the static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these later fields can differ when a question is used in different quizzes.

The runtime fields are added to question objects with the function <code>quiz_get_questions_options()</code> is called. This in turn calls the questiontype specific <code>get_question_options()</code> method for to add the options field.

;maxgrade
:This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in the [[#quiz_question_instances|quiz_question_instances table]].

;instance
:Foreign key: refers to an id in the table [[#quiz_question_instances|quiz_question_instances]]

;options
:Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the <code>get_question_options</code> method.

;name_prefix
:The prefix to be used on all interactions printed as part of the question.

We now deal in alphabetical order with the remaining tables for the teacher-provided data.

===quiz_answers===

This table allows a common way to store one or more teacher-defined answers for each question. It is not mandatory for a questiontype to make use of this table however. A questiontype may choose to store it's teacher-defined answers in an entirely different way, or even to do away with teacher-defined answers and use some other method to mark the student-supplied answer. For example it could calculate the correct answer on the fly.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to [[#quiz_questions|quiz_questions]] table.

;answer
:text NOT NULL,
:The string that represents the teacher-defined answer that will be compared to the student responses for grading and feedback purposes. The format of this field is entirely up to the question type.

;fraction
:varchar(10) NOT NULL default '0.0',
:The fraction of the total mark that the student should earn for giving this particular answer. This could be a negative number for wrong answers. Note that it is stored in a varchar(10) field.

;feedback
:text NOT NULL,
:Text that can be displayed to student as feedback when the student's responses match this particular answer.

In the past there was also a sequence number field was sometimes used to store the order of the different answers and was set to '0' if the order was of no importance.

===quiz_categories===

Categories are provided as a way to organize questions. Each category has a name and a descriptive text (info) and the sortorder as metadata. Categories allow hierarchical nesting via the parent id and can be private or published, i.e. they can be made available to teachers in other courses.

Since categories are simply a means for organising questions they are not vital for understanding how the quiz module works.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;course
:int(10) unsigned NOT NULL default '0',
:Foreign key to the course table

;name
varchar(255) NOT NULL default '',

;info
:text NOT NULL,

;publish
:tinyint(4) NOT NULL default '0',

;stamp
:varchar(255) NOT NULL default '',

;parent int(10)
:unsigned NOT NULL default '0',

;sortorder int(10)
:unsigned NOT NULL default '999',

===quiz_numerical===

The quiz_numerical table belongs to the numerical questiontype and is an extension of the quiz_answers table, defining a tolerance value for each answer.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
;answer :int(10) unsigned NOT NULL default '0',
;tolerance :varchar(255) NOT NULL default '0.0',

===quiz_numerical_units===

The quiz_numerical_units table is used by the numerical questiontype and the calculated questionype. It extends the quiz_questions table, defining an arbitrary number of units that can be used in the responses.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
;multiplier :decimal(40,20) NOT NULL default '1.00000000000000000000',
;unit :varchar(50) NOT NULL default '',

===quiz_question_instances===

Questions can be assigned different grades in different quizzes. These are stored in this table.

While, after a small extension, this table could also fulfill the purpose of storing the order of the questions in a quiz, this is currently still done in the questions field in the [[#quiz|quiz]] table.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz|quiz]] table.

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key to the id of the [[#quiz_questions|quiz_questions]] table.

;grade
:smallint(6) NOT NULL default '0',
:The maximum grade assigned to this question in this quiz. This grade was set by the teacher on the [[mod/quiz/edit|quiz editing page]]. At runtime this information is stored in the $question->maxgrade field.

===quiz_question_versions===

This feature is not finished and disabled. The table structure may still change. See [[Quiz developer docs#Question versioning]] for a discussion.

;id
:int(10) unsigned NOT NULL auto_increment,

;quiz
:int(10) unsigned NOT NULL default '0',

;oldquestion
:int(10) unsigned NOT NULL default '0',

;newquestion
:int(10) unsigned NOT NULL default '0',

;userid
:int(10) unsigned NOT NULL default '0',

;timestamp
:int(10) unsigned NOT NULL default '0',

==Student-created data==

===quiz_attempts===

In the quiz_attempts table a record is created each time a user starts an attempt at a quiz. This is one of the important tables and the corresponding $attempt object is passed between many of the quiz module functions and methods.

;quiz
:int(10) unsigned NOT NULL default '0',<br />The id of the quiz that is attempted
;userid
:int(10) unsigned NOT NULL default '0',<br />The id of the user who is attempting the quiz
;attempt
:smallint(6) NOT NULL default '0',<br>It is possible for a user to attempt a quiz several times, therefore the number of the attempt is stored in this field.
;sumgrades
:varchar(10) NOT NULL default '0.0',<br>The (unscaled) grade for the attempt, i.e. if the grades assigned to the questions add up to 8, but the maximum grade for the quiz is set to 10, then the sumgrades field can contain 8 at maximum.
;timestart
:int(10) unsigned NOT NULL default '0',<br>The timestart field is set to the current time when an attempt is started and is never changed afterwards.
;timefinish
:int(10) unsigned NOT NULL default '0',<br>The timefinish field is set to "0" initially and to the current time when the attempt is closed. This is exploited at several places in the code to determine whether an attempt has been closed or not (i.e. closed = timefinish > 0). For all other modifications of an attempt record the timemodified field should be changed as well.
;timemodified
:int(10) unsigned NOT NULL default '0',<br>This should be changed each time data in the record is modified.
;layout
:text NOT NULL,<br>a comma separated list of question ids, with a "0" denoting a page break. Usually the comma separated list ends with ",0".
;preview
:tinyint(3) unsigned NOT NULL default '0',<br>A flag that marks a teacher preview (i.e. an attempt by a user with teacher privileges) that may be automatically deleted when the quiz is previewed again, and which is not taken into account when viewing statistics.

===quiz_states===

States are saved for each interaction with a question. This allows a review of the complete history of a user's interactions with individual questions. The current state is the most important object used by the quiz module runtime code. This $state runtime object has a few additional fields not in the database that will be explained further down. The database fields are:

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;attempt
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_attempts|quiz_attempts]]

;question
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table [[#quiz_questions|quiz_questions]]. The attempt id and the question id together sufficiently identify a question instance that a state belongs to.

;originalquestion
:int(10) unsigned NOT NULL default '0',
:Foreign key: refers to an id in the table quiz_questions. It identifies which question was in use when the student attempted the question. This is part of the [[Quiz_developer_docs#Question_versioning|question versioning]] code.

;seq_number
:int(6) unsigned NOT NULL default '0',
:A counter that provides information about the sequence in which the states were created.

;answer
:text NOT NULL,
:This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses. Questiontypes are allowed to deviate from this and handle their response storage in any desired way. Some questiontypes do not use this field but instead store the student response in their own table extending this table.

;timestamp
:int(10) unsigned NOT NULL default '0',
:A timestamp to record when the state was created. This could mainly be useful for audit purposes.

;event
:int(4) unsigned NOT NULL default '0',
:Records the event or interaction type that lead from the previouse state to the current one. The field can take the value of any of the following constants (defined in locallib.php):
:*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.

;grade
:varchar(10) NOT NULL default '0.0',
:Calculated from the raw grade by deducting the penalty and rescaling to the defaultgrade value of the question. Note that this is a varchar(10) field like most grade-related fields in the quiz module.

;raw_grade
:varchar(10) NOT NULL default '',
:The grade that was achieved for the question scaled to the question's weight or grade as assigned in the quiz_question_instances table

;penalty
:varchar(10) NOT NULL default '0.0',
:The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous marking events.

In addition to the database fields a few fields are added to the states at runtime. They are dealt with by the questiontypes with the methods <code>create_session_and_responses</code>, <code>restore_session_and_responses</code> and <code>save_session_and_responses</code> and are defined as follows.

;sumpenalty
:The cumulative penalty, which can be calculated by adding up all the penalties from previous marking events. For efficiency these cumulative penalties are stored in the table [[#quiz_newest_states|quiz_newest_states]] so that they do not need to be re-calculated each time.

;changed
:This records whether a change has taken place to the runtime state. This is set to false when the state is restored from the database. Any code which changes the question state must set this field to true amd must increment seq_number. The <code>quiz_save_question_session()</code> function will save the new state object to the database if the field is set to true.

;responses
:This is automatically set to the value of the database field <code>answer</code> before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indicies are determined by the name of the elements after the name_prefix is stripped.

;last_graded
:This field contains another state object representing the most recent graded state in the history of this question attempt. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.

;options
:Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

We now deal in alphabetical order with the remaining tables holding the student-created data.

===quiz_grades===

The quiz_grades table merely stores a student's awarded grade for a quiz. Since it is possible to allow several attempts on a quiz, the grade stored is calculated depending on the quiz setting grademethod. This table exists mainly for convenience, because the values of its fields can be recalculated.

;id
:int(10) unsigned NOT NULL auto_increment,
:Primary key

;quiz
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the [[#quiz|quiz]] table

;userid
:int(10) unsigned NOT NULL default '0',
:Foreign key refering to the id of the user table

;grade
:double NOT NULL default '0',
:The grade awarded for this quiz to this user

;timemodified
:int(10) unsigned NOT NULL default '0',
:Unix timestamp to be updated each time the grade is changed

===quiz_newest_states===

This table exists only for efficiency reasons:
#Via its 'newest' and 'newgraded' fields it gives attempt.php a way to quickly find the newest state and the newest graded state for an attempt. It allows the construction of SQL to select all the states that need to be loaded on attempt.php or review.php.
#Via its 'sumpenalty' field it gives quiz_apply_penalty() a quick way for getting at the accumulated penalty that needs to be applied. Without this field the penalties from all previous graded states would have to be added up each time. Not a big deal actually because this could be achieved with a single SQL query (using SUM) but this field was introduced when we still had the multiplicative penalty scheme around which would have been more difficult to recompute.

This table was introduced in Moodle 1.5 and is not populated for all states during the upgrade because on sites with a lot of existing states that could take too long. Rather it is done whenever needed by quiz_upgrade_states().

;id
:int(10) unsigned NOT NULL auto_increment,
Primary key

;attemptid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_attempts|quiz_attempts]] table

;questionid
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_questions|quiz_questions]] table

;newest
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state for this attempt and this question.

;newgraded
:int(10) unsigned NOT NULL default '0',
Foreign key refering to the id in the [[#quiz_states|quiz_states]] table. This points to the newest state created by a grading event.

;sumpenalty
:varchar(10) NOT NULL default '0.0',
This stores the total penalty that this user has accumulated over previous graded responses to this question in this attempt.

[[Category:Developer]]
[[Category:Quiz]]

Development:Dataset dependent

2006-02-05T23:41:00Z

Gustav: /* Database tables */

Development:Dataset dependent

2006-02-05T23:38:13Z

Gustav:

{{Questiontype developer docs}}
This is an abstract questiontype that is currently only used by the calculated questiontype.

==Database tables==

==Response storage==

==Question->options==

==State->options==

[[Category:Developer]]
[[Category:Quiz]]