MoodleDocs - User contributions [en]

Development:Quiz attempt

2009-07-16T10:18:17Z

Arunjohnruben: added an 'i' to a word

{{Quiz developer docs}}The attempt.php script is one of the most complicated scripts of the quiz module. It is responsible for displaying questions to a user, to evaluate and grade the users' responses and additionally it needs to take various quiz settings into account and change the behaviour of the script accordingly. This script, which is vital for the functioning of the quiz module, is explained in this document in some detail in order to provide some context and examples for the use of the question/state model and to illustrate some of the functions provided in locallib.php.

In addition to the immediate benefit of explaining what happens in attempt.php, this piece of documentation should provide an entry point to the quiz module code. A number of functions are used in attempt.php that are likely to be used in other scripts as well.

Although the attempt.php script is useful for understanding how user interactions are handled, in order to gain an understanding of the teacher interface for editing quizzes and questions you should look at edit.php.

This file describes the situation up to Moodle 1.9. For Moodle 2.0 and later, Attempt.php was split into several bits as shown on [[Development:Quiz_user_interface_overview]]. However, the code still does the same things, just in smaller, better organised pieces. (See also http://moodle.org/mod/forum/discuss.php?d=68922.)

== A simplified perspective ==

From a simple functional point of view, the responsibilities of attempt.php is the handling of attempts at a quiz. This includes displaying questions and storing data provided or generated by the users. The interaction could be limited to opening the page and thus creating a new attempt and submitting the responses back to the server, which causes the responses to be graded. While the script is actually more sophisticated and allows to interrupt and continue attempts, this two step scenario provides a good starting point and covers the core functionality.

=== Starting a new attempt ===

When a new attempt is started the attempt object is created by the function <code>quiz_create_attempt()</code> (line 183). It returns an empty <code> $attempt</code> object, which is stored in the database immediately to record the fact that the student has seen the questions.

The next step is to load up all questions and to create initial states for all of them. Loading up the questions is a two step process: first the question records are extracted from the database, then the function <code> quiz_get_questions_options()</code> is called. This attaches the name_prefix field and calls the questiontype specific <code>get_question_options()</code> method for each question record in order to add any required data.

// Load the questions
if (!$questions = get_records_sql($sql)) {
...
}
// Load the question type specific information
if (!quiz_get_question_options($questions)) {
...
}
// Restore the question sessions to their most recent states
// creating new sessions where required
if (!$states = quiz_get_states($questions, $attempt)) {
...
}

After all questions are correctly initialised a state object is created for each by the function <code>quiz_get_states()</code>. This function is responsible for providing a state for each question and creates a new state if there isn't one to be restored. Any newly states are added to the database right away.

At this point all the required data has been generated or loaded, so the last step is to print the page. The printing happens towards the end of the attempt.php script and, apart from a simple call to <code>print_heading()</code> (line 409), is done in a loop through all the question records by calling <code> quiz_print_quiz_question()</code> (line 461), which is just a shorthand for calling the questiontype specific <code>print_question()</code> method. So, quite conveniently, each question is responsible for printing itself. To round up the printing, submit buttons and a footer are printed to the bottom of the page.

=== Processing responses ===

The next logical step after creating and displaying an attempt is that the user enters answers for all questions and submits them for marking. Now it is not necessary to create a new attempt, because there is already an open existing one in the database and the same holds for each question's state. So this time the attempt record is loaded from the database. The questions are loaded in the same way, by querying for the question records an then attaching any required questiontype specific fields by calling the function <code> quiz_get_question_options()</code>. Now the call to the function <code> quiz_get_states()</code> does actually restore the states from the database rather than generate new ones, so the same code works for the two scenarios, creating and closing an attempt.

Now that all data concerning the attempt under discussion has been loaded, the responses submitted by the student come to the scene. For each question they need to be evaluated and graded. The first step here is to determine how to deal with each question and the associated responses. In the simplified case this is clear; all responses need to be graded, the grades stored and then the attempt needs to be closed. However, there are more complicated cases, so the function <code> quiz_extract_responses()</code> is called to create the <code>$actions</code> array, which acts as a set of instructions for the function <code>quiz_process_responses()</code>, a quite complicated function, which encapsulates the entire response processing for one question and calls out to the questiontype specific <code>grade_responses()</code> method for grading.

After all submitted responses have been processed, the questions are rendered in the new states. An exception is if the student has requested to close the attempt (or if it is closed automatically due to a time limit). In this case the attempt is closed by setting the <code>timefinish</code> field to the current time. After this the user is redirected to review.php, which, depending on the quiz review settings, shows the questions including the student's responses, feedback, grades and correct answers.

== A more complicated perspective ==

Before an attempt may be started there are a series of mandatory and optional checks, to determine if the user is allowed to attempt the quiz. In addition to these checks, the page display and functionality are slightly different for users with and without teacher privileges. Also, when the quiz is set to start in "secure" mode (the $quiz->popup option), the printing of the page is slightly different. Including all of these scenarios evidently complicates the structure of the attempt.php script, deviating from the simple scenario described above.

First of all, access to the quiz is denied to guests. Additionally it is possible to restrict access to an IP range ($quiz->subnet) and to set up a password for the quiz ($quiz->password). In both cases users that can't pass the required tests are denied access.

When a teacher "attempts" a quiz there is a tab navigation facility at the top of the page, which allows the teacher to jump between reviewing, previewing and editing the quiz (and possibly even more options). The teacher interface also contains a button to start a new attempt, which is not present on the student interface. Teachers' attempts are automatically marked as previews, which means that old attempts are automatically deleted when a new attempt is started. It also prevents previews to show up in the students' answers review and preview attempts don't block the possibility of editing the quiz, while students' attempts do.

Further complication is introduced by the feature to allow multiple pages with questions and navigation between these pages. This requieres mechanisms to determine which questions are on which page, which page is currently displayed and which page needs to be viewed next. This is not too hard to achieve, however, one subtlety should be noted: when the attempt is closed it is necessary to load all questions and their most recent states before they are marked, whereas in the case of navigation only the questions and related states of the page that was displayed before are loaded, processed and saved; and the questions and states for the next page are loaded.

Towards the end of the script there are two blocks of code that are responsible for timed quizzes ($quiz->timelimit). The first block prints the start element of the form using javascript to make sure that javascript is enabled (which obviously doesn't help a lot, because the quiz is printed as usual, only the submit won't work). The second block includes the file jstimer.php, which prints a timer that counts down and causes an auto-submit when time is up.
[[Category:Quiz]]

Development:Installing and upgrading plugin database tables

2009-07-13T05:33:28Z

Arunjohnruben:

==Introduction==

If you have done the right thing, Moodle will automatically create the database tables for your plugin when you visit the Admin notifications page (.../admin/index.php). This process is controlled by three files within your plugin:
;version.php : This records the version of the plugin code
;db/install.xml : This is used when someone installs your plugin for the first time.
;db/upgrade.php : This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin.

In Moodle 1.9 and before, this is stored in the mdl_config table, in a row with the name ''plugintype''_''pluginname''_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

In Moodle 2.0 an beyond, plugin version numbers are stored in the mdl_config_plugins table, with ''plugintype''_''pluginname'' in the plugin column, and 'version' in the name column - with the same exception for modules and blocks.

==A specific example==

For the rest of this document, I will use a particular example, because it should make the explanation easier. You should be able to see how to generalise it.

We will suppose you that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the qtype_myqtype_version row of the mdl_config table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_question_myqtype, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_question_myqtype table.

==The files you need for the first release==

In what follows, the bits of code you need to replace are '''in bold'''.

;version.php
$plugin->version = 2008080100;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml
:This file, which you should [[XMLDB editor|create with the XMLDB editor]], should contain the definition for your mdl_question_myqtype table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

==The files you need for the second release==

;version.php
$plugin->version = 2008080200;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml : This file should now contain the updated definition for your mdl_question_myqtype table, with three columns col1, col2 and newcol. You modify this file using the XMLDB editor.
;db/upgrade.php
:This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_question_myqtype table. You don't have to write this code yourself as the XMLDB editor will generate it for you. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:
function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
$result = true;

/// Add a new column newcol to the mdl_question_myqtype
if ($result && $oldversion < 2008080200) {
'''// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.'''
}

return $result;
}

