MoodleDocs - Användarbidrag [sv]

Dataset dependent

2007-06-30T00:42:21Z

Fulano2040: /* question_dataset_definitions */

{{Questiontype developer docs}}

==Database tables==

===question_dataset_definitions=== Organises and stores properties for dataset items

This table is an indirect extension to the question table, because the 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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
this can be 1=LITERAL 2=FILE 3=LINK
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===question_dataset_items=== Individual dataset items

Dataset items can be created for each dataset. The dataset_items table stores these possible values for the variables defined in the dataset_definitions table.

;id :int(10) unsigned NOT NULL auto_increment,
;definition :int(10) unsigned NOT NULL default '0',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

The question_datasets table is used by dataset dependent question types (i.e. calculated) to link datasets to questions.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
id from the question table
;datasetdefinition :int(10) unsigned NOT NULL default '0',
id from the question_dataset_definitions table

==Response storage==

==Question->options==

==State->options==

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

Dataset dependent

2007-06-30T00:41:07Z

Fulano2040: /* question_datasets */

{{Questiontype developer docs}}

==Database tables==

===question_dataset_definitions=== Organises and stores properties for dataset items

This table is an indirect extension to the question table, because the 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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===question_dataset_items=== Individual dataset items

Dataset items can be created for each dataset. The dataset_items table stores these possible values for the variables defined in the dataset_definitions table.

;id :int(10) unsigned NOT NULL auto_increment,
;definition :int(10) unsigned NOT NULL default '0',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

The question_datasets table is used by dataset dependent question types (i.e. calculated) to link datasets to questions.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
id from the question table
;datasetdefinition :int(10) unsigned NOT NULL default '0',
id from the question_dataset_definitions table

==Response storage==

==Question->options==

==State->options==

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

Dataset dependent

2007-06-13T17:52:29Z

Fulano2040: /* question_dataset_items */

{{Questiontype developer docs}}

==Database tables==

===question_dataset_definitions=== Organises and stores properties for dataset items

This table is an indirect extension to the question table, because the 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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===question_dataset_items=== Individual dataset items

Dataset items can be created for each dataset. The dataset_items table stores these possible values for the variables defined in the dataset_definitions table.

;id :int(10) unsigned NOT NULL auto_increment,
;definition :int(10) unsigned NOT NULL default '0',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

The question_datasets table is used by dataset dependent question types (i.e. calculated) to link datasets to questions.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
id from the question table
;datasetdefinition :int(10) unsigned NOT NULL default '0',
id form the question_dataset_definitions

==Response storage==

==Question->options==

==State->options==

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

Dataset dependent

2007-06-13T17:51:40Z

Fulano2040: /* question_dataset_items */

{{Questiontype developer docs}}

==Database tables==

===question_dataset_definitions=== Organises and stores properties for dataset items

This table is an indirect extension to the question table, because the 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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===question_dataset_items=== Individual 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 dataset_definitions table.

;id :int(10) unsigned NOT NULL auto_increment,
;definition :int(10) unsigned NOT NULL default '0',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

The question_datasets table is used by dataset dependent question types (i.e. calculated) to link datasets to questions.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
id from the question table
;datasetdefinition :int(10) unsigned NOT NULL default '0',
id form the question_dataset_definitions

==Response storage==

==Question->options==

==State->options==

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

Dataset dependent

2007-06-13T17:51:12Z

Fulano2040: /* question_datasets */

{{Questiontype developer docs}}

==Database tables==

===question_dataset_definitions=== Organises and stores properties for dataset items

This table is an indirect extension to the question table, because the 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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===question_dataset_items=== Individual 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',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

The question_datasets table is used by dataset dependent question types (i.e. calculated) to link datasets to questions.

;id :int(10) unsigned NOT NULL auto_increment,
;question :int(10) unsigned NOT NULL default '0',
id from the question table
;datasetdefinition :int(10) unsigned NOT NULL default '0',
id form the question_dataset_definitions

==Response storage==

==Question->options==

==State->options==

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

