question_usage_by_activity Class Reference

Public Member Functions
	__construct ($component, $context)
	set_preferred_behaviour ($behaviour)
	get_preferred_behaviour ()
	get_owning_context ()
	get_owning_component ()
	get_id ()
	set_id_from_database ($id)
	get_observer ()
	set_observer ($observer)
	add_question (question_definition $question, $maxmark=null)
	get_question ($slot)
	get_slots ()
	get_first_question_number ()
	question_count ()
	get_attempt_iterator ()
	get_question_attempt ($slot)
	get_question_state ($slot)
	get_question_state_string ($slot, $showcorrectness)
	get_question_state_class ($slot, $showcorrectness)
	get_question_action_time ($slot)
	get_question_fraction ($slot)
	get_question_mark ($slot)
	get_question_max_mark ($slot)
	get_total_mark ()
	get_question_summary ($slot)
	get_response_summary ($slot)
	get_right_answer_summary ($slot)
	render_question ($slot, $options, $number=null)
	render_question_head_html ($slot)
	render_question_at_step ($slot, $seq, $options, $number=null)
	check_file_access ($slot, $options, $component, $filearea, $args, $forcedownload)
	replace_loaded_question_attempt_info ($slot, $qa)
	get_field_prefix ($slot)
	get_num_variants ($slot)
	get_variant ($slot)
	start_question ($slot, $variant=null)
	start_all_questions (question_variant_selection_strategy $variantstrategy=null, $timestamp=null, $userid=null)
	start_question_based_on ($slot, question_attempt $oldqa)
	process_all_actions ($timestamp=null, $postdata=null)
	extract_responses ($slot, $postdata=null)
	process_action ($slot, $submitteddata, $timestamp=null)
	validate_sequence_number ($slot, $postdata=null)
	update_question_flags ($postdata=null)
	get_correct_response ($slot)
	finish_question ($slot, $timestamp=null)
	finish_all_questions ($timestamp=null)
	manual_grade ($slot, $comment, $mark)
	regrade_question ($slot, $finished=false, $newmaxmark=null)
	regrade_all_questions ($finished=false)
Static Public Member Functions
static	load_from_records ($records, $qubaid)
Protected Member Functions
	check_slot ($slot)
Protected Attributes
	$id = null
	$preferredbehaviour = null
	$context
	$owningcomponent
	$questionattempts = array()
	$observer

---

Detailed Description

This class keeps track of a group of questions that are being attempted, and which state, and so on, each one is currently in.

A quiz attempt or a lesson attempt could use an instance of this class to keep track of all the questions in the attempt and process student submissions. It is basically a collection of {} objects.

The questions being attempted as part of this usage are identified by an integer that is passed into many of the methods as $slot. ($question->id is not used so that the same question can be used more than once in an attempt.)

Normally, calling code should be able to do everything it needs to be calling methods of this class. You should not normally need to get individual {} objects and play around with their inner workind, in code that it outside the quetsion engine.

Instances of this class correspond to rows in the question_usages table.

Copyright:

2009 The Open University http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Definition at line 52 of file questionusage.php.

---

Constructor & Destructor Documentation

__construct	(	$	component,
		$	context
	)

Create a new instance. Normally, calling code should use question_engine::make_questions_usage_by_activity() or question_engine::load_questions_usage_by_activity() rather than calling this constructor directly.

Parameters:

string	$component	the plugin creating this attempt. For example mod_quiz.
object	$context	the context this usage belongs to.

Definition at line 87 of file questionusage.php.

---

Member Function Documentation

add_question	(	question_definition $	question,
		$	maxmark = null
	)

Add another question to this usage.

The added question is not started until you call start_question() on it.

Parameters:

question_definition	$question	the question to add.
number	$maxmark	the maximum this question will be marked out of in this attempt (optional). If not given, $question->defaultmark is used.

Returns:

int the number used to identify this question within this usage.

