Question engine - Revision history

Finns: /* Question types */

2023-05-21T16:19:52Z

Question types

← Older revision		Revision as of 16:19, 21 May 2023
Line 149:		Line 149:
	[[Question type code flow]]		[[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]].		It is hoped that Moodlers will contribute a lot of non-core question types in the future. For this, see [https://docs.moodle.org/en/How_to_write_a_question_type_plugin Question type plugin how to].

	==Grades==		==Grades==

Mudrd8mz: Text replacement - "" to ""

2021-07-14T20:28:22Z

Text replacement - "</code>" to "</syntaxhighlight>"

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:02:51Z
Text replacement - "<code>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:02, 14 July 2021
				
Line 109:
Line 109:
==Response storage== ==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 student's responses to a question are stored in <syntaxhighlight lang="php">$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: 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 <syntaxhighlight lang="php">$state->responses</code> field, to convert from the runtime to the storage model and vice versa:



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



;<code>restore_session_and_responses()</code> ;<syntaxhighlight lang="php">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. :Loads the question type specific session data from the database into the <syntaxhighlight lang="php">$state</code> object, in particular it loads the responses that have been saved for the given <syntaxhighlight lang="php">$state</code> into the <syntaxhighlight lang="php">$state->responses</code> field.



;<code>save_session_and_responses()</code> ;<syntaxhighlight lang="php">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. :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 <syntaxhighlight lang="php">$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 generic quiz module code saves the contents form the <syntaxhighlight lang="php"><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 <syntaxhighlight lang="php"><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).   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 <syntaxhighlight lang="php"><nowiki>$state->responses['']</nowiki></code> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <syntaxhighlight lang="php">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. In the method <syntaxhighlight lang="php">restore_session_and_responses()</code> the serialized value can be read from <syntaxhighlight lang="php"><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== ==Response processing==
Line 132:
Line 132:
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. 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. 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 <syntaxhighlight lang="php">print_question_formulation_and_controls()</code>. The convention only dictates that the name of the control element(s) must begin with the value of <syntaxhighlight lang="php">$question->name_prefix</code>. The <syntaxhighlight lang="php">$question->name_prefix</code> is a string starting with "resp" followed by the question id and an underscore, e.g. <syntaxhighlight lang="php">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. 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 <syntaxhighlight lang="php">respXX_</code>. Upon submission, the function <syntaxhighlight lang="php">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 <syntaxhighlight lang="php">$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. The function <syntaxhighlight lang="php">quiz_process_responses()</code> in turn calls the questiontype specific method <syntaxhighlight lang="php">grade_responses()</code> to assign a grade to the submitted responses and <syntaxhighlight lang="php">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 <syntaxhighlight lang="php">$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. Finally, the methods <syntaxhighlight lang="php">restore_session_and_responses()</code> and <syntaxhighlight lang="php">save_session_and_responses()</code> also need to know the questiontype specific layout of the <syntaxhighlight lang="php">$state->responses array</code> and restore or save the information, e.g. by converting from or to the data representation.



==Question types== ==Question types==



Rcollman: Question engine upgrade helper
2011-07-18T17:50:22Z
Question engine upgrade helper

				
				
				
				
				
				← Older revision
				Revision as of 17:50, 18 July 2011
				
Line 253:
Line 253:



All the other functions are really just about dispatching the request to the right place to be handled. All the other functions are really just about dispatching the request to the right place to be handled.

==Question engine upgrade helper 2.1 ==

''Site administration > Question engine upgrade helper'' has a menu to assist quiz conversion. It contains links for:
*List quizzes still to upgrade
*List already upgrade quizzes than can be reset
*Extract test case
*Config cron






[[Category:Question engine]] [[Category:Question engine]]
[[Category:Quiz]] [[Category:Quiz]]



Ganderson: /* Questions */ Add Wikipedia link to define the term QTI
2010-12-23T13:24:53Z
Questions:  Add Wikipedia link to define the term QTI

				
				
				
				
				
				← Older revision
				Revision as of 13:24, 23 December 2010
				