Dataset dependent

2007-06-13T17:47:08Z

Fulano2040: /* question_dataset_definitions */

{{Questiontype developer docs}}

==Database tables==

===question_dataset_definitions=== Organises and stores properties for dataset items

This table is an indirect extension to the question table, because the 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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===question_dataset_items=== Individual 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',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

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]]

Dataset dependent

2007-06-13T17:45:22Z

Fulano2040: /* quiz_dataset_items */

{{Questiontype developer docs}}

==Database tables==

===question_dataset_definitions=== Organises and stores properties for dataset items

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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===question_dataset_items=== Individual 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',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

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]]

Dataset dependent

2007-06-13T17:45:09Z

Fulano2040: /* quiz_dataset_definitions */

{{Questiontype developer docs}}

==Database tables==

===question_dataset_definitions=== Organises and stores properties for dataset items

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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===quiz_dataset_items=== Individual 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',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

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]]

Dataset dependent

2007-06-13T17:44:47Z

Fulano2040: /* quiz_question_datasets */

{{Questiontype developer docs}}

==Database tables==

===quiz_dataset_definitions=== Organises and stores properties for dataset items

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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===quiz_dataset_items=== Individual 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',
id corresponding to the question_dataset_definitions table
;number :int(10) unsigned NOT NULL default '0',
;value :varchar(255) NOT NULL default '',

===question_datasets=== Many-many relation between questions and dataset definitions

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]]

Dataset dependent

2007-06-13T17:42:50Z

Fulano2040: /* quiz_dataset_items */

{{Questiontype developer docs}}

==Database tables==

===quiz_dataset_definitions=== Organises and stores properties for dataset items

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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===quiz_dataset_items=== Individual 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',
id corresponding to the question_dataset_definitions table
;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]]

Dataset dependent

2007-06-13T17:40:16Z

Fulano2040: /* quiz_dataset_definitions */

{{Questiontype developer docs}}

==Database tables==

===quiz_dataset_definitions=== Organises and stores properties for dataset items

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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===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]]

Dataset dependent

2007-06-13T01:04:26Z

Fulano2040: /* 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',
when this is a shared dataset the value is the category id
when this is a private dataset the value is 0
;name :varchar(255) NOT NULL default '',
;type :int(10) NOT NULL default '0',
;options :varchar(255) NOT NULL default '',
the options for this dataset separated by ':'(distribution:min:max:decimals)
;itemcount :int(10) unsigned NOT NULL default '0',
the number of dataset items

===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]]

Broken/Question engine

2007-06-13T00:13:58Z

Fulano2040: /* Sessions, States, Events */

Moodle has a powerful question engine with a modular structure to allow question type plug-ins. The question engine is responsible for rendering the questions and for processing student responses. It is used by the [[Quiz developer docs|quiz module]] and it is planned that in future it will be used by the Lesson and other modules.

Historically the question engine started as a part of the quiz module. Only since Moodle 1.6 is it a separate core component of Moodle that can be used by any other Moodle component or module. During this restructuring the code was moved from mod/quiz/ to question/ and the tables and functions were renamed. Wherever the old table or function name contained 'quiz_' the new one will contain 'question_'

==Terminology==