''Hint: If you are modifying or adding a field/table, get the XMLDB editor to generate the PHP update code for you '''after''' making the changes in the editor. If you are deleting one, you need to generate the PHP code '''before''' making the change - or you won't be able to select the field/table to write the code for, because it no longer exists.''

==What happens when a user installs or upgrades your plugin==

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/adminlib.php and reading this code is the best way to find out exactly what happens. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
// For the body of this loop, suppose the current plugin being processed is myqtype.

Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.php exist.

if ($CFG->qtype_myqtype_version exists, and is less than the number in version.php) {
Call the upgrade function xmldb_qtype_myqtype_upgrade from
upgrade.php, passing the old version number ($CFG->qtype_myqtype_version)
which says what is currently installed
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}

else if ($CFG->qtype_myqtype_version does not exist) {
Create the tables from the definitions in install.xml
Update $CFG->qtype_myqtype_version to the latest number from version.php
to record what is currently installed
}
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works.

Let us now look at some worked examples:

===User installs version 2008080100 of myqtype===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

===User upgrades from version 2008080100 to version 2008080200 of myqtype===

To start with, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

# The user will delete the old question/type/myqtype folder.
# The user will unzip the new myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables (qtype_myqtype_version) is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_question_myqtype table will now have three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

===User installs version 2008080200 of myqtype into a clean Moodle install===

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

