mirror_php/moodle
1
0
Fork 0
mirror of https://github.com/moodle/moodle.git synced 2025-02-15 21:36:58 +01:00
Code Issues Projects Releases Wiki Activity

Documentation about response storage and the beginning of a glossary for quiz specific terminology.

Browse Source
This commit is contained in:
mindforge 2005-05-31 23:10:18 +00:00
parent 736f191c1d
commit b27d7b3b6b
2 changed files with 346 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
mod/quiz/doc/responsestorage.html Normal file
View File

@ -0,0 +1,275 @@
<!DOCTYPE HTML PUBLIC>
<html>
<head>
<title>Response Storage</title>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<!--link rel="stylesheet" type="text/css" href="doc.css"-->
</head>
<body>
<h1>Response Storage</h1>
<h2>Contents</h2>
<ul class="navigation">
<li><a href='#description'>Purpose and Description</a></li>
<li><a href='#qtypemethods'>Questiontype Methods</a></li>
<li><a href='#storage'>Response Storage</a></li>
<li><a href='#runtime'>Runtime Model</a></li>
<li><a href='#qtypes'>Responses by Questiontype</a></li>
</ul>
<a name='description'></a><h2>Purpose and Description</h2>
<p>
<a href="terminology.html#responses">Responses</a> are an attribute of the
<code>$state</code> object. Questiontypes are completely free to implement the
storage mechanism of their responses (and other state information) the way they
want. Still, the default <a href="terminology.html#responses">questiontypes</a>
all follow a similar model. The default storage model and the questiontype
specific variations are explained below.
</p><p>
The <a href="#runtime">runtime model</a> needs some more standardisation to work
generically. Therefore it imposes some constraints by convention, which are
explained later on the page.
</p>
<a name='qtypemethods'></a><h2>Questiontype Methods</h2>
<p>
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:
<ul>
<li><code>create_session_and_responses</code></li>
<li><code>restore_session_and_responses</code></li>
<li><code>save_session_and_responses</code></li>
</ul>
The following method descriptions are adapted from the phpdoc comments in
locallib.php.
</p>
<h3><code>create_session_and_responses</code></h3>
<p>
Initializes the <code>$state</code> object, in particular the
<code>$state->responses</code> field, but also any other state (or session)
information.
</p><p>
This function is called to start a question session. Empty question type
specific session data (if any) and empty response data is added to the
<code>$state</code> object. Session data is any data which must persist
throughout the quiz attempt, possibly with updates as the user interacts with
the question. This function does <strong>not</strong> create new entries in the
database for the session; a call to the <code>save_session_and_responses</code>
method will occur to do this.
</p>
<h3><code>restore_session_and_responses</code></h3>
<p>
Restores the session data and most recent responses for the given state.
</p><p>
This function loads any session data associated with the question session in the
given state 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.
</p><p>
Questiontypes with only a single form field for the student's response will not
need to restore the responses; the value of the <code>answer</code> field in the
<code>quiz_states</code> table is restored to <code>$state->responses['']</code>
automatically before this function is called. Questiontypes with more response
fields should override this method and set the <code>$state->responses</code>
field to an associative array of responses.
</p>
<h3><code>save_session_and_responses</code></h3>
<p>
Saves the session data and responses for the given question and state.
</p><p>
This function saves the question type specific session data from the
<code>$state</code> object to the database. In particular, for most
questiontypes, it saves the responses from the <code>$state->responses</code>
field of the <code>$state</code> object. The questiontype non-specific data for
the state has already been saved in the <code>quiz_states</code> table and the
<code>$state</code> object contains the corresponding id and sequence number,
which may be used to index a question type specific table.
</p><p>
Questiontypes with only a single form field for the student's response, which is
contained in <code>$state->responses['']</code> will not have to save this
response. It will already have been saved to the <code>answer</code> field of
the <code>quiz_states</code> table. Questiontypes with more response fields
should override this method and save the responses in their own database tables.
</p>
<a name='storage'></a><h2>Response Storage</h2>
<p>
The generic quiz module code saves the contents form the
<code>$state->responses['']</code> field to the <code>answer</code> field in the
<code>quiz_states</code> table and also automatically restores the contents of
this field to <code>$state->responses['']</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 <code>answer</code> field in the <code>quiz_states</code> table.
However, it is also possible (and may be better practice) to extend the
<code>quiz_states</code> table with a questiontype specific table, i.e. take the
id of the <code>quiz_states</code> record as a foreign key in the questiontype
specific table. Because the value of <code>$state->responses['']</code> is set
to the value of the <code>answer</code> 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 <code>set_field</code>). In the method
<code>restore_session_and_responses</code> the serialized value can be read from
<code>$state->responses['']</code>. 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.
</p>
<a name='runtime'></a><h2>Runtime Model</h2>
<p>
The runtime model for responses dictates the structure of the
<code>$state->responses</code> array. Starting with the names of the form
elements this section goes through the relevant processing steps and thus
attempts to clarify why the indecies of the <code>$state->responses</code> array
can differ for different questiontypes; even more, it explains how the indicies
are chosen and set.
</p><p>
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) <strong>must</strong> 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. resp56_. In the default case, when
there is only a single control element (this includes a list of equally named
radio buttons), no postfix is appended to the name prefix. For questiontypes
that allow or require multiple responses, an arbitrary string can be appended
to the name prefix. Ideally the postfix should not include any relational data
(i.e. ids of records in the <code>quiz_answers</code> table), because this can
lead to problems with regrading of versioned questions.
</p><p>
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 respXX_. 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 indecies. 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.
</p><p>
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 indicies of the <code>$state->responses</code> array.
</p><p>
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</code> array and restore or save
the information, e.g. by converting from or to the data representation.
<a name='qtypes'></a><h2>Responses by Questiontype</h2>
<h3>Calculated</h3>
<p>
The calculated questiontype inherits its methods
<code>create_session_and_responses</code>,
<code>restore_session_and_responses</code> and
<code>save_session_and_responses</code> from the abstract dataset dependent
questiontype. This questiontype serializes the information of the chosen dataset
together with the (single) response value into a string of the format
datasetXX-RESPONSE, where dataset is the actual string "dataset", XX is the
number of the chosen dataset item and RESPONSE is the value that was recieved
from the submitted form.
</p>
<h3>Description</h3>
<p>The description questiontype does not have responses.</p>
<h3>Match</h3>
<p>Note: This will be changed soon, so the description is pending.</p>
<h3>Multichoice</h3>
<p>Note: This will be changed soon, so the description is pending.</p>
<h3>Numerical</h3>
<p>
The numerical questiontype, which inherits the function
<code>print_question_formulation_and_controls</code> from the shortanswer
questiontype, has only one response field, so its responses are handled by the
default questiontype. The response is stored without any modifications in the
<code>answer</code> field of the table <code>quiz_states</code>.
</p>
<h3>Random</h3>
<p>
The random questiontype saves one state with a question id in the
<code>answer</code> field to indicate which question was randomly selected. From
that point onwards only states for the chosen question are saved.
</p>
<h3>RandomSAMatch</h3>
<p>Note: This will be changed soon, so the description is pending.</p>
<h3>Shortanswer</h3>
<p>
The shortanswer questiontype is the ideal example of the default case. It does
not overwrite any of the default implementations of the three methods mentioned
above, because it uses the default <code>$state->responses</code> array indexed
with the empty string. The value entered into the shortanswer input field is
entered directly into the <code>answer</code> field.
</p>
<h3>Truefalse</h3>
<p>Note: This will be changed soon, so the description is pending.</p>
</body>
</html>