Line 12:
Line 12:



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. 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.   In the terminology of the [http://en.wikipedia.org/wiki/QTI 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. 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.



TimHunt at 09:20, 4 August 2010
2010-08-04T09:20:05Z


				
				
				
				
				
				← Older revision
				Revision as of 09:20, 4 August 2010
				
Line 196:
Line 196:



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

==Files belonging to questions==

This talks about the situation in relation to the Moodle 2.0 file API.

===File areas===

There are various file areas associated with each question.

For example there is a file are 'questiontext', belonging to the 'question' core component, which stores any images or other embedded files used by the question text. There are also 'generalfeedback' and 'question_answer' file areas.

There may also be some file areas specific to each question type. For example the 'qtype_multichoice' component has a 'correctfeedback' file area (among others).

All these file areas belong to the context that is the context of $question->category.

===Serving files and access checks===

This is a bit complicated because, although the files belong to the question system or a particular question type, then whether the user should be able to see a particular file (for example an image in the general feedback) is influenced by whichever part of Moodle is using the question (for example the quiz module or question preview).

The easiest way to explain is probably to show the call-stack for determining whether a particular image is displayed, then you can go and read the code.

For the request .../pluginfile.php/123/question/questiontext/234/345/image.png for an impage in the questiontext of a question in a quiz attempt.

(here, 123 is the contextid, 234 if the attemptid (corresponding to question_attempts.id) and 345 is the questionid.)

# pluginfile.php
# question_pluginfile() ''in lib/questionlib.php''
# quiz_question_pluginfile() ''in mod/quiz/lib.php''
# quiz_attempt->check_file_access() ''in mod/quiz/attemptlib.php''
# question->check_file_access() ''in lib/questionlib.php''
# qtype_''whatever''->check_file_access() ''in question/type/whatever/quetsiontype.php''

If, instead, the question was appearing in the question preview pop-up window, the call stack would be

# pluginfile.php
# question_pluginfile() ''in lib/questionlib.php''
# '''question_preview_question_pluginfile()''' ''in question/previewlib.php''
# question->check_file_access() ''in lib/questionlib.php''
# qtype_''whatever''->check_file_access() ''in question/type/whatever/quetsiontype.php''

(the different bit is highlighted in bold).

If, instead, the image url was .../pluginfile.php/123/qtype_multichoice/correctfeedback/234/345/image.png, the call stack would be

# pluginfile.php
# '''qtype_multichoice_pluginfile()''' ''in question/type/multichoice/lib.php''
# question_pluginfile() ''in lib/questionlib.php''
# quiz_question_pluginfile() ''in mod/quiz/lib.php''
# quiz_attempt->check_file_access() ''in mod/quiz/attemptlib.php''
# question->check_file_access() ''in lib/questionlib.php''
# qtype_multichoice->check_file_access() ''in question/type/multichoice/quetsiontype.php''

Roughly speaking, qtype_whatever->check_file_access() takes the same $question, $state and $options objects as print_question_formulation_and_controls, so, for example, you can do the same permissions check when trying to access a file in the feedback as was done when deciding whether to display the feedback.

The quiz_question_pluginfile or question_preview_question_pluginfile functions are responsible for getting the right $question, $state, $options based on the $attemptid and $questionid in the URL. They also do some basic access checks.

All the other functions are really just about dispatching the request to the right place to be handled.



[[Category:Question engine]] [[Category:Question engine]]
[[Category:Quiz]] [[Category:Quiz]]



TimHunt at 12:27, 5 March 2009
2009-03-05T12:27:05Z


				
				
				
				
				
				← Older revision
				Revision as of 12:27, 5 March 2009
				
Line 1:
Line 1:
{{Template:Question development}}

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






Peter2108: /* How the penalty is determined */
2008-03-30T19:55:12Z
How the penalty is determined

				
				
				
				
				
				← Older revision
				Revision as of 19:55, 30 March 2008
				
Line 185:
Line 185:
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. 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. 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. (In Moodle 1.8 the default value of 0.1 is actually hardcoded at line 87 of moodle/question/type/edit_question_form.php)



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



Tsala: cat edit
2007-06-18T09:21:23Z
cat edit

				
				
				
				
				
				← Older revision
				Revision as of 09:21, 18 June 2007
				
Line 195:
Line 195:
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. 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:Question engine]]
[[Category:Quiz]] [[Category:Quiz]]



Fulano2040: /* Sessions, States, Events */
2007-06-13T00:13:58Z
Sessions, States, Events

				
				
				
				
				
				← Older revision
				Revision as of 00:13, 13 June 2007
				
Line 45:
Line 45:
;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. ;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. ;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. ;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. ;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.

