Permalink
Browse files

Added attempt.php documentation, unfinished.

  • Loading branch information...
1 parent 7f65461 commit d5711371ce15f274b78c585ec539af22652b176f mindforge committed Jun 30, 2005
Showing with 166 additions and 0 deletions.
  1. +166 −0 mod/quiz/doc/attempt.html
@@ -0,0 +1,166 @@
+<!DOCTYPE HTML PUBLIC>
+<html>
+ <head>
+ <title>Attempt.php</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>Attempt.php</h1>
+
+<h2>Contents</h2>
+<ul>
+ <a href='#description'><li>Description and purpose</li></a>
+ <a href='#simple'><li>A simplified perspective</li></a>
+ <ul>
+ <a href='#simple_start'><li>Starting a new attempt</li></a>
+ <a href='#simple_finish'><li>Finishing an attempt</li></a>
+ </ul>
+ <a href='#complicated'><li>A more complicated perspective</li></a>
+</ul>
+
+<a name="description"></a><h2>Description and purpose</h2>
+<p>
+
+The attempt.php script is one of the most complicated scripts of the quiz
+module. It is responsible for displaying questions to a user, to evaluate and
+grade the users' responses and additionally it needs to take various quiz
+settings into account and change the behaviour of the script accordingly. This
+script, which is vital for the fucntioning of the quiz module is explained in
+this document in some detail in order to provide some context and examples for
+the use of the question/state model and to illustrate some of the functions
+provided in locallib.php.
+
+</p><p>
+
+In addition to the immediate benefit of explaining what happens in attempt.php,
+this piece of documentation should provide an entry point to the quiz module
+code. A number of functions are used in attempt.php, which are likely to be used
+in other scripts as well.
+
+</p><p>
+
+Although the attempt.php script is useful for understanding how user
+interactions are handled, it is of very limited use for understanding the
+teacher interface for editing quizzes and questions.
+
+</p>
+
+<a name="simple"></a><h2>A simplified perspective</h2>
+<p>
+
+From a simple functional point of view, the responsibilities of attempt.php is
+the handling of attempts at a quiz. This includes displaying questions and
+storing data provided or generated by the users. The interaction could be
+limited to opening the page and thus creating a new attempt and submitting the
+responses back to the server, which causes the responses to be graded. While the
+script is actually more sophisticated and allows to interrupt and continue
+attempts, this two step scenario provides a good starting point and covers the
+core functionality.
+
+</p>
+
+<a name='simple_start'></a><h3>Starting a new attempt</h3>
+<p>
+
+When a new attempt is started no session data exists for the user and therefore
+it needs to be created. A function is defined to do exactly this job, it is
+called <code>quiz_create_attempt</code> (line 183). It returns an empty <code>
+$attempt</code> object, which is stored in the database immediately to record
+the fact that the student has seen the questions.
+
+</p><p>
+
+The next step is to load up all questions and to create initial states for all
+of them. Loading up the questions is a two step process: first the question
+records are extracted from the database, then the function <code>
+quiz_get_questions_options</code> is called. This attaches the name_prefix
+field and calls the questiontype specific <code>get_question_options</code>
+method for each question record in order to add any required data.
+
+</p><pre>
+ // Load the questions
+ if (!$questions = get_records_sql($sql)) {
+ ...
+ }
+ // Load the question type specific information
+ if (!quiz_get_question_options($questions)) {
+ ...
+ }
+ // Restore the question sessions to their most recent states
+ // creating new sessions where required
+ if (!$states = quiz_restore_question_sessions($questions, $quiz, $attempt)) {
+ ...
+ }
+
+</pre><p>
+
+After all questions are correctly initialised a state object is created for
+each by the function <code>quiz_restore_question_sessions</code>. This may seem
+a bad name for a function to create states, however, it so happens that this
+function is responsible for providing a state for each question and creates a
+new state if there isn't one to be restored. Again, the new states are saved
+right away.
+
+</p><p>
+
+At this point all the required data is generated or loaded, so the last step is
+to print the page. The printing happens towards the end of the attempt.php
+script and, apart from a simple call to <code>print_heading</code> (line 409),
+is done in a loop through all the question records by calling <code>
+quiz_print_quiz_question</code> (line 461), which is just a shorthand for
+calling the questiontype specific <code>print_question</code> method. So, quite
+conveniently, each question is responsible for printing itself. To round up the
+printing, submit buttons and a footer are printed to the bottom of the page.
+
+</p>
+
+<a name='simple_finish'></a><h3>Finishing an attempt</h3>
+<p>
+
+The next logical step after creating and displaying an attempt is that the user
+enters answers for all questions and submits them for marking. Now it is not
+necessary to create a new attempt, because there is already an open existing one
+in the database and the same holds for each question's state. So this time the
+attempt record is loaded from the database. The questions are loaded in the same
+way, by querying for the question records an then attaching any required
+questiontype specific fields by calling the function <code>
+quiz_get_question_options</code>. Now the call to the function <code>
+quiz_restore_question_sessions</code> does actually restore the states from the
+database rather than generate new ones, so the same code works for the two
+scenarios, creating and closing an attempt.
+
+</p><p>
+
+Now all data concerning the attempt under discussion is loaded, the responses
+submitted by the student come to the scene. For each question they need to be
+evaluated and graded. The first step here is to determine how to deal with each
+question and the associated responses. In the simplified case this is clear; all
+responses need to be graded, the grades stored and then the attempt needs to be
+closed. However, ther are more complicated cases, so the function <code>
+quiz_extract_responses</code> is called to create the <code>$actions</code>
+array, which acts as a set of instructions for the fucntion <code>
+quiz_process_responses</code>, a quite complicated function, which encapsulates
+the entire response processing for one question and calls out to the
+questiontype specific <code>grade_responses</code> method for grading.
+
+</p><p>
+
+After all questions are graded the attempt is closed by setting the
+<code>timefinish</code> field to the current time. After this the user is
+redirected to review.php, which, depending on the quiz review settings, shows
+the questions including the student's responses, feedback, grades and correct
+answers.
+
+</p>
+
+
+<a name="complicated"></a><h2>A more complicated perspective</h2>
+<p>
+
+</p>
+
+
+</body>
+</html>

0 comments on commit d571137

Please sign in to comment.