questionlib.php

Contents

Description and purpose

The question library defines the core code that is used for the processing of question and state objects. For the understanding of the quiz module (and soon also the lesson module) these functions, which are defined to be generically reusable by any module that wants to use questions, are key. Therefore all non-trivial functions defined in this library is explained in this documentation. Further documentation is contained as phpDoc comments in the library itself.

quiz_load_questiontypes

This function loads the plugged in questiontypes, i.e. it looks for all folders in the quiz/questiontypes subdirectory, that contain a file called questiontype.php and loads these questiontype definitions.

quiz_get_question_options

This function adds the name prefix to a single question object or to each item in an array of question objects and calls the appropriate questiontype specific get_question_options method. Question objects that come directly from the database should always be processed by this function to guarantee that they are set up correctly for further processing.

quiz_get_states

This function attempts to load the most recent state for each question object in an array of question objects. If there is no such state it creates a new empty state object instead. For existing states the function quiz_restore_state is called automatically.

quiz_restore_state

This function adds all generic runtime fields to a given state object and calls the corresponding quetsiontype specific restore_session_and_responses method. This function needs to be called on any states that are retrieved directly from the database. It should normally not be necessary to call this function directly; instead the function quiz_get_states should be used.

quiz_save_question_session

This function takes an array of state objects and saves all that are marked as changed to the database. After they are saved it calls the questiontype specific save_session_and_responses method. Additionally, this method determines what needs to be written to the table quiz_newest_states .

quiz_regrade_question_in_attempt

This function regrades a single question instance (identified by question and attempt). In order to do this correctly, it loads the complete history of states for the question instance and replays it. I.e. it starts out with the first state, prepares an $action object, that is required by the function quiz_process_responses, with its three fields: event, responses and timestamp and finally it calls the function quiz_process_responses, which does the actual grading. This means that the same code is used for grading and regrading, which should guarantee identical grades if the question remains unchanged.

quiz_process_responses

The quiz_process_responses function is a rather complicated construct, which does all necessary processing to get from one state to the next, depending on the information provided in the $action object (event, responses and timestamp). It takes care that the questiontype specific grade_responses method is called, that the changed flag is set, that re-submissions are detected and not graded again and that the function quiz_apply_penalty_and_timelimit is called when necessary.

quiz_apply_penalty_and_timelimit

This function determines whether a penalty needs to be applied to the achieved grade (depending on the history of states) or if the timelimit was up and the grade should be set to zero in any case.

quiz_new_attempt_uniqueid

In order to make questions and states usable for several moodle modules a unique attempt id is needed for the states table. However, attempts are module specific and therefore they use different database tables. To guarantee that the attempt is still unique, the config option attemptuniqueid was introduced. It stores the value that needs to be used for the next attempt. This function makes sure that this counter is incremented and returns the id that should be used.

quiz_get_renderoptions

This function determines from the information provided whether to show specific pieces of information when the question is printed (or rendered). It returns an object (usually called $options) that has six boolean fields: readonly, feedback, validation, correct_responses, responses and scores. These boolean options are used by the questiontype specific print methods to determine whether certain bits of information should be displayed or not. This function is used during attempts.

quiz_get_reviewoptions

This function is similar to quiz_get_renderoptions in that it returns the same object. However, this function is not used during an attempt, but when attempt is reviewed.