← Older revision		Revision as of 20:28, 14 July 2021
Line 109:		Line 109:
	==Response storage==		==Response storage==

	The student's responses to a question are stored in <syntaxhighlight lang="php">$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 student's responses to a question are stored in <syntaxhighlight lang="php">$state->responses</syntaxhighlight>. 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 <syntaxhighlight lang="php">$state->responses</~~code~~> field, to convert from the runtime to the storage model and vice versa:		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 <syntaxhighlight lang="php">$state->responses</syntaxhighlight> field, to convert from the runtime to the storage model and vice versa:

	;<syntaxhighlight lang="php">create_session_and_responses()</~~code~~>		;<syntaxhighlight lang="php">create_session_and_responses()</syntaxhighlight>
	:Initializes the $state object, in particular the <syntaxhighlight lang="php">$state->responses</~~code~~> field		:Initializes the $state object, in particular the <syntaxhighlight lang="php">$state->responses</syntaxhighlight> field

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

	;<syntaxhighlight lang="php">save_session_and_responses()</~~code~~>		;<syntaxhighlight lang="php">save_session_and_responses()</syntaxhighlight>
	: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 <syntaxhighlight lang="php">$state->responses</~~code~~> to the database.		: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 <syntaxhighlight lang="php">$state->responses</syntaxhighlight> to the database.

	The generic quiz module code saves the contents form the <syntaxhighlight lang="php"><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 <syntaxhighlight lang="php"><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 generic quiz module code saves the contents form the <syntaxhighlight lang="php"><nowiki>$state->responses['']</nowiki></syntaxhighlight> 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 <syntaxhighlight lang="php"><nowiki>$state->responses['']</nowiki></syntaxhighlight>. 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 <syntaxhighlight lang="php"><nowiki>$state->responses['']</nowiki></~~code~~> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <syntaxhighlight lang="php">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).		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 <syntaxhighlight lang="php"><nowiki>$state->responses['']</nowiki></syntaxhighlight> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <syntaxhighlight lang="php">save_session_and_responses()</syntaxhighlight>) whatever value the generic code set this field to with their serialized value (usually achieved with a simple set_field).

	In the method <syntaxhighlight lang="php">restore_session_and_responses()</~~code~~> the serialized value can be read from <syntaxhighlight lang="php"><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.		In the method <syntaxhighlight lang="php">restore_session_and_responses()</syntaxhighlight> the serialized value can be read from <syntaxhighlight lang="php"><nowiki>$state->responses['']</nowiki></syntaxhighlight> 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==		==Response processing==
Line 132:		Line 132:
	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.		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 <syntaxhighlight lang="php">print_question_formulation_and_controls()</~~code~~>. The convention only dictates that the name of the control element(s) must begin with the value of <syntaxhighlight lang="php">$question->name_prefix</~~code~~>. The <syntaxhighlight lang="php">$question->name_prefix</~~code~~> is a string starting with "resp" followed by the question id and an underscore, e.g. <syntaxhighlight lang="php">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.		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 <syntaxhighlight lang="php">print_question_formulation_and_controls()</syntaxhighlight>. The convention only dictates that the name of the control element(s) must begin with the value of <syntaxhighlight lang="php">$question->name_prefix</syntaxhighlight>. The <syntaxhighlight lang="php">$question->name_prefix</syntaxhighlight> is a string starting with "resp" followed by the question id and an underscore, e.g. <syntaxhighlight lang="php">resp56_</syntaxhighlight>. 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 <syntaxhighlight lang="php">respXX_</~~code~~>. Upon submission, the function <syntaxhighlight lang="php">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 <syntaxhighlight lang="php">$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.		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 <syntaxhighlight lang="php">respXX_</syntaxhighlight>. Upon submission, the function <syntaxhighlight lang="php">quiz_process_responses()</syntaxhighlight> 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 <syntaxhighlight lang="php">$state->responses</syntaxhighlight> 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 <syntaxhighlight lang="php">quiz_process_responses()</~~code~~> in turn calls the questiontype specific method <syntaxhighlight lang="php">grade_responses()</~~code~~> to assign a grade to the submitted responses and <syntaxhighlight lang="php">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 <syntaxhighlight lang="php">$state->responses</~~code~~> array.		The function <syntaxhighlight lang="php">quiz_process_responses()</syntaxhighlight> in turn calls the questiontype specific method <syntaxhighlight lang="php">grade_responses()</syntaxhighlight> to assign a grade to the submitted responses and <syntaxhighlight lang="php">compare_responses()</syntaxhighlight> 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 <syntaxhighlight lang="php">$state->responses</syntaxhighlight> array.

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

	==Question types==		==Question types==

