Runtime Objects

Contents

Description and purpose

In most scripts the quiz module deals with the same objects. In some cases these are not identical to the records from the database, but they have some fields that are added at runtime. The objects concerned are questions and states; both are described below. Also the options object, purely a runtime object, is described. 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.

The question object

The question object is based on the database record for a question. The table below illustrates this structure.

id Primary key
category Foreign key: refers to an id in the table quiz_categories
parent Foreign key: refers to an id in the table quiz_questions and indicates for wrapped questions, which question they are a part of. If parent is not '0' the question is never shown in a list of questions, because it is not a valid question by itself.
name Question name
questiontext Main text of the question
questiontextformat
image
defaultgrade Default grade for a question, usually '1'. In the wrapped parts of cloze questions defaultgrade represents the weight of the part.
penalty The penalty that is applied (if the respective quiz option is set) for a incorrect attempt at the question.
qtype The questiontype of the question. (Constants are defined in locallib.php)
length The number of question numbers used up by this question. 0 for descriptions, 1 for most other question types.
stamp Unique identifier
version A number representing how often the question was edited.
hidden Controls whether to display a question in the question bank list in edit.php.

In addition to these static fields, which are part of the generic question definitions, there are some additional fields that are only added to the object at runtime. There are two different kinds of fields: On the one hand there are questiontype specific fields, which are also part of fthe static question definition, but only apply to some questions. On the other hand there are fields that refer to the question instance, i.e. the question in the context of a particular quiz. The values for these fields can differ when a question is used in different quizzes.

maxgrade The maximum grade available for this question in this quiz, i.e. the grade for a correct response.
instance Foreign key: refers to an id in the table quiz_instances
options Optional field. It provides a namespace for any questiontype specific information that may be stored in this field. It is generally set by the get_question_options method.
name_prefix The prefix to be used on all interactions printed as part of the question.

The state object

For each question object there is a corresponding state object, which holds all the information, which stores all the information that is specific to the current question and session. There can be several states stored for each question instance, however, this list of states represents the history of interactions. The state object that corresponds to a particular question is generally the most recent state. Again, like for the question objects, the state objects are mostly made up of data from the database and then some fields are added at runtime. First the fields from the database are described.

id Primary key
attempt Foreign key: refers to an id in the table quiz_attempts
question Foreign key: refers to an id in the table quiz_questions. The attempt id (or the quiz id) and the question id together sufficiently identify a question instance, which a state logically belongs to. However, for practical reasons it is more convenient to store the attempt and question ids.
originalquestion Foreign key: identifies which question was in use when the student attempted the question. This is part of the versioning feature.
seq_number A counter that provides information about the sequence in which the states were created.
answer This field is deleted during runtime and replaced with the responses field. For legacy reasons it is still called answer in the database. Questiontypes can store students' responses (usually in a serialized format) in this field using the method save_session_and_responses . Questiontypes are allowed to deviate from this and handle their response storage in any desired way.
timestamp A timestamp to record when the state was created. This could mainly be useful for audit purposes.
event Records the event or interaction type that lead from the previouse state to the current one.
grade The raw grade scaled to the defaultgrade value of the question.
raw_grade A grade between 0 and 1, giving the correctness of the responses as a percentage.
penalty The penalty incurred during the transition from the previous state to this one. This is different to the cumulative penalty, which can be calculated by adding up all the penalties from previous states. For convenience the most recent cumulative penalties are also stored in the table quiz_newes_states.

In addition to the database fields a few fields are added to the states at runtime. They are dealt with by the questiontypes with the methods create_session_and_responses, restore_session_and_responses and save_session_and_responses and are defined as follows.

responses This is automatically set to the value of the database field answer before that one is removed. The responses field contains an array of responses. In the default case of a single response the value can be found in ->responses['']. For questiontypes using several HTML form elements for their responses the array contains a value for each of the interaction elements. The indecies are determined by the name of the elements if the name_prefix is stripped.
last_graded This field contains the most recent graded state in the history of this question instance. This is necessary, because if a state merely represents a save interaction, it should not affect the session in any way. Therefore another grade interaction has to proceed from the last graded state.
options Optional field. Similarly to the options field in the question object, this field provides a namespace for any questiontype specific information. The difference is that the information in the state->options field should be state specific, whereas the question->options field should be static.

The options object

The options object is purely a runtime object. It is used to carry information about which optional bits of a question should be printed. That can be feedback, correct responses or any other information that a teacher can choose to show or hide to the students during different phases of the quiz lifecycle.

feedback The feedback field holds a boolean value, indicating to the questiontypes' print_question_formulation_and_controls method whether or not to print feedback (if available) for the submitted responses.
correct_responses The correct_responses field holds a boolean value, indicating to the questiontypes' print_question_formulation_and_controls method whether or not to provide the correct responses (if available) inline with the question.
readonly The readonly field holds a boolean value, indicating to the questiontypes' print_question_formulation_and_controls method whether the interaction elements should be disabled or not.
validation The validation field holds a boolean value, indicating to the questiontypes' print_question_formulation_and_controls method whether or not to print question validation information. (This is currently only used by the RQP questiontype.)
responses The responses field holds a boolean value, indicating to the questiontypes' print methods whether or not to print a student's responses. This only makes sense for reviewing.
scores The scores field holds a boolean value, indicating to the questiontypes' print methods whether or not to print the grade awarded to student.
solutions The solutions field holds a boolean value, indicating to the questiontypes' print methods whether or not to show the worked solution provided by the teacher (if any). This only makes sense for reviewing.