# The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

==Summary==

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no ''plugintype''_''pluginname''_version value in the mdl_config table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the ''plugintype''_''pluginname''_version value in the mdl_config table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

==Database upgrades and stable branches==

The simple rule is, never make any database changes on a stable branch. You only need to read this section in the rare situations where a database change on the stable branch is unavoidable.

'''Warning!!! advanced material follows.'''

Suppose, in order to fix a bug, you need to make a database change in Moodle 1.9.3+ (which must also be merged into HEAD). The root of the problem is that people may upgrade their Moodle in three different ways, which

* Upgrade from <=1.9.3 to 1.9.4 - this executes the ugprade script on the 1.9 branch.
* Upgrade from <=1.9.3 directly to >=2.0 - this executes the upgrade script on the HEAD branch.
* Upgrade from 1.9.4 to >=2.0 - in this case, you must ensure that the upgrade on HEAD is not executed.

The normal way to do this is ensure that your database upgrade is idempotent. That is, it does not matter if you do it twice. So for example, instead of doing

$dbman->create_table($table);

you should do

if (!$dbman->table_exists($table)) {
$dbman->create_table($table);
}

You should also think about what version numbers to put in your version.php file on each branch. Above all, test carefully.

==See also==

* [[Development:XMLDB_Documentation|XMLDB_Documentation]]
* [[Development:Coding|Coding guidelines]]
* [[Development:DDL functions|DDL functions]]
* [[Development:XMLDB defining an XML structure|install.xml file documentation]]

[[Category:Developer]]
[[Category:XMLDB]]
[[Category:Installation]]

Development:Quiz user interface overview

2009-07-11T08:21:22Z

Arunjohnruben:

{{Quiz developer docs}}This diagram summarises the various pages that make up the quiz user interface. Or at least what the situation will be in Moodle 2.0 - a proposed refactor got delayed. The changes compared to previous version are indicated in the diagram - but because of the delay, it has 1.9 where it should have 2.0.

[[Image:Quiz_interface_overview.png]]

[[Category:Quiz]]

Development:NEWMODULE Documentation

2009-07-07T09:43:16Z

Arunjohnruben:

{{Template:Work in progress}}
{{New_Module}}

This first draft of Moodle Docs page about the creation of a new module is divided into the following sections:

*[[Development:NEWMODULE Tutorial]]
*[[Development:NEWMODULE Reference]]
*[[Development:NEWMODULE FAQ]]
*[[Development:NEWMODULE Adding capabilities]]

----

Danielle, did you know about [[Development:Modules]], which is linked to from [[Developer_documentation#Make_a_new_plugin]]? You may be better off editing that, rather than starting a new page. However don't let me discourage you. That documentation is very limited, and badly needs to be expanded, so it is absolutely brilliant that you want to work on it.--[[User:Tim Hunt|Tim Hunt]] 12:03, 28 March 2008 (CDT)

::Good point Tim! Anyway... I think we can use this as temporary root for Daniele's work and then, simply, move things to their final place. Let's see how this evolves. -- [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 12:33, 28 March 2008 (CDT)

----

[http://lyceum.open.ac.uk/temp/creating_moodle_modules.ppt My powerpoint about creating moodle modules] is a bit old (1.8) and maybe not that comprehensible but I use it when I'm trying to explain things to people. It includes a list of all the things you need to have in a module, except the ones I forgot (backuplib iirc is missing). [[User:sam marshall|sam marshall]] 12:52, 28 March 2008 (CDT)

::That's really great, Sam. For sure that presentation will help.Thanks! -- [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 13:08, 28 March 2008 (CDT)

==See also==

* [http://dev.moodle.org/course/view.php?id=2 Moodle Developers' Course]
* [[Development:Modules]]
* [[Development:Places to search for lang strings|Where to put language strings for your plugin]]
* [[Development:Installing and upgrading plugin database tables|Defining the database tables for your plugin]]

{{CategoryDeveloper}}
[[Category:Developer|Modules]]

error/debug/codingerror

2009-07-03T08:56:36Z

Arunjohnruben:

When trying to move a course into another category