← Older revision		Revision as of 13:02, 14 July 2021
Line 109:		Line 109:
	==Response storage==		==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 student's responses to a question are stored in <syntaxhighlight lang="php">$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:		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 <syntaxhighlight lang="php">$state->responses</code> field, to convert from the runtime to the storage model and vice versa:

	;<~~code~~>create_session_and_responses()</code>		;<syntaxhighlight lang="php">create_session_and_responses()</code>
	:Initializes the $state object, in particular the <~~code~~>$state->responses</code> field		:Initializes the $state object, in particular the <syntaxhighlight lang="php">$state->responses</code> field

	;<~~code~~>restore_session_and_responses()</code>		;<syntaxhighlight lang="php">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.		:Loads the question type specific session data from the database into the <syntaxhighlight lang="php">$state</code> object, in particular it loads the responses that have been saved for the given <syntaxhighlight lang="php">$state</code> into the <syntaxhighlight lang="php">$state->responses</code> field.

	;<~~code~~>save_session_and_responses()</code>		;<syntaxhighlight lang="php">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.		: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 <syntaxhighlight lang="php">$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 generic quiz module code saves the contents form the <syntaxhighlight lang="php"><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 <syntaxhighlight lang="php"><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).		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 <syntaxhighlight lang="php"><nowiki>$state->responses['']</nowiki></code> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <syntaxhighlight lang="php">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.		In the method <syntaxhighlight lang="php">restore_session_and_responses()</code> the serialized value can be read from <syntaxhighlight lang="php"><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==		==Response processing==
Line 132:		Line 132:
	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.		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.		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 <syntaxhighlight lang="php">print_question_formulation_and_controls()</code>. The convention only dictates that the name of the control element(s) must begin with the value of <syntaxhighlight lang="php">$question->name_prefix</code>. The <syntaxhighlight lang="php">$question->name_prefix</code> is a string starting with "resp" followed by the question id and an underscore, e.g. <syntaxhighlight lang="php">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.		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 <syntaxhighlight lang="php">respXX_</code>. Upon submission, the function <syntaxhighlight lang="php">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 <syntaxhighlight lang="php">$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.		The function <syntaxhighlight lang="php">quiz_process_responses()</code> in turn calls the questiontype specific method <syntaxhighlight lang="php">grade_responses()</code> to assign a grade to the submitted responses and <syntaxhighlight lang="php">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 <syntaxhighlight lang="php">$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.		Finally, the methods <syntaxhighlight lang="php">restore_session_and_responses()</code> and <syntaxhighlight lang="php">save_session_and_responses()</code> also need to know the questiontype specific layout of the <syntaxhighlight lang="php">$state->responses array</code> and restore or save the information, e.g. by converting from or to the data representation.

	==Question types==		==Question types==

← Older revision		Revision as of 17:50, 18 July 2011
Line 253:		Line 253:

	All the other functions are really just about dispatching the request to the right place to be handled.		All the other functions are really just about dispatching the request to the right place to be handled.

			==Question engine upgrade helper 2.1 ==

			''Site administration > Question engine upgrade helper'' has a menu to assist quiz conversion. It contains links for:
			*List quizzes still to upgrade
			*List already upgrade quizzes than can be reset
			*Extract test case
			*Config cron




	[[Category:Question engine]]		[[Category:Question engine]]
	[[Category:Quiz]]		[[Category:Quiz]]

← Older revision		Revision as of 13:24, 23 December 2010
Line 12:		Line 12:

	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.		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.		In the terminology of the [http://en.wikipedia.org/wiki/QTI 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.		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.

← Older revision		Revision as of 12:27, 5 March 2009
Line 1:		Line 1:
			{{Template:Question development}}

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

← Older revision		Revision as of 19:55, 30 March 2008
Line 185:		Line 185:
	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.		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.		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. (In Moodle 1.8 the default value of 0.1 is actually hardcoded at line 87 of moodle/question/type/edit_question_form.php)

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

← Older revision		Revision as of 09:21, 18 June 2007
Line 195:		Line 195:
	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.		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:Question engine]]
	[[Category:Quiz]]		[[Category:Quiz]]

← Older revision		Revision as of 00:13, 13 June 2007
Line 45:		Line 45:
	;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.		;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.		;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.		;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.		;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.