Definition at line 167 of file questionusage.php.

Here is the call graph for this function:

check_file_access	(	$	slot,
		$	options,
		$	component,
		$	filearea,
		$	args,
		$	forcedownload
	)

Checks whether the users is allow to be served a particular file.

Parameters:

int	$slot	the number used to identify this question within this usage.
question_display_options	$options	the options that control display of the question.
string	$component	the name of the component we are serving files for.
string	$filearea	the name of the file area.
array	$args	the remaining bits of the file path.
bool	$forcedownload	whether the user must be forced to download the file.

Returns:

bool true if the user can access this file.

Definition at line 400 of file questionusage.php.

Here is the call graph for this function:

check_slot

(

$

slot

)

[protected]

Check whether $number actually corresponds to a question attempt that is part of this usage. Throws an exception if not.

Parameters:

int

$slot

a number allegedly identifying a question within this usage.

Definition at line 222 of file questionusage.php.

Here is the caller graph for this function:

extract_responses	(	$	slot,
		$	postdata = null
	)

Get the submitted data from the current request that belongs to this particular question.

Parameters:

int	$slot	the number used to identify this question within this usage.
	$postdata	optional, only intended for testing. Use this data instead of the data from $_POST.

Returns:

array submitted data specific to this question.

Definition at line 540 of file questionusage.php.

Here is the call graph for this function:

Here is the caller graph for this function:

finish_all_questions

(

$

timestamp = null

)

Finish the active phase of an attempt at a question. See finish_question() for a fuller description of what 'finish' means.

Definition at line 628 of file questionusage.php.

finish_question	(	$	slot,
		$	timestamp = null
	)

Finish the active phase of an attempt at a question.

This is an external act of finishing the attempt. Think, for example, of the 'Submit all and finish' button in the quiz. Some behaviours, (for example, immediatefeedback) give a way of finishing the active phase of a question attempt as part of a process_action() call.

After the active phase is over, the only changes possible are things like manual grading, or changing the flag state.

Parameters:

int

$slot

the number used to identify this question within this usage.

Definition at line 618 of file questionusage.php.

Here is the call graph for this function:

get_attempt_iterator

(

)

Note the part of the question_usage_by_activity comment that explains that question_attempt objects should be considered part of the inner workings of the question engine, and should not, if possible, be accessed directly.

Returns:

question_attempt_iterator for iterating over all the questions being attempted. as part of this usage.

Definition at line 212 of file questionusage.php.

Here is the caller graph for this function:

get_correct_response

(

$

slot

)

Get the correct response to a particular question. Passing the results of this method to process_action() will probably result in full marks. If it is not possible to compute a correct response, this method should return null.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

array that constitutes a correct response to this question.

Definition at line 601 of file questionusage.php.

Here is the call graph for this function:

get_field_prefix

(

$

slot

)

You should probably not use this method in code outside the question engine. The main reason for exposing it was for the benefit of unit tests.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

string return the prefix that is pre-pended to field names in the HTML that is output.

Definition at line 428 of file questionusage.php.

Here is the call graph for this function:

get_first_question_number

(

)

Returns:

int the identifying number of the first question that was added to this usage.

Definition at line 194 of file questionusage.php.

get_id

(

)

Returns:

int|string If this usage came from the database, then the id from the question_usages table is returned. Otherwise a random string is returned.

Definition at line 120 of file questionusage.php.

Here is the call graph for this function:

Here is the caller graph for this function:

get_num_variants

(

$

slot

)

Get the number of variants available for the question in this slot.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

int the number of variants available.

Definition at line 437 of file questionusage.php.

Here is the call graph for this function:

Here is the caller graph for this function:

get_observer

(

)

Returns:

question_usage_observer that is tracking changes made to this usage.

Definition at line 140 of file questionusage.php.

Here is the caller graph for this function:

get_owning_component

(

)

Returns:

string the name of the plugin that owns this attempt.

Definition at line 113 of file questionusage.php.

Here is the caller graph for this function:

get_owning_context

(

)

Returns:

object the context this usage belongs to.

Definition at line 108 of file questionusage.php.

Here is the caller graph for this function:

get_preferred_behaviour

(

)

Returns:

string the name of the preferred behaviour.

Definition at line 103 of file questionusage.php.

Here is the caller graph for this function:

get_question

(

$

slot

)

Get the question_definition for a question in this attempt.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

question_definition the requested question object.

Definition at line 184 of file questionusage.php.

Here is the call graph for this function:

get_question_action_time

(

$

slot

)

Get the time of the most recent action performed on a question.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

int timestamp.

Definition at line 276 of file questionusage.php.

Here is the call graph for this function:

get_question_attempt

(

$

slot

)

Note the part of the question_usage_by_activity comment that explains that question_attempt objects should be considered part of the inner workings of the question engine, and should not, if possible, be accessed directly.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

question_attempt the corresponding question_attempt object.

Definition at line 237 of file questionusage.php.

Here is the call graph for this function:

Here is the caller graph for this function:

get_question_fraction

(

$

slot

)

Get the current fraction awarded for the attempt at a question.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

number|null The current fraction for this question, or null if one has not been assigned yet.

Definition at line 286 of file questionusage.php.

Here is the call graph for this function:

get_question_mark

(

$

slot

)

Get the current mark awarded for the attempt at a question.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

number|null The current mark for this question, or null if one has not been assigned yet.

Definition at line 296 of file questionusage.php.

Here is the call graph for this function:

get_question_max_mark

(

$

slot

)

Get the maximum mark possible for the attempt at a question.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

number the available marks for this question.

Definition at line 305 of file questionusage.php.

Here is the call graph for this function:

get_question_state

(

$

slot

)

Get the current state of the attempt at a question.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

question_state.

Definition at line 247 of file questionusage.php.

Here is the call graph for this function:

get_question_state_class	(	$	slot,
		$	showcorrectness
	)

Parameters:

int	$slot	the number used to identify this question within this usage.
bool	$showcorrectness	Whether right/partial/wrong states should be distinguised.

Returns:

string a CSS class name for the current state.

Definition at line 267 of file questionusage.php.

Here is the call graph for this function:

get_question_state_string	(	$	slot,
		$	showcorrectness
	)

Parameters:

int	$slot	the number used to identify this question within this usage.
bool	$showcorrectness	Whether right/partial/wrong states should be distinguised.

Returns:

string A brief textual description of the current state.

Definition at line 257 of file questionusage.php.

Here is the call graph for this function:

get_question_summary

(

$

slot

)

Returns:

string a simple textual summary of the question that was asked.

Definition at line 329 of file questionusage.php.

Here is the call graph for this function:

get_response_summary

(

$

slot

)

Returns:

string a simple textual summary of response given.

Definition at line 336 of file questionusage.php.

Here is the call graph for this function:

get_right_answer_summary

(

$

slot

)

Returns:

string a simple textual summary of the correct resonse.

Definition at line 343 of file questionusage.php.

Here is the call graph for this function:

get_slots

(

)

Returns:

array all the identifying numbers of all the questions in this usage.

Definition at line 189 of file questionusage.php.

Here is the caller graph for this function:

get_total_mark

(

)

Get the current mark awarded for the attempt at a question.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

number|null The current mark for this question, or null if one has not been assigned yet.

Definition at line 315 of file questionusage.php.

get_variant

(

$

slot

)

Get the variant of the question being used in a given slot.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

int the variant of this question that is being used.

Definition at line 446 of file questionusage.php.

Here is the call graph for this function:

static load_from_records	(	$	records,
		$	qubaid
	)		[static]

Create a question_usage_by_activity from records loaded from the database.

For internal use only.

Parameters:

Iterator	$records	Raw records loaded from the database.
int	$questionattemptid	The id of the question_attempt to extract.

Returns:

question_usage_by_activity The newly constructed usage.

Definition at line 692 of file questionusage.php.

Here is the call graph for this function:

Here is the caller graph for this function:

manual_grade	(	$	slot,
		$	comment,
		$	mark
	)

Perform a manual grading action on a question attempt.

Parameters:

int	$slot	the number used to identify this question within this usage.
string	$comment	the comment being added to the question attempt.
number	$mark	the mark that is being assigned. Can be null to just add a comment.

Definition at line 642 of file questionusage.php.

Here is the call graph for this function:

process_action	(	$	slot,
		$	submitteddata,
		$	timestamp = null
	)

Process a specific action on a specific question.

Parameters:

int	$slot	the number used to identify this question within this usage.
	$submitteddata	the submitted data that constitutes the action.

Definition at line 549 of file questionusage.php.

Here is the call graph for this function:

Here is the caller graph for this function:

process_all_actions	(	$	timestamp = null,
		$	postdata = null
	)

Process all the question actions in the current request.

If there is a parameter slots included in the post data, then only those question numbers will be processed, otherwise all questions in this useage will be.

This function also does update_question_flags().

Parameters:

int	$timestamp	optional, use this timestamp as 'now'.
array	$postdata	optional, only intended for testing. Use this data instead of the data from $_POST.

Definition at line 512 of file questionusage.php.

Here is the call graph for this function:

question_count

(

)

Returns:

int the number of questions that are currently in this usage.

Definition at line 200 of file questionusage.php.

regrade_all_questions

(

$

finished = false

)

Regrade all the questions in this usage (without changing their max mark).

Parameters:

bool

$finished

whether each question should be forced to be finished after the regrade, or whether it may still be in progress (default false).

Definition at line 677 of file questionusage.php.

Here is the call graph for this function:

regrade_question	(	$	slot,
		$	finished = false,
		$	newmaxmark = null
	)

Regrade a question in this usage. This replays the sequence of submitted actions to recompute the outcomes.

Parameters:

int	$slot	the number used to identify this question within this usage.
bool	$finished	whether the question attempt should be forced to be finished after the regrade, or whether it may still be in progress (default false).
number	$newmaxmark	(optional) if given, will change the max mark while regrading.

Definition at line 656 of file questionusage.php.

Here is the call graph for this function:

Here is the caller graph for this function:

render_question	(	$	slot,
		$	options,
		$	number = null
	)

Get the core_question_renderer, in collaboration with appropriate qbehaviour_renderer and qtype_renderer subclasses, to generate the HTML to display this question.

Parameters:

int	$slot	the number used to identify this question within this usage.
question_display_options	$options	controls how the question is rendered.
string | null	$number	The question number to display. 'i' is a special value that gets displayed as Information. Null means no number is displayed.

Returns:

string HTML fragment representing the question.

Definition at line 357 of file questionusage.php.

Here is the call graph for this function:

render_question_at_step	(	$	slot,
		$	seq,
		$	options,
		$	number = null
	)

Like render_question() but displays the question at the past step indicated by $seq, rather than showing the latest step.

Parameters:

int	$slot	the number used to identify this question within this usage.
int	$seq	the seq number of the past state to display.
question_display_options	$options	controls how the question is rendered.
string | null	$number	The question number to display. 'i' is a special value that gets displayed as Information. Null means no number is displayed.

Returns:

string HTML fragment representing the question.

Definition at line 384 of file questionusage.php.

Here is the call graph for this function:

render_question_head_html

(

$

slot

)

Generate any bits of HTML that needs to go in the <head> tag when this question is displayed in the body.

Parameters:

int

$slot

the number used to identify this question within this usage.

Returns:

string HTML fragment.

Definition at line 368 of file questionusage.php.

Here is the call graph for this function:

replace_loaded_question_attempt_info	(	$	slot,
		$	qa
	)

Replace a particular question_attempt with a different one.

For internal use only. Used when reloading the state of a question from the database.

Parameters:

array	$records	Raw records loaded from the database.
int	$questionattemptid	The id of the question_attempt to extract.

Returns:

question_attempt The newly constructed question_attempt_step.

Definition at line 416 of file questionusage.php.

Here is the call graph for this function:

set_id_from_database

(

$

id

)

For internal use only. Used by question_engine_data_mapper to set the id when a usage is saved to the database.

Parameters:

int

$id

the newly determined id for this usage.

Definition at line 132 of file questionusage.php.

Here is the caller graph for this function:

set_observer

(

$

observer

)

You should almost certainly not call this method from your code. It is for internal use only.

Parameters:

question_usage_observer

that should be used to tracking changes made to this usage.

Definition at line 149 of file questionusage.php.

set_preferred_behaviour

(

$

behaviour

)

Parameters:

string

$behaviour

the name of an archetypal behaviour, that should be used by questions in this usage if possible.

Definition at line 97 of file questionusage.php.

start_all_questions	(	question_variant_selection_strategy $	variantstrategy = null,
		$	timestamp = null,
		$	userid = null
	)

Start the attempt at all questions that has been added to this usage.

Parameters:

	question_variant_selection_strategy	how to pick which variant of each question to use.
int	$timestamp	optional, the timstamp to record for this action. Defaults to now.
int	$userid	optional, the user to attribute this action to. Defaults to the current user.

Definition at line 473 of file questionusage.php.

start_question	(	$	slot,
		$	variant = null
	)

Start the attempt at a question that has been added to this usage.

Parameters:

int	$slot	the number used to identify this question within this usage.
int	$variant	which variant of the question to use. Must be between 1 and ->get_num_variants($slot) inclusive. If not give, a variant is chosen at random.

Definition at line 457 of file questionusage.php.

Here is the call graph for this function:

start_question_based_on	(	$	slot,
		question_attempt $	oldqa
	)

Start the attempt at a question, starting from the point where the previous question_attempt $oldqa had reached. This is used by the quiz 'Each attempt builds on last' mode.

Parameters:

int	$slot	the number used to identify this question within this usage.
question_attempt	$oldqa	a previous attempt at this quetsion that defines the starting point.

Definition at line 493 of file questionusage.php.

Here is the call graph for this function:

update_question_flags

(

$

postdata = null

)

Update the flagged state for all question_attempts in this usage, if their flagged state was changed in the request.

Parameters:

$postdata

optional, only intended for testing. Use this data instead of the data from $_POST.

Definition at line 584 of file questionusage.php.

Here is the caller graph for this function:

validate_sequence_number	(	$	slot,
		$	postdata = null
	)

Check that the sequence number, that detects weird things like the student clicking back, is OK. If the sequence check variable is not present, returns false. If the check variable is present and correct, returns true. If the variable is present and wrong, throws an exception.

Parameters:

int	$slot	the number used to identify this question within this usage.
array	$submitteddata	the submitted data that constitutes the action.

Returns:

bool true if the check variable is present and correct. False if it is missing. (Throws an exception if the check fails.)

Definition at line 565 of file questionusage.php.

Here is the call graph for this function:

Here is the caller graph for this function:

---

Field Documentation

$context [protected]

Definition at line 67 of file questionusage.php.

$id = null [protected]

Definition at line 58 of file questionusage.php.

$observer [protected]

Definition at line 76 of file questionusage.php.

$owningcomponent [protected]

Definition at line 70 of file questionusage.php.

$preferredbehaviour = null [protected]

Definition at line 64 of file questionusage.php.

$questionattempts = array() [protected]

Definition at line 73 of file questionusage.php.

---

The documentation for this class was generated from the following file:

• C:/xampp/htdocs/moodle/question/engine/questionusage.php