Development:Using the question engine from module - Revision history

TimHunt at 06:58, 1 May 2011

2011-05-01T06:58:07Z

← Older revision		Revision as of 06:58, 1 May 2011
Line 96:		Line 96:
	'" enctype="multipart/form-data" accept-charset="utf-8">', "\n<div>\n";		'" enctype="multipart/form-data" accept-charset="utf-8">', "\n<div>\n";

	~~print_js_call~~('~~question_init_form~~', array('responseform'));		$PAGE->requires->js_init_call('M.core_question_engine.init_form',
			array('#responseform'), false, 'core_question_engine');

	echo '<input type="hidden" name="slots" value="' . implode(',', $slotsonpage) . "\" />\n";		echo '<input type="hidden" name="slots" value="' . implode(',', $slotsonpage) . "\" />\n";
Line 141:		Line 142:
	<code php>		<code php>
	$timenow = time();		$timenow = time();
	~~begine_sql~~();		$transaction = $DB->start_delegated_transaction();

	$quba = question_engine::load_questions_usage_by_activity($usageid);		$quba = question_engine::load_questions_usage_by_activity($usageid);
Line 147:		Line 148:
	question_engine::save_questions_usage_by_activity($quba);		question_engine::save_questions_usage_by_activity($quba);

	~~commit_sql~~();		$transaction->allow_commit();
	</code>		</code>

Line 159:		Line 160:
	}		}
	$attempt->timemodified = $timenow;		$attempt->timemodified = $timenow;
	update_record('quiz_attempts', $attempt);		$DB->update_record('quiz_attempts', $attempt);
	</code>		</code>

Line 201:		Line 202:
	<tt>qubaid_list</tt> is a subclass of the <tt>qubaid_condition</tt> class. This is an efficient way to represent a set of usage ids in a way that can be used in database queries. The other main subclass is <tt>qubaid_join</tt>. That could be used like this:		<tt>qubaid_list</tt> is a subclass of the <tt>qubaid_condition</tt> class. This is an efficient way to represent a set of usage ids in a way that can be used in database queries. The other main subclass is <tt>qubaid_join</tt>. That could be used like this:
	<code php>		<code php>
	$qubaidscondition = new qubaid_join("{~~$CFG->prefix~~}~~quiz_attempts~~ quiza",		$qubaidscondition = new qubaid_join('{quiz_attempts} quiza', 'quiza.uniqueid',
	'quiza.uniqueid', "quiza.quiz = $quizid");		'quiza.quiz = :quizaquiz', array('quizaquiz' => $quizid))
	</code>		</code>