71
mod/quiz/doc/terminology.html Normal file
View File

@ -0,0 +1,71 @@
<!DOCTYPE HTML PUBLIC>
<html>
<head>
<title>Terminology</title>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<!--link rel="stylesheet" type="text/css" href="doc.css"-->
</head>
<body>
<h1>Terminology in the Quiz Module</h1>
<h2>Contents</h2>
<ul class="navigation">
<li><a href='#description'>Purpose and Description</a></li>
<li><a href='#terms'>Terms</a></li>
</ul>
<a name='description'></a><h2>Purpose and Description</h2>
<p>
In order to describe and understand the quiz module, it is necessary to
understand the terminology that is used to describe its aspects. On this page
the important terms are named and explained and in some cases linked to more
detailed documentation.
</p>
<a name='terms'></a><h2>Terms</h2>
<table>
<tr>
<th>Term</th>
<th>Description</th>
<th>Related Links</th>
</tr>
<tr>
<td><a name="#answers"></a>answer(s)</td>
<td>The term answer is used exclusively for the teacher defined answers
of a question. These answers are usually stored in the
<code>quiz_answers</code> table and are compared to the responses for
grading.
</td>
<td></td>
</tr>
<tr>
<td><a name="#questiontype"></a>questiontype</td>
<td>There are several questiontypes built into the quiz module, however,
due to the plugin architechture of the quiz module, it is possible to
define custom questiontypes. Existing questiontypes include true/false,
multiple choice, short answer, numerical and calculated questions.
</td>
<td><a href="http://moodle.org/mod/wiki/view.php?id=2935&page=Guidelines+for+converting+existing+questiontypes">conversion guide</a></td>
</tr>
<tr>
<td><a name="#responses"></a>responses</td>
<td>Conceptually these are the students' responses to a question. This
is always used in plural, although for some questiontypes there is only
one possible response. In the runtime <code>$state</code> object there
is a field <code>$state-&gt;responses</code>, which holds an array of a
student's responses to a question.
</td>
<td><a href="responsestorage.html">response storage</a></td>
</tr>
</table>
</p>
</body>
</html>