Permalink
Browse files

Database documentation finished.

  • Loading branch information...
1 parent 4d16298 commit 94c6290094720f752b86529fc04d814c58679075 mindforge committed Jun 29, 2005
Showing with 203 additions and 25 deletions.
  1. +203 −25 mod/quiz/doc/databasetables.html
@@ -219,38 +219,37 @@ <h3>Redundant</h3>
<a name="quiz_attempts"></a><h2>quiz_attempts</h2>
<p>
+In the quiz_attempts table a record is created each time when a user starts an
+attempt at a quiz. It is possible for a user to attempt a quiz several times,
+therefore the number of the attempt is stored in the <code>attempt</code> field.
+The <code>sumgrade</code> field records the (unscaled) grade for the attempt,
+i.e. if the grades assigned to the questions add up to 8, but the maximum grade
+for the quiz is set to 10, then the <code>sumgrades</code> field can contain 8
+at maximum.
+</p><p>
-</p>
+The <code>timestart</code> field is set to the current time when an attempt is
+started and is never changed afterwards. The <code>timefinish</code> field is
+set to "0" initially and to the current time when it is closed. This fact that
+is exploited at several places in the code to determine whether an attempt
+has been closed or not (i.e. closed = timefinish > 0). For all other
+modifications of an attempt record the <code>timemodified</code> field should be
+changed as well.
+</p><p>
+Finally, there are the <code>layout</code> and <code>preview</code> fields.
+While the preview field simply denotes a teacher preview (i.e. an attempt by a
+user with teacher privileges) that may be automatically deleted when the quiz is
+previewed again, and which is not taken into account when viewing statistics,
+the <code>layout</code> field is a little more complicated. It contains a comma
+separated list of question ids, with a "0" denoting a pagebreak. In the case
+where all questions on one page the comma separated list ends with ",0".
+</p>
<a name="quiz_newest_states"></a><h2>quiz_newest_states</h2>
-<a name="quiz_question_instances"></a><h2>quiz_question_instances</h2>
-<a name="quiz_states"></a><h2>quiz_states</h2>
-<a name="quiz_calculated"></a><h2>quiz_calculated</h2>
-<a name="quiz_dataset_definitions"></a><h2>quiz_dataset_definitions</h2>
-<a name="quiz_dataset_items"></a><h2>quiz_dataset_items</h2>
-<a name="quiz_match"></a><h2>quiz_match</h2>
-<a name="quiz_match_sub"></a><h2>quiz_match_sub</h2>
-<a name="quiz_multianswers"></a><h2>quiz_multianswers</h2>
-<a name="quiz_multichoice"></a><h2>quiz_multichoice</h2>
-<a name="quiz_numerical"></a><h2>quiz_numerical</h2>
-<a name="quiz_numerical_units"></a><h2>quiz_numerical_units</h2>
-<a name="quiz_question_datasets"></a><h2>quiz_question_datasets</h2>
-<a name="quiz_randomsamatch"></a><h2>quiz_randomsamatch</h2>
-<a name="quiz_rqp"></a><h2>quiz_rqp</h2>
-<a name="quiz_rqp_states"></a><h2>quiz_rqp_states</h2>
-<a name="quiz_rqp_types"></a><h2>quiz_rqp_types</h2>
-<a name="quiz_shortanswer"></a><h2>quiz_shortanswer</h2>
-<a name="quiz_truefalse"></a><h2>quiz_truefalse</h2>
-
-
-
-
-<a name='quiz_newest_states'></a><h2>quiz_newest_states</h2>
-
<p>This table exists only for efficiency reasons:</p>
<ol>
@@ -273,4 +272,183 @@ <h3>Redundant</h3>
states that could take too long. Rather it is done whenever needed
by quiz_upgrade_states().</p>
+<a name="quiz_question_instances"></a><h2>quiz_question_instances</h2>
+<p>
+
+Questions can have different grades assigned in different quizzes. These are
+stored in the <code>quiz_question_instances</code> table. While, after a small
+extension, this table could also fulfill the purpose of storing the order of the
+questions in a quiz, this is currently still done in the <code>questions</code>
+field in the <code>quiz</code> table.
+
+</p>
+
+<a name="quiz_states"></a><h2>quiz_states</h2>
+<p>
+
+States are saved for each interaction with a question. This allows to review the
+complete history of a user's attempts on individual questions. The
+<code>seq_number</code> field stores the order of this history, the
+<code>answer</code> field stores a questiontype specific string unless the
+questiontype stores its answers differently. The <code>event</code> field stores an integer, each of which is
+defined as a named constant in the file <code>locallib.php</code>. E.g. values
+can denote a saveing or a grading interaction amongst others.
+
+</p><p>
+
+Of further interest are the <code>grade</code>, <code>raw_grade</code> and
+<code>penalty</code> fields. The <code>raw_grade</code> field stores the grade
+that was achieved for the question scaled to the question's weight or grade as
+assigned in the <code>quiz_question_instances</code> table. The <code>grade
+</code> field stores the actual achieved grade after deduction of the penalty.
+And in the <code>penalty</code> field the penalty for that state is saved. This
+is different from the cumulative penalty, which is stored in the <code>
+quiz_newest_states</code> table.
+
+</p><p>
+
+The <code>originalquestion</code> field is a construct that will be used by the
+versioning code. The question ids in the states will be changed to the ids of
+the new versions of the questions and the id of the question, which was used
+for the actual attempt, will be stored in the <code>originalquestion</code>
+field.
+
+</p>
+
+<a name="quiz_calculated"></a><h2>quiz_calculated</h2>
+<p>
+
+The <code>quiz_calculated</code> table is an extension to the
+<code>quiz_questions</code> table by the calculated questiontype. However, it
+would be more suitable to change that to be an extension of the
+<code>quiz_answers</code> table, which, from a data perspective, is already
+possible, since an answer id is stored in the <code>answer</code> field. The
+questiontype code woud need some changes to take this into account, however.
+
+</p>
+
+<a name="quiz_dataset_definitions"></a><h2>quiz_dataset_definitions</h2>
+<p>
+
+The <code>quiz_dataset_definitions</code> table belongs to the abstract
+datasetdependent questiontype, which is currently only used by the calculated
+questiontype. It is an indirect extension to the <code>quiz_questions</code>
+table, because the <code>quiz_question_datasets</code> 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.
+
+</p>
+
+<a name="quiz_dataset_items"></a><h2>quiz_dataset_items</h2>
+<p>
+
+Dataset items can be created for each dataset. The <code>quiz_dataset_items
+</code> table stores these possible values for the variables defined in the
+<code>quiz_dataset_definitions</code> table.
+
+</p>
+
+<a name="quiz_match"></a><h2>quiz_match</h2>
+<p>
+
+The <code>quiz_match</code> table belongs to the match questiontype and extends
+the <code>quiz_questions</code> table. It is only used in the code for saving
+matching questions and can therefore be considered redundant.
+
+</p>
+
+<a name="quiz_match_sub"></a><h2>quiz_match_sub</h2>
+<p>
+
+The <code>quiz_match_sub</code> table belongs to the match questiontype and
+extends the <code>quiz_questions</code> table. It stores the pairs of questions
+and answers (as strings) that need to be matched for a correct solution.
+
+</p>
+
+
+<a name="quiz_multianswers"></a><h2>quiz_multianswers</h2>
+<p>
+
+The <code>quiz_multianswers</code> table belongs to the multianswer questiontype
+and is an extension of the <code>quiz_questions</code> table. It merely stores a
+comma separated list of question ids in the <code>sequence</code> field, which
+is important, because that's the only way to know which sub question belongs to
+which position in the questiontext.
+
+</p>
+
+<a name="quiz_multichoice"></a><h2>quiz_multichoice</h2>
+<p>
+
+The <code>quiz_multichoice</code> table belongs to the multichoice questiontype
+and is an extension of the <code>quiz_questions</code> table. The <code>layout
+</code> field does not seem to be used, the <code>answers</code> field stores
+the order of the answers (should be superceeded by the <code>seq_number</code>
+field in the <code>quiz_answers</code> table) and the <code>single</code> field
+is a flag signaling, whether only one option or multiple options can be chosen.
+
+</p>
+
+<a name="quiz_numerical"></a><h2>quiz_numerical</h2>
+<p>
+
+The <code>quiz_numerical</code> table belongs to the numerical questiontype
+and is an extension of the <code>quiz_answers</code> table, defining a tolerance
+value for each answer.
+
+</p>
+
+<a name="quiz_numerical_units"></a><h2>quiz_numerical_units</h2>
+<p>
+
+The <code>quiz_numerical_units</code> table is used by the numerical
+questiontype and the calculated questionype. It extends the
+<code>quiz_questions</code> table, defining an arbitrary number of units that
+can be used in the responses.
+
+</p>
+
+<a name="quiz_question_datasets"></a><h2>quiz_question_datasets</h2>
+<p>
+
+The <code>quiz_question_datasets</code> table is used by dataset depenndent
+questionypes (i.e. calculated) to link datasets to questions.
+
+</p>
+
+<a name="quiz_randomsamatch"></a><h2>quiz_randomsamatch</h2>
+<p>
+
+This extension to the <code>quiz_questions</code> table simply stores how many
+shortanswer questions should be randomly chosen to build this randomsamatch
+question.
+
+</p>
+
+<a name="quiz_rqp"></a><h2>quiz_rqp</h2>
+<p>No information.</p>
+<a name="quiz_rqp_states"></a><h2>quiz_rqp_states</h2>
+<p>No information.</p>
+<a name="quiz_rqp_types"></a><h2>quiz_rqp_types</h2>
+<p>No information.</p>
+<a name="quiz_shortanswer"></a><h2>quiz_shortanswer</h2>
+<p>
+
+The <code>quiz_shortanswer</code> table belongs to the shortanswer questiontype
+and is an extension of the <code>quiz_questions</code> table. The answers field
+stores a comma separated list of answer ids, which is redundant. The only
+valuable piece of information contained in this table is the <code>usecase
+</code> field, which is used to decide whether to do a case sensitive or case
+insensitive comparison for grading.
+
+</p>
+
+<a name="quiz_truefalse"></a><h2>quiz_truefalse</h2>
+<p>
+
+An extension of the <code>quiz_questions</code> table the <code>quiz_truefalse
+</code> table stores the answer ids for the true and for the false answers.
+
+</p>
</body> </html>

0 comments on commit 94c6290

Please sign in to comment.