Line 238:		Line 239:
	// ... or many.		// ... or many.
	question_engine::delete_questions_usage_by_activity(		question_engine::delete_questions_usage_by_activity(
	"{~~$CFG->prefix~~}~~question_usages~~.~~id IN (SELECT~~ uniqueid		new qubaid_join('{quiz_attempts} quiza', 'quiza.uniqueid',
	~~FROM {~~$~~CFG->prefix}quiz_attempts quiza~~)"		'quiza.quiz = :quizaquiz', array('quizaquiz' => $quizid)));
	</code>		</code>

Line 255:		Line 256:
	This code example is adapted from <tt>mod/quiz/report/overview/report.php</tt>. It re-grades selected slots within a quiz attempt.		This code example is adapted from <tt>mod/quiz/report/overview/report.php</tt>. It re-grades selected slots within a quiz attempt.
	<code php>		<code php>
	~~begin_sql~~();		$transaction = $DB->start_delegated_transaction();
	$quba = question_engine::load_questions_usage_by_activity($attempt->uniqueid);		$quba = question_engine::load_questions_usage_by_activity($attempt->uniqueid);

Line 267:		Line 268:
	$attempt->sumgrades = $quba->get_total_mark();		$attempt->sumgrades = $quba->get_total_mark();
	update_record('quiz_attempts', $attempt);		update_record('quiz_attempts', $attempt);
	~~commit_sql~~();		$transaction->allow_commit();
	</code>		</code>

TimHunt: /* Other methods */

2010-12-02T22:42:01Z

Other methods

← Older revision		Revision as of 22:42, 2 December 2010
Line 249:		Line 249:
	</code>		</code>

			===Re-grading a question===

			You only need to re-grade a question when the question definition id edited, for example to change the scoring rules. If you are just changing the maximum possible score for a question, see the previous sub-section.

			This code example is adapted from <tt>mod/quiz/report/overview/report.php</tt>. It re-grades selected slots within a quiz attempt.
			<code php>
			begin_sql();
			$quba = question_engine::load_questions_usage_by_activity($attempt->uniqueid);

			foreach ($slots as $slot) {
			$oldfraction[$slot] = $quba->get_question_fraction($slot);
			$quba->regrade_question($slot);
			$newfraction[$slot] = $quba->get_question_fraction($slot);
			}

			question_engine::save_questions_usage_by_activity($quba);
			$attempt->sumgrades = $quba->get_total_mark();
			update_record('quiz_attempts', $attempt);
			commit_sql();
			</code>

	==See also==		==See also==

TimHunt: /* The simple case */

2010-12-02T22:41:21Z

The simple case

← Older revision		Revision as of 22:41, 2 December 2010
Line 156:		Line 156:
	<code php>		<code php>
	if ($attempt->timefinish) {		if ($attempt->timefinish) {
	$attempt->sumgrades = $~~this->~~quba->get_total_mark();		$attempt->sumgrades = $quba->get_total_mark();
	}		}
	$attempt->timemodified = $timenow;		$attempt->timemodified = $timenow;
	update_record('quiz_attempts', $~~this->~~attempt);		update_record('quiz_attempts', $attempt);
	</code>		</code>

TimHunt: /* Methods to help with settings UI */

2010-12-02T22:34:13Z

Methods to help with settings UI

← Older revision		Revision as of 22:34, 2 December 2010
Line 224:		Line 224:
	</code>		</code>

	Question marks are stored in the database to a fixed number of decimal places. To get a list of possible decimal place options, use		Question marks are stored in the database to a fixed number of decimal places. To get a list of possible decimal place display options, use
	<code php>		<code php>
	$options = question_engine::get_dp_options();		$options = question_engine::get_dp_options();

TimHunt: /* More selective processing */

2010-12-02T22:32:36Z

More selective processing

← Older revision		Revision as of 22:32, 2 December 2010
Line 164:		Line 164:
	===More selective processing===		===More selective processing===

	If you want something other than the default processing, you can use <tt>$submitteddata = $quba->extract_responses($slot); $quba->process_action($slot, $submitteddata);</tt>.		If you want something other than the default processing, you can use code like <tt>$submitteddata = $quba->extract_responses($slot); $quba->process_action($slot, $submitteddata);</tt> or something similar.

	===Handling scrollpos===		===Handling scrollpos===

TimHunt: /* Overview */

2010-12-02T22:27:47Z

Overview

← Older revision		Revision as of 22:27, 2 December 2010
Line 13:		Line 13:
	The key class you will be working with is <tt>question_usage_by_activity</tt>. This tracks an attempt at some questions, for example a quiz attempt. The usage should provide all the interface methods you need to do things with the question engine. You should rarely need to dive deeper into the inner workings of the question engine than this.		The key class you will be working with is <tt>question_usage_by_activity</tt>. This tracks an attempt at some questions, for example a quiz attempt. The usage should provide all the interface methods you need to do things with the question engine. You should rarely need to dive deeper into the inner workings of the question engine than this.

	A usage is a collection of <tt>question_attempt</tt> objects. A question attempt represents the state of the user's attempt at one question within the usage. When you add a question to the usage, you get back a '''slot''' number. This ~~server~~ to index that question within the attempt. Using slot numbers like this means that the same question can be added more than once to the same usage. A lot of the usage API calls take this slot number to indicate which question attempt to operate on. Other API methods let you perform batch actions on all the question attempts within the usage.		A usage is a collection of <tt>question_attempt</tt> objects. A question attempt represents the state of the user's attempt at one question within the usage. When you add a question to the usage, you get back a '''slot''' number. This serves to index that question within the attempt. Using slot numbers like this means that the same question can be added more than once to the same usage. A lot of the usage API calls take this slot number to indicate which question attempt to operate on. Other API methods let you perform batch actions on all the question attempts within the usage.


	==Starting an attempt at some questions==		==Starting an attempt at some questions==

TimHunt at 22:27, 2 December 2010

2010-12-02T22:27:03Z

← Older revision		Revision as of 22:27, 2 December 2010
Line 4:		Line 4:
	Previous section: [[Development:Developing_a_Question_Type\|Developing a Question Type]]		Previous section: [[Development:Developing_a_Question_Type\|Developing a Question Type]]

	The first example of a module that uses the question engine is the quiz module. Looking at how the quiz code works will let you see a real working example of what explained on this page.		The first example of a module that uses the question engine is the quiz module. Looking at how the quiz code works will let you see a real working example of what explained on this page. Another, much simpler example to look at is <tt>question/preview.php</tt>.

	Note that all the question engine code has extensive PHP documentor comments that should explain the purpose of every class and method. This document is supposed to provide an overview of the key points to get you started. It does not attempt to duplicate all the details in the PHPdocs.		Note that all the question engine code has extensive PHP documentor comments that should explain the purpose of every class and method. This document is supposed to provide an overview of the key points to get you started. It does not attempt to duplicate all the details in the PHPdocs.

TimHunt at 17:04, 2 December 2010

2010-12-02T17:04:40Z

← Older revision		Revision as of 17:04, 2 December 2010
Line 188:		Line 188:
	==Reports==		==Reports==

	~~TODO~~		Places like the quiz reports, we need to get data about a lot of usages at the same time. There are methods on the <tt>question_engine_data_mapper</tt> to do this. You should never access the data in the question engine tables directly.

			For example from the quiz grades report. (Again the example code has been simplified.)
			<code php>
			// $qubaids is an array of integer ids.
			$qubaidscondition = new qubaid_list($qubaids);

			$dm = new question_engine_data_mapper();
			$latesstepdata = $dm->load_questions_usages_latest_steps(
			$qubaidscondition, $slots);
			</code>

			<tt>qubaid_list</tt> is a subclass of the <tt>qubaid_condition</tt> class. This is an efficient way to represent a set of usage ids in a way that can be used in database queries. The other main subclass is <tt>qubaid_join</tt>. That could be used like this:
			<code php>
			$qubaidscondition = new qubaid_join("{$CFG->prefix}quiz_attempts quiza",
			'quiza.uniqueid', "quiza.quiz = $quizid");
			</code>

			Another example, from the quiz manual grading report is
			<code php>
			$dm = new question_engine_data_mapper();
			$statesummary = $dm->load_questions_usages_question_state_summary(
			$qubaidscondition, $slots);
			</code>

			(Perhaps the use of the class <tt>question_engine_data_mapper</tt> should be hidden inside a helper class <tt>question_engine_reporter</tt>?)


	==Other methods==		==Other methods==

	===~~Methodsto~~ help with settings UI===		===Methods to help with settings UI===

	When you want to present users with a choice of question behaviour (for example, the quiz How questions behave option) use		When you want to present users with a choice of question behaviour (for example, the quiz How questions behave option) use
Line 220:		Line 245:
	===Changing the score of a question in all attempts===		===Changing the score of a question in all attempts===

			Suppose you change the number of marks awarded to question 2 in the quiz, you need to change that information in every attempt at that quiz, you can do that with a call like
	<code php>		<code php>
	question_engine::set_max_mark_in_attempts($qubaids, $slot, $newmaxmark);		question_engine::set_max_mark_in_attempts($qubaids, $slot, $newmaxmark);
	</code>		</code>

	~~TODO.~~

	==See also==		==See also==

TimHunt at 14:20, 2 December 2010

2010-12-02T14:20:47Z

@@ Line 184: / Line 184: @@
 redirect($nexturl);
 </code>
 ==Reports==
@@ Line 189: / Line 190: @@
 TODO
 ==See also==

TimHunt: /* Processing responses */

2010-12-02T14:08:53Z

Processing responses

← Older revision		Revision as of 14:08, 2 December 2010
Line 136:		Line 136:
	Once again, the example here are inspired by real code from the quiz module, in this case <tt>mod/quiz/processattempt.php</tt>, but simplified to remove mention of the <tt>quiz_attempt</tt> class.		Once again, the example here are inspired by real code from the quiz module, in this case <tt>mod/quiz/processattempt.php</tt>, but simplified to remove mention of the <tt>quiz_attempt</tt> class.

	~~It is really quite simple:~~

			===The simple case===

			Normally, you just need to do something like:
	<code php>		<code php>
	$timenow = time();		$timenow = time();
Line 160:		Line 162:
	update_record('quiz_attempts', $this->attempt);		update_record('quiz_attempts', $this->attempt);
	</code>		</code>

			===More selective processing===

			If you want something other than the default processing, you can use <tt>$submitteddata = $quba->extract_responses($slot); $quba->process_action($slot, $submitteddata);</tt>.

	===Handling scrollpos===		===Handling scrollpos===