When talking about the question engine 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''' is the set of definitions (question name, question text, possible answers, grading rules, feedback, etc.) that constitute a reusable assessment item. So it includes much more than what one would in everyday language call a question.
In the terminology of the QTI specification a 'question' is more 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 '''[[Question engine#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 questions that interact with the student by going through several states depending on the student 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', in which case Moodle provides buttons to mark each question individually.

===Answers===

In Moodle the term ''''answer'''' is used exclusively for the '''teacher-defined answers''' of a question. 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. 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 question_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 a quiz" (or another activity involving questions). 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.

Each module that uses the question engine should hold its own data for the attempts in its own tables. When the module calls the question engine functions it is often expected to pass an attempt object.

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 ''''question sessions'''' or sometimes 'attempts at a question, never just as 'attempts'.

===Sessions, States, Events===

When a new attempt is started, a new '''session''' is started for each question. So in a sense a session is for a question what an attempt is for a whole quiz. A question session lasts no longer than an attempt and for each question there can only by one session within one attempt.

Moodle allows the student to interact with a question repeatedly within one session and each such interaction leads to a new '''state'''. The first state is created when the session is created. A new state is then created when a student saves, validates or submits an answer or .... The student's responses and, if appropriate, the results of response processing (grading) are stored in the new state that gets created.

The type of '''event''' that led to the creation of a particular state is saved along with the state. The types of events currently used are:
;open :A new session has just been created and this is the opening state. Usually it doesn't hold student responses yet (except where a quiz attempt is based on a previous attempt because the 'attemptonlast' option is set).
;save:The student has clicked the save button.
;validate:The student has asked for his responses to be validated. This means it is checked that they are valid responses. In the case of mathematical questions which requires the input of a mathematical expression in some linear format the question type may want to display the validated result back to the student in typeset form. Similar things may apply to other subject-specific question types. If a student response is found to be invalid the student is told so but no penalty is applied. The invalid response is stored with the state.
;grade:The student has pressed the submit button. The grade is calculated and stored with the attempt.
;duplicategrade:The student has pressed the submit button but the response to this question has not actually changed. This happens a lot in quizzes with several questions on one page where the student may have changed the responses for one question only. I believe that states created by this type of event are not stored in the database.
;close:The last state in a session which is now closed. Currently a session closes only when the attempt closes, either because the student requests it or because the timelimit elapses.

There are now plans to introduce another event type
;submit:The student has submitted his responses for grading but grading has not yet taken place. This will be used by teacher-marked question types like the essay questions for example.

==Code documentation==

The code is documented according to [http://www.phpdoc.org/ PHPdocumentor] 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

Code is organised into packages
* Package questionbank - code that relates to the questionbank system
** Subpackage questiontypes - code that relates to the question types, including the question type base class.
** Subpackage importexport - code that relates to importing and exporting questions.

Generally, the base classes default_questiontype and qformat_default should contain most of the documentation, since all question types should follow the same interface. There is no value in repeating the same information on all the various subclasses. The subclasses should concentrate on describing any new methods they have that do not come from the base class.

See the [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html#coding.phpcomments PHPdocumentor manual] for more advice on writing good comments.

Moodle PHPdocs can be seen here: http://phpdocs.moodle.org/.

==API==

The library lib/questionlib.php contains 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 mod/quiz/locallib.php). Loading this library instantiates all questiontype classes by loading the questiontype.php files

A description of the API still needs to be written. Also lib/questionlib.php should be cleaned up a bit to distinguish between the API functions and the helper functions.

==Organisation==
The default questiontype class is defined in '''question/type/questiontype.php''' (in Moodle 1.5 this was still in mod/quiz/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.

While questiontypes are realized as classes, the question engine 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 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 one 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 question engine works is to understand how the different kinds of object work together. The most important ones are:

*Questions
*Attempts
*States

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

The Moodle quiz module allows students to make several attempts at a quiz. Data about such an '''attempt''' is stored in an attempt object. The Moodle question engine was optimized to deal with such attempts and therefore every module wanting to use the question engine also has to implement the attempt object and pass it to many of the question engine functions. The attempt object holds for example information about how the quiz was randomized for this attempt and the ordering of the questions and answers.

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. When the student first views a question within a particular attempt a '''question session''' and the first question state is created. Each time the student interacts with the question a new '''question 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 details about
*Database tables
*Response storage
*Question options object
*State options object
[[Development:Question type code flow]]

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 [[How to write a question type plugin]].

==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.

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

Broken/Question engine

2007-06-13T00:03:22Z

Fulano2040: /* Sessions, States, Events */

Moodle has a powerful question engine with a modular structure to allow question type plug-ins. The question engine is responsible for rendering the questions and for processing student responses. It is used by the [[Quiz developer docs|quiz module]] and it is planned that in future it will be used by the Lesson and other modules.

Historically the question engine started as a part of the quiz module. Only since Moodle 1.6 is it a separate core component of Moodle that can be used by any other Moodle component or module. During this restructuring the code was moved from mod/quiz/ to question/ and the tables and functions were renamed. Wherever the old table or function name contained 'quiz_' the new one will contain 'question_'

==Terminology==

When talking about the question engine 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''' is the set of definitions (question name, question text, possible answers, grading rules, feedback, etc.) that constitute a reusable assessment item. So it includes much more than what one would in everyday language call a question.
In the terminology of the QTI specification a 'question' is more 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 '''[[Question engine#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 questions that interact with the student by going through several states depending on the student 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', in which case Moodle provides buttons to mark each question individually.

===Answers===

In Moodle the term ''''answer'''' is used exclusively for the '''teacher-defined answers''' of a question. 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. 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 question_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 a quiz" (or another activity involving questions). 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.

Each module that uses the question engine should hold its own data for the attempts in its own tables. When the module calls the question engine functions it is often expected to pass an attempt object.

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 ''''question sessions'''' or sometimes 'attempts at a question, never just as 'attempts'.

===Sessions, States, Events===

When a new attempt is started, a new '''session''' is started for each question. So in a sense a session is for a question what an attempt is for a whole quiz. A question session lasts no longer than an attempt and for each question there can only by one session within one attempt.

Moodle allows the student to interact with a question repeatedly within one session and each such interaction leads to a new '''state'''. The first state is created when the session is created. A new state is then created when a student saves, validates or submits an answer or .... The student's responses and, if appropriate, the results of response processing (grading) are stored in the new state that gets created.

The type of '''event''' that led to the creation of a particular state is saved along with the state. The types of events currently used are:
;open :A new session has just been created and this is the opening state. Usually it doesn't hold student responses yet (except where a quiz attempt is based on a previous attempt because the 'attemptonlast' option is set).
;save:The student has clicked the save button.
;validate:The student has asked for his responses to be validated. This means it is checked that they are valid responses. In the case of mathematical questions which requires the input of a mathematical expression in some linear format the question type may want to display the validated result back to the student in typeset form. Similar things may apply to other subject-specific question types. If a student response is found to be invalid the student is told so but no penalty is applied. The invalid response is stored with the state.
;grade:The student has pressed the submit button. The grade is calculated and stored with the attempt.
;duplicategrade:The student has pressed the submit button but the response to this question has not actually changed. This happens a lot in quizzes with several questions on on page where the student may have changed the responses for one question only. I believe that states created by this type of event are not stored in the database.
;close:The last state in a session which is now closed. Currently a session closes only when the attempt closes, either because the student requests it or because the timelimit elapses.

There are now plans to introduce another event type
;submit:The student has submitted his responses for grading but grading has not yet taken place. This will be used by teacher-marked question types like the essay questions for example.

==Code documentation==

The code is documented according to [http://www.phpdoc.org/ PHPdocumentor] 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

Code is organised into packages
* Package questionbank - code that relates to the questionbank system
** Subpackage questiontypes - code that relates to the question types, including the question type base class.
** Subpackage importexport - code that relates to importing and exporting questions.

Generally, the base classes default_questiontype and qformat_default should contain most of the documentation, since all question types should follow the same interface. There is no value in repeating the same information on all the various subclasses. The subclasses should concentrate on describing any new methods they have that do not come from the base class.

See the [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html#coding.phpcomments PHPdocumentor manual] for more advice on writing good comments.

Moodle PHPdocs can be seen here: http://phpdocs.moodle.org/.

==API==

The library lib/questionlib.php contains 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 mod/quiz/locallib.php). Loading this library instantiates all questiontype classes by loading the questiontype.php files

A description of the API still needs to be written. Also lib/questionlib.php should be cleaned up a bit to distinguish between the API functions and the helper functions.

==Organisation==
The default questiontype class is defined in '''question/type/questiontype.php''' (in Moodle 1.5 this was still in mod/quiz/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.

While questiontypes are realized as classes, the question engine 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 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 one 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 question engine works is to understand how the different kinds of object work together. The most important ones are:

*Questions
*Attempts
*States

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

The Moodle quiz module allows students to make several attempts at a quiz. Data about such an '''attempt''' is stored in an attempt object. The Moodle question engine was optimized to deal with such attempts and therefore every module wanting to use the question engine also has to implement the attempt object and pass it to many of the question engine functions. The attempt object holds for example information about how the quiz was randomized for this attempt and the ordering of the questions and answers.

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. When the student first views a question within a particular attempt a '''question session''' and the first question state is created. Each time the student interacts with the question a new '''question 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 details about
*Database tables
*Response storage
*Question options object
*State options object
[[Development:Question type code flow]]

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 [[How to write a question type plugin]].

==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.

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

Groups FAQ

2007-06-06T00:41:04Z

Fulano2040: /* Can I use the same groups for more than one course? */

==General==
===What is the 'groups mode' setting?===

There are three different groups modes – No groups, Separate Groups, Visible Groups. In ‘Separate groups’ mode, each group can only see their own group – other groups are invisible. In ‘Visible groups’ mode, each group works in their own group, but can also see other groups.

===What is the 'force' setting?===

If force is set to yes, then all activities are group activities. This overrides any settings for individual activities. If force is set to no, then activities are only group activities if they have been set to group mode. In this case, each activity requires to be set to group mode individually.

===How do I assign a teacher to a group? Can a teacher be in more than one group?===

You can assign a teacher to a group in exactly the same way that you assign a student to a group. In 1.5, a teacher cannot be in more than one group. This has changed in 1.6.

===How do I restrict a teacher to view only information about the groups that they are in?===

For Separate Groups mode, if a teacher has edit rights set to yes, then they can see all groups. If a teacher has edit rights set to no, then they can see only the groups of which they are a member.

===What determines whether students can see a teacher's profile?===

A student can see the profile of all teachers that are members of their group or that have edit rights.

===I have two groups that meet on different days. Can I set up activities for different times for the two groups?===

Not currently. You can create a separate course for each class using backup and restore, though you do then have to update both courses.

===Can I use the same groups for more than one course?===

Not currently. There are two possible workarounds for this. The first is to give the students group enrolment keys, so they enrol themselves into the right group for each course. The other alternative is to create a master course with all the students enrolled and in the correct groups, and then to make each of the courses a metacourse based on that master course (although the metacourse documentation claims that metacourses do not preserve groups, this seems to have been used by some people). See the documentation on [[Metacourses]].

===Can a student be a member of more than one group? Is it possible to have students not in any group?===

In 1.5, a student cannot be a member of more than one group. This has changed in 1.6 - a student can be in more than one group. A student does not need to be in a group.

===If I have several groups, can I make a specific activity visible to just one of those groups?===

Not currently. You can however make a forum post visible to just one group.

===Can I have one set of groups for Activity A and another set of groups for Activity B?===

Not currently.

===Is it possible to view all the groups in a course as a list to print out?===

Not currently.

===When I try to add a student, they are always added to the first group, whichever group I select?===

Make sure that the students name does not include any punctuation. There is also a workaround – give each group a temporary name at the start of the alphabet, put your students in the group and then rename the group.

===How can I import a list of students into a group?===

Please check [[Upload users]].

===How can I sort students automatically into groups during enrolment?===

You can make use of enrolment keys. Set an enrolment key on the course settings page (to enforce the enrolment key dialog form when students enrol). That key is only for students who should not be in a group. On the screen for administering groups, you create your groups and by editing the settings of each group, you can add a different enrolment key for each group. When a student enrols, using an enrolment key that is connected to a certain group, the student will automatically be part of that group.

===How can I change the sort order of the participants?===

The admin can change the "fullnamedisplay" which will affect the sort order of participants.

Have your admin go to:

Administration >> Configuration >> Variables

Then under "User," see "fullnamedisplay."

(Tested using Moodle 1.6.3.)

===Groupings===
{{Moodle 1.9}}
In Moodle 1.9+, groupings will be introduced as a hierarchical entity one higher above groups. Groups normally exist within a grouping, but can also be orphan groups. However, administrators and course creators are advised to create all their groups within groupings.

===Orphan groups===
{{Moodle 1.8}}
An orphan group is simply a group that doesn't belong to any grouping.

==Activity modules and groups==

Different activity modules vary as to how they treat groups – some have better support for groups than others! In general if you have questions about how an activity supports groups, you’re advised to post in the forum for the activity module, and not the groups forum.

===What happens if I switch an activity from being in non-groups mode to being in groups mode?===

This depends on the activity module in question.

For forums, posts made before the forum is put into groups mode are visible to all students after you have put the forum into group mode. However students cannot reply to these posts if they have no group (i.e. blank).

===What happens if I change the groups for an activity in groups mode e.g. if I move a student from one group to another?===

Again this depends on the activity module. You may find that grades or activity logs are lost, so check for the specific activity module first.

===How do I post a message in a forum that only one group can see?===

Before you click 'Add a new topic', you need to choose the group from the Separate groups drop-down menu at the top left.

===As a teacher I want to put the same post in each group's forum with students able to reply to that post. How can I do this?===

You need to post the same message into the forum for each group. There is currently no way to do this in one go if you want students to be able to reply to your post. If you don't mind students not being able to reply, then you can of course just post the message to all participants.

[[Category:Teacher]]
[[Category:Groups]]
[[Category:FAQ]]

[[fr:FAQ des groupes]]
[[ru:FAQ по группам]]

Developer FAQ

2007-03-25T07:30:57Z

Fulano2040: /* How do I insert/retrieve records in the database, without creating my own database connections? */

{{FAQ}}

==Help for new coders==

===Where can "newbies" to Moodle get help?===

The [http://moodle.org/mod/forum/view.php?f=33 General developer forum]! Feel free to ask any question, no matter how basic or advanced. Many people ask different levels of question every day, and the community is generally welcoming and quick to respond.

==Moodle's database==

===Where can I see a schema for the structure of the Moodle database?===

When installing Moodle, the database tables are generated and updated by various db-handling scripts located in various places. There is no canonical schema representation, although the [[Coding#Database_structures | coding guidelines for database structure]] give an outline of the general approach.

The reason that the database information isn't stored in one place is because of Moodle's '''modular structure'''. Each activity module, for example, comes as a folder with script files inside. If the module needs to store information in the database, it must include scripts in a "db" subfolder which define and update the database structure.

==How to get/set information when writing new Moodle code==

===How do I find out the currently-logged-on user?===

The global object $USER, which contains the numeric $USER->id among other things.

===How do I find out the current course?===
The global object $COURSE, which contains the numeric $COURSE->id

===How do I insert/retrieve records in the database, without creating my own database connections?===

Always use the "datalib" functions, such as insert_record() or get_record(). Since Moodle 1.7 these are found in lib/dmllib.php. Using these functions helps with database abstraction (e.g. running on either MySQL or Postgres) as well as maintaining a single database connection. Moodle uses ADODB for database abstraction.

Look at [http://phpdocs.moodle.org/moodlecore/_lib---datalib.php.html the documentation for datalib.php] for the list of functions and details of use.

===How do I get/set configuration settings?===

To get config values you would typically access the global $CFG object directly, which is automatically created by the core Moodle scripts. To set these "main" config values use set_config($name, $value). The values are stored in the Moodle "config" database table, but these functions take care of cacheing on your behalf, so you should always use these rather than fetching the records directly.

There is also a second table of config settings specifically for plugins ("config_plugin"). These are not automatically loaded into the $CFG object, so to fetch these you would use get_config($plugin, $name). To set them use set_config($name, $value, $plugin).

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=55719 How does date / time in DB convert to real Date / Time?] forum discussion

[[Category: Developer]]
[[Category: FAQ]]

[[es:FAQ Desarrollador]]
[[fr:FAQ de développement]]