Tracks an attempt at one particular question in a question_usage_by_activity. More...

Inheritance diagram for question_attempt:

Public Member Functions
	__construct (question_definition $question, $usageid, question_usage_observer $observer=null, $maxmark=null)
	#- More...

	can_finish_during_attempt ()
	Whether this attempt at this question could be completed just by the student interacting with the question, before finish() is called. More...

	check_file_access ($options, $component, $filearea, $args, $forcedownload)
	Checks whether the users is allow to be served a particular file. More...

	classify_response ($whichtries=self::LAST_TRY)
	Break down a student response by sub part and classification. More...

	discard_autosaved_step ()
	Discard any auto-saved data belonging to this question attempt.

	finish ($timestamp=null, $userid=null)
	Perform a finish action on this question attempt. More...

	format_fraction_as_mark ($fraction, $dp)
	The a mark, formatted to the stated number of decimal places. More...

	format_mark ($dp)
	The current mark, formatted to the stated number of decimal places. More...

	format_max_mark ($dp)
	The maximum mark for this question attempt, formatted to the stated number of decimal places. More...

	fraction_to_mark ($fraction)

	get_all_submitted_qt_vars ($postdata)
	Get all the submitted question type data for this question, whithout checking that it is valid or cleaning it in any way. More...

	get_applicable_hint ()
	Return the hint that applies to the question in its current state, or null. More...

	get_behaviour ()
	For internal use only. More...

	get_behaviour_field_name ($varname)
	Get the name (in the sense a HTML name="" attribute, or a $_POST variable name) to use for a question_type variable belonging to this question_attempt. More...

	get_behaviour_name ()

	get_control_field_name ($varname)
	Get the name (in the sense a HTML name="" attribute, or a $_POST variable name) to use for a control variables belonging to this question_attempt. More...

	get_correct_response ()
	Get a set of response data for this question attempt that would get the best possible mark. More...

	get_current_manual_comment ()
	This is used by the manual grading code, particularly in association with validation. More...

	get_current_manual_mark ()
	This is used by the manual grading code, particularly in association with validation. More...

	get_database_id ()

	get_field_prefix ()
	Get the prefix added to variable names to give field names for this question attempt. More...

	get_flag_field_name ()
	Get the name (in the sense a HTML name="" attribute, or a $_POST variable name) to use for the field that indicates whether this question is flagged. More...

	get_fraction ()
	Get the current fraction of this question attempt. More...

	get_full_qa ()
	This method exists so that question_attempt_with_restricted_history can override it. More...

	get_full_step_iterator ()
	The same as }. More...

	get_last_action_time ()

	get_last_behaviour_var ($name, $default=null)
	Get the latest value of a particular behaviour variable. More...

	get_last_qt_data ($default=array())
	Get the qt data from the latest step that has any qt data. More...

	get_last_qt_files ($name, $contextid)
	Get the latest set of files for a particular question type variable of type question_attempt::PARAM_FILES. More...

	get_last_qt_var ($name, $default=null)
	Get the latest value of a particular question type variable. More...

	get_last_step ()
	Return the latest step in this question_attempt. More...

	get_last_step_with_behaviour_var ($name)
	Get the last step with a particular behaviour variable set. More...

	get_last_step_with_qt_var ($name)
	Get the last step with a particular question type varialbe set. More...

	get_manual_comment ()

	get_mark ()

	get_max_fraction ()

	get_max_mark ()

	get_metadata ($name)
	Return one of the bits of metadata for a this question attempt. More...

	get_min_fraction ()

	get_num_steps ()
	Get the number of steps in this attempt. More...

	get_outer_question_div_unique_id ()
	When the question is rendered, this unique id is added to the outer div of the question. More...

	get_qt_field_name ($varname)
	Get the name (in the sense a HTML name="" attribute, or a $_POST variable name) to use for a question_type variable belonging to this question_attempt. More...

	get_question ()

	get_question_summary ()

	get_response_file_url (stored_file $file)
	Get the URL of a file that belongs to a response variable of this question_attempt. More...

	get_response_summary ()

	get_reverse_step_iterator ()

	get_right_answer_summary ()

	get_sequence_check_count ()
	Get the number of real steps in this attempt. More...

	get_slot ()

	get_state ()
	Get the current state of this question attempt. More...

	get_state_class ($showcorrectness)

	get_state_string ($showcorrectness)

	get_step ($i)
	Get one of the steps in this attempt. More...

	get_step_iterator ()

	get_steps_with_submitted_response_iterator ()
	Allow access to steps with responses submitted by students for grading in a question attempt. More...

	get_submitted_data ($postdata=null)
	Get all the sumbitted data belonging to this question attempt from the current request. More...

	get_submitted_var ($name, $type, $postdata=null)
	Get a particular parameter from the current request. More...

	get_usage_id ()

	get_variant ()
	Get the variant of the question being used in a given slot. More...

	has_autosaved_step ()

	has_manual_comment ()

	has_marks ()

	is_flagged ()

	manual_grade ($comment, $mark, $commentformat=null, $timestamp=null, $userid=null)
	Perform a manual grading action on this attempt. More...

	prepare_response_files_draft_itemid ($name, $contextid)
	Prepare a draft file are for the files belonging the a response variable of this question attempt. More...

	process_action ($submitteddata, $timestamp=null, $userid=null, $existingstepid=null)
	Perform the action described by $submitteddata. More...

	process_autosave ($submitteddata, $timestamp=null, $userid=null)
	Process an autosave. More...

	regrade (question_attempt $oldqa, $finished)
	Perform a regrade. More...

	render ($options, $number, $page=null)
	Get the }, in collaboration with appropriate * qbehaviour_renderer} and qtype_renderer subclasses, to generate the HTML to display this question attempt in its current state. More...

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

	render_head_html ($page=null)
	Generate any bits of HTML that needs to go in the <head> tag when this question attempt is displayed in the body. More...

	rewrite_pluginfile_urls ($text, $component, $filearea, $itemid)
	Calls question_rewrite_question_urls() with appropriate parameters for content belonging to this question. More...

	rewrite_response_pluginfile_urls ($text, $contextid, $name, question_attempt_step $step)
	Calls question_rewrite_question_urls() with appropriate parameters for content belonging to responses to this question. More...

	select_variant (question_variant_selection_strategy $variantstrategy)
	Use a strategy to pick a variant. More...

	set_database_id ($id)
	For internal use only. More...

	set_flagged ($flagged)
	Set the flagged state of this question. More...

	set_max_mark ($maxmark)
	Change the max mark for this question_attempt. More...

	set_metadata ($name, $value)
	Set some metadata for this question attempt. More...

	set_observer ($observer)
	You should almost certainly not call this method from your code. More...

	set_question_summary ($questionsummary)
	Change the quetsion summary. More...

	set_slot ($slot)
	Set the number used to identify this question_attempt within the usage. More...

	set_usage_id ($usageid)
	Set the id of the question_usage_by_activity we belong to. More...

	start ($preferredbehaviour, $variant, $submitteddata=array(), $timestamp=null, $userid=null, $existingstepid=null)
	Start this question attempt. More...

	start_based_on (question_attempt $oldqa)
	Start this question attempt, starting from the point that the previous attempt $oldqa had reached. More...

	summarise_action (question_attempt_step $step)
	Produce a plain-text summary of what the user did during a step. More...

	validate_manual_mark ($currentmark)
	Validate the manual mark for a question. More...

Static Public Member Functions
static	load_from_records ($records, $questionattemptid, question_usage_observer $observer, $preferredbehaviour)
	Create a question_attempt_step from records loaded from the database. More...

Public Attributes
int	$timemodified = null
	last modified time.

string const	ALL_TRIES = 'alltries'
	means all tries at a question during an attempt by a user.

const	DISCARD = false

string const	FIRST_TRY = 'firsttry'
	means first try at a question during an attempt by a user.

const	KEEP = true
	#+ Constants used by the intereaction models to indicate whether the current pending step should be kept or discarded.

string const	LAST_TRY = 'lasttry'
	means last try at a question during an attempt by a user.

string const	PARAM_FILES = 'paramfiles'
	special value to indicate a response variable that is uploaded files.

string const	PARAM_MARK = PARAM_RAW_TRIMMED
	Should not longer be used. More...

string const	PARAM_RAW_FILES = 'paramrawfiles'
	special value to indicate a response variable that is uploaded files.

string const	USE_RAW_DATA = 'use raw data'
	this is a magic value that question types can return from question_definition::get_expected_data().

Protected Member Functions
	add_autosaved_step (question_attempt_step $step)
	Add an auto-saved step to this question attempt. More...

	add_step (question_attempt_step $step)
	Add a step to this question attempt. More...

	check_qt_var_name_restrictions ($expected)
	Ensure that no reserved prefixes are being used by installed question types. More...

	convert_autosaved_step_to_real_step ()
	If there is an autosaved step, convert it into a real save, so that it is preserved.

	extra_file_path_components ()
	Helper function used by } and * rewrite_response_pluginfile_urls(). More...

	get_expected_data ($expected, $postdata, $extraprefix)
	Get any data from the request that matches the list of expected params. More...

	get_resume_data ()
	Used by start_based_on() to get the data needed to start a new attempt from the point this attempt has go to. More...

	process_response_files ($name, $draftidname, $postdata=null, $text=null)
	Handle a submitted variable representing uploaded files. More...

Protected Attributes
question_attempt_step	$autosavedstep = null
	if, when we loaded the step from the DB, there was an autosaved step, we save a pointer to it here. More...

question_behaviour	$behaviour = null
	the behaviour controlling this attempt. More...

boolean	$flagged = false
	whether the user has flagged this attempt within the usage.

integer	$id = null
	if this attempts is stored in the question_attempts table, the id of that row.

float	$maxfraction = null
	the maximum fraction that can be scored at this question, so the maximum mark is $this->maxfraction * $this->maxmark.

float	$maxmark
	the maximum mark that can be scored at this question. More...

float	$minfraction = null
	the minimum fraction that can be scored at this question, so the minimum mark is $this->minfraction * $this->maxmark.

question_usage_observer	$observer
	tracks changes to the useage this attempt is part of.

question_definition	$question
	the question this is an attempt at.

string	$questionsummary = null
	plain text summary of the variant of the question the student saw. More...

string	$responsesummary = null
	plain text summary of the response the student gave. More...

string	$rightanswer = null
	plain text summary of the correct response to this question variant the student saw. More...

integer	$slot = null
	the number used to identify this question_attempt within the usage.

array	$steps = array()
	of . More...

integer string	$usageid
	the id of the question_usage_by_activity we belong to.

int	$variant
	which variant of the question to use.

Detailed Description

Tracks an attempt at one particular question in a question_usage_by_activity.

Most calling code should need to access objects of this class. They should be able to do everything through the usage interface. This class is an internal implementation detail of the question engine.

Instances of this class correspond to rows in the question_attempts table, and a collection of question_attempt_steps. Question inteaction models and question types do work with question_attempt objects.

Copyright: 2009 The Open University

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

question_attempt::__construct	(	question_definition	$question,
			$usageid,
		question_usage_observer	$observer = `null`,
			$maxmark = `null`
	)

#-

Create a new }. Normally you should create question_attempts * indirectly, by calling question_usage_by_activity::add_question().

Parameters

question_definition	$question	the question this is an attempt at.
int \| string	$usageid	The id of the } we belong to. Used by get_field_prefix().
question_usage_observer	$observer	tracks changes to the useage this attempt is part of. (Optional, a question_usage_null_observer is used if one is not passed.
number	$maxmark	the maximum grade for this question_attempt. If not passed, $question->defaultmark is used.

Member Function Documentation

◆ add_autosaved_step()

question_attempt::add_autosaved_step ( question_attempt_step $step )

protected

Add an auto-saved step to this question attempt.

We mark auto-saved steps by changing saving the step number with a - sign.

Parameters

question_attempt_step $step the new step.

◆ add_step()

question_attempt::add_step ( question_attempt_step $step )

protected

Add a step to this question attempt.

Parameters

question_attempt_step $step the new step.

Reimplemented in testable_question_attempt, and question_attempt_with_restricted_history.

◆ can_finish_during_attempt()

question_attempt::can_finish_during_attempt ( )

Whether this attempt at this question could be completed just by the student interacting with the question, before finish() is called.

Return values

boolean whether this attempt can finish naturally.

◆ check_file_access()

question_attempt::check_file_access	(	$options,
		$component,
		$filearea,
		$args,
		$forcedownload
	)

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

Parameters

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.

Return values

bool	true if the user can access this file.

◆ check_qt_var_name_restrictions()

question_attempt::check_qt_var_name_restrictions ( $expected )

protected

Ensure that no reserved prefixes are being used by installed question types.

Parameters

array $expected An array of question type variables

◆ classify_response()

question_attempt::classify_response ( $whichtries = self::LAST_TRY )

Break down a student response by sub part and classification.

See also question::classify_response. Used for response analysis.

Parameters

string $whichtries which tries to analyse for response analysis. Will be one of question_attempt::FIRST_TRY, LAST_TRY or ALL_TRIES. Defaults to question_attempt::LAST_TRY.

Return values

question_classified_response[]|question_classified_response[][] If $whichtries is question_attempt::FIRST_TRY or LAST_TRY index is subpartid and values are question_classified_response instances. If $whichtries is question_attempt::ALL_TRIES then first key is submitted response no and the second key is subpartid.

◆ extra_file_path_components()

question_attempt::extra_file_path_components ( )

protected

Helper function used by } and * rewrite_response_pluginfile_urls().

Return values

array ids that need to go into the file paths.

◆ finish()

question_attempt::finish	(	$timestamp = `null`,
		$userid = `null`
	)

Perform a finish action on this question attempt.

This corresponds to an external finish action, for example the user pressing Submit all and finish in the quiz, rather than using one of the controls that is part of the question.

Parameters

int	$timestamp	the time to record for the action. (If not given, use now.)
int	$userid	the user to attribute the aciton to. (If not given, use the current user.)

◆ format_fraction_as_mark()

question_attempt::format_fraction_as_mark	(	$fraction,
		$dp
	)

The a mark, formatted to the stated number of decimal places.

Uses format_float() to format floats according to the current locale.

Parameters

number	$fraction	a fraction.
int	$dp	number of decimal places.

Return values

string formatted mark.

◆ format_mark()

question_attempt::format_mark ( $dp )

The current mark, formatted to the stated number of decimal places.

Uses format_float() to format floats according to the current locale.

Parameters

int $dp number of decimal places.

Return values

string formatted mark.

◆ format_max_mark()

question_attempt::format_max_mark ( $dp )

The maximum mark for this question attempt, formatted to the stated number of decimal places.

Uses format_float() to format floats according to the current locale.

Parameters

int $dp number of decimal places.

Return values

string formatted maximum mark.

◆ fraction_to_mark()

question_attempt::fraction_to_mark ( $fraction )

Parameters

number | null $fraction a fraction.

Return values

number|null the corresponding mark.

◆ get_all_submitted_qt_vars()

question_attempt::get_all_submitted_qt_vars ( $postdata )

Get all the submitted question type data for this question, whithout checking that it is valid or cleaning it in any way.

Parameters

null | array $postdata null to use real post data, otherwise an array of data to use.

Return values

array name => value.

◆ get_applicable_hint()

question_attempt::get_applicable_hint ( )

Return the hint that applies to the question in its current state, or null.

Return values

question_hint|null

◆ get_behaviour()

question_attempt::get_behaviour ( )

For internal use only.

Return values

question_behaviour the behaviour that is controlling this attempt.

◆ get_behaviour_field_name()

question_attempt::get_behaviour_field_name ( $varname )

Get the name (in the sense a HTML name="" attribute, or a $_POST variable name) to use for a question_type variable belonging to this question_attempt.

See the comment on question_attempt_step for an explanation of question type and behaviour variables.

Parameters

string $varname The short form of the variable name.

Return values

string The field name to use.

◆ get_behaviour_name()

question_attempt::get_behaviour_name ( )

Return values

string the name of the behaviour that is controlling this attempt.

◆ get_control_field_name()

question_attempt::get_control_field_name ( $varname )

Get the name (in the sense a HTML name="" attribute, or a $_POST variable name) to use for a control variables belonging to this question_attempt.

Examples are :sequencecheck and :flagged

Parameters

string $varname The short form of the variable name.

Return values

string The field name to use.

◆ get_correct_response()

question_attempt::get_correct_response ( )

Get a set of response data for this question attempt that would get the best possible mark.

If it is not possible to compute a correct response, this method should return null.

Return values

array|null name => value pairs that could be passed to process_action().

◆ get_current_manual_comment()

question_attempt::get_current_manual_comment ( )

This is used by the manual grading code, particularly in association with validation.

If there is a comment submitted in the request, then use that, otherwise use the latest comment for this question.

Return values

array with three elements, comment, commentformat and mark.

◆ get_current_manual_mark()

question_attempt::get_current_manual_mark ( )

This is used by the manual grading code, particularly in association with validation.

It gets the current manual mark for a question, in exactly the string form that the teacher entered it, if possible. This may come from the current POST request, if there is one, otherwise from the database.

Return values

string the current manual mark for this question, in the format the teacher typed, if possible.

◆ get_database_id()

question_attempt::get_database_id ( )

Return values

int	the id of row for this question_attempt, if it is stored in the database. null if not.

◆ get_expected_data()

question_attempt::get_expected_data	(	$expected,
		$postdata,
		$extraprefix
	)

protected

Get any data from the request that matches the list of expected params.

Parameters

array	$expected	variable name => PARAM_... constant.
null \| array	$postdata	null to use real post data, otherwise an array of data to use.
string	$extraprefix	'-' or ''.

Return values

array name => value.

◆ get_field_prefix()

question_attempt::get_field_prefix ( )

Get the prefix added to variable names to give field names for this question attempt.

You should not use this method directly. This is an implementation detail anyway, but if you must access it, use question_usage_by_activity::get_field_prefix().

Return values

string The field name to use.

◆ get_flag_field_name()

question_attempt::get_flag_field_name ( )

Get the name (in the sense a HTML name="" attribute, or a $_POST variable name) to use for the field that indicates whether this question is flagged.

Return values

string The field name to use.

◆ get_fraction()

question_attempt::get_fraction ( )

Get the current fraction of this question attempt.

That is, the fraction of the latest step, or null if this question has not yet been graded.

Return values

number the current fraction.

◆ get_full_qa()

question_attempt::get_full_qa ( )

This method exists so that question_attempt_with_restricted_history can override it.

You should not normally need to call it.

Return values

question_attempt return ourself.

Reimplemented in question_attempt_with_restricted_history.

◆ get_full_step_iterator()

question_attempt::get_full_step_iterator ( )

The same as }.

However, for a * question_attempt_with_restricted_history this returns the full list of steps, while get_step_iterator() returns only the limited history.

Return values

question_attempt_step_iterator for iterating over the steps in this attempt, in order.

Reimplemented in question_attempt_with_restricted_history.

◆ get_last_action_time()

question_attempt::get_last_action_time ( )

Return values

int	the timestamp of the most recent step in this question attempt.

◆ get_last_behaviour_var()

question_attempt::get_last_behaviour_var	(	$name,
		$default = `null`
	)

Get the latest value of a particular behaviour variable.

That is, get the value from the latest step that has it set. Return null if it is not set in any step.

Parameters

string	$name	the name of the variable to get.
	mixed	default the value to return in the variable has never been set. (Optional, defaults to null.)

Return values

mixed string value, or $default if it has never been set.

◆ get_last_qt_data()

question_attempt::get_last_qt_data ( $default = array() )

Get the qt data from the latest step that has any qt data.

Return $default array if it is no step has qt data.

Parameters

mixed default the value to return no step has qt data. (Optional, defaults to an empty array.)

Return values

array|mixed the data, or $default if there is not any.

◆ get_last_qt_files()

question_attempt::get_last_qt_files	(	$name,
		$contextid
	)

Get the latest set of files for a particular question type variable of type question_attempt::PARAM_FILES.

Parameters

string	$name	the name of the associated variable.
int	$contextid	the context to which the files are linked.

Return values

array of stored_files.

◆ get_last_qt_var()

question_attempt::get_last_qt_var	(	$name,
		$default = `null`
	)

Get the latest value of a particular question type variable.

That is, get the value from the latest step that has it set. Return null if it is not set in any step.

Parameters

string	$name	the name of the variable to get.
	mixed	default the value to return in the variable has never been set. (Optional, defaults to null.)

Return values

mixed string value, or $default if it has never been set.

◆ get_last_step()

question_attempt::get_last_step ( )

Return the latest step in this question_attempt.

For internal/test code use only.

Return values

question_attempt_step

◆ get_last_step_with_behaviour_var()

question_attempt::get_last_step_with_behaviour_var ( $name )

Get the last step with a particular behaviour variable set.

Parameters

string $name the name of the variable to get.

Return values

question_attempt_step the last step, or a step with no variables if there was not a real step.

◆ get_last_step_with_qt_var()

question_attempt::get_last_step_with_qt_var ( $name )

Get the last step with a particular question type varialbe set.

Parameters

string $name the name of the variable to get.

Return values

question_attempt_step the last step, or a step with no variables if there was not a real step.

◆ get_manual_comment()

question_attempt::get_manual_comment ( )

Return values

array(string,int) the most recent manual comment that was added to this question, the FORMAT_... it is and the step itself.

◆ get_mark()

question_attempt::get_mark ( )

Return values

number the current mark for this question. } * get_max_mark().

◆ get_max_fraction()

question_attempt::get_max_fraction ( )

Return values

float the maximum mark possible for this question attempt.

◆ get_max_mark()

question_attempt::get_max_mark ( )

Return values

float the maximum mark possible for this question attempt. In fact, this is not strictly the maximum, becuase get_max_fraction may return a number greater than 1. It might be better to think of this as a question weight.

◆ get_metadata()

question_attempt::get_metadata ( $name )

Return one of the bits of metadata for a this question attempt.

Parameters

string $name the name of the metadata variable to return.

Return values

string the value of that metadata variable.

◆ get_min_fraction()

question_attempt::get_min_fraction ( )

Return values

float the maximum mark possible for this question attempt.

◆ get_num_steps()

question_attempt::get_num_steps ( )

Get the number of steps in this attempt.

For internal/test code use only.

Return values

int	the number of steps we currently have.

◆ get_outer_question_div_unique_id()

question_attempt::get_outer_question_div_unique_id ( )

When the question is rendered, this unique id is added to the outer div of the question.

It can be used to uniquely reference the question from JavaScript.

Return values

string

id added to the outer

when the question is rendered.

◆ get_qt_field_name()

question_attempt::get_qt_field_name ( $varname )

Get the name (in the sense a HTML name="" attribute, or a $_POST variable name) to use for a question_type variable belonging to this question_attempt.

See the comment on question_attempt_step for an explanation of question type and behaviour variables.

Parameters

string $varname The short form of the variable name.

Return values

string The field name to use.

◆ get_question()

question_attempt::get_question ( )

Return values

question_definition the question this is an attempt at.

◆ get_question_summary()

question_attempt::get_question_summary ( )

Return values

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

◆ get_response_file_url()

question_attempt::get_response_file_url ( stored_file $file )

Get the URL of a file that belongs to a response variable of this question_attempt.

Parameters

stored_file $file the file to link to.

Return values

string the URL of that file.

◆ get_response_summary()

question_attempt::get_response_summary ( )

Return values

string a simple textual summary of response given.

◆ get_resume_data()

question_attempt::get_resume_data ( )

protected

Used by start_based_on() to get the data needed to start a new attempt from the point this attempt has go to.

Return values

array name => value pairs.

◆ get_reverse_step_iterator()

question_attempt::get_reverse_step_iterator ( )

Return values

question_attempt_reverse_step_iterator for iterating over the steps in this attempt, in reverse order.

◆ get_right_answer_summary()

question_attempt::get_right_answer_summary ( )

Return values

string a simple textual summary of the correct resonse.

◆ get_sequence_check_count()

question_attempt::get_sequence_check_count ( )

Get the number of real steps in this attempt.

This is put as a hidden field in the HTML, so that when we receive some data to process, then we can check that it came from the question in the state we are now it.

Return values

int	a number that summarises the current state of this question attempt.

◆ get_slot()

question_attempt::get_slot ( )

Return values

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

◆ get_state()

question_attempt::get_state ( )

Get the current state of this question attempt.

That is, the state of the latest step.

Return values

question_state

◆ get_state_class()

question_attempt::get_state_class ( $showcorrectness )

Parameters

bool $showcorrectness Whether right/partial/wrong states should be distinguised.

Return values

string a CSS class name for the current state.

◆ get_state_string()

question_attempt::get_state_string ( $showcorrectness )

Parameters

bool $showcorrectness Whether right/partial/wrong states should be distinguised.

Return values

string A brief textual description of the current state.

◆ get_step()

question_attempt::get_step ( $i )

Get one of the steps in this attempt.

Parameters

int $i the step number, which counts from 0.

Return values

question_attempt_step

◆ get_step_iterator()

question_attempt::get_step_iterator ( )

Return values

question_attempt_step_iterator for iterating over the steps in this attempt, in order.

◆ get_steps_with_submitted_response_iterator()

question_attempt::get_steps_with_submitted_response_iterator ( )

Allow access to steps with responses submitted by students for grading in a question attempt.

Return values

question_attempt_steps_with_submitted_response_iterator to access all steps with submitted data for questions that allow multiple submissions that count towards grade, per attempt.

◆ get_submitted_data()

question_attempt::get_submitted_data ( $postdata = null )

Get all the sumbitted data belonging to this question attempt from the current request.

Parameters

array $postdata (optional, only inteded for testing use) take the data from this array, instead of from $_POST.

Return values

array name => value pairs that could be passed to process_action().

◆ get_submitted_var()

question_attempt::get_submitted_var	(	$name,
		$type,
		$postdata = `null`
	)

Get a particular parameter from the current request.

A wrapper round optional_param(), except that the results is returned without slashes.

Parameters

string	$name	the paramter name.
int	$type	one of the standard PARAM_... constants, or one of the special extra constands defined by this class.
array	$postdata	(optional, only inteded for testing use) take the data from this array, instead of from $_POST.

Return values

mixed the requested value.

◆ get_usage_id()

question_attempt::get_usage_id ( )

Return values

int|string the id of the question_usage_by_activity we belong to.

◆ get_variant()

question_attempt::get_variant ( )

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

Return values

int	the variant number.

◆ has_autosaved_step()

question_attempt::has_autosaved_step ( )

Return values

boolean whether this question_attempt has autosaved data from some time in the past.

◆ has_manual_comment()

question_attempt::has_manual_comment ( )

Return values

bool	Whether this question attempt has had a manual comment added.

◆ has_marks()

question_attempt::has_marks ( )

Return values

bool	whether this question attempt has a non-zero maximum mark.

◆ is_flagged()

question_attempt::is_flagged ( )

Return values

bool	whether this question is currently flagged.

◆ load_from_records()

static question_attempt::load_from_records	(		$records,
			$questionattemptid,
		question_usage_observer	$observer,
			$preferredbehaviour
	)

static

Create a question_attempt_step 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.
question_usage_observer	$observer	the observer that will be monitoring changes in us.
string	$preferredbehaviour	the preferred behaviour under which we are operating.

Return values

question_attempt The newly constructed question_attempt.

◆ manual_grade()

question_attempt::manual_grade	(	$comment,
		$mark,
		$commentformat = `null`,
		$timestamp = `null`,
		$userid = `null`
	)

Perform a manual grading action on this attempt.

Parameters

string	$comment	the comment being added.
float	$mark	the new mark. If null, then only a comment is added.
int	$commentformat	the FORMAT_... for $comment. Must be given.
int	$timestamp	the time to record for the action. (If not given, use now.)
int	$userid	the user to attribute the aciton to. (If not given, use the current user.)

◆ prepare_response_files_draft_itemid()

question_attempt::prepare_response_files_draft_itemid	(	$name,
		$contextid
	)

Prepare a draft file are for the files belonging the a response variable of this question attempt.

The draft area is populated with the files from the most recent step having files.

Parameters

string	$name	the variable name the files belong to.
int	$contextid	the id of the context the quba belongs to.

Return values

int	the draft itemid.

◆ process_action()

question_attempt::process_action	(	$submitteddata,
		$timestamp = `null`,
		$userid = `null`,
		$existingstepid = `null`
	)

Perform the action described by $submitteddata.

Parameters

array	$submitteddata	the submitted data the determines the action.
int	$timestamp	the time to record for the action. (If not given, use now.)
int	$userid	the user to attribute the action to. (If not given, use the current user.)
int	$existingstepid	used by the regrade code.

Reimplemented in question_attempt_with_restricted_history.

◆ process_autosave()

question_attempt::process_autosave	(	$submitteddata,
		$timestamp = `null`,
		$userid = `null`
	)

Process an autosave.

Parameters

array	$submitteddata	the submitted data the determines the action.
int	$timestamp	the time to record for the action. (If not given, use now.)
int	$userid	the user to attribute the action to. (If not given, use the current user.)

Return values

bool	whether anything was saved.

◆ process_response_files()

question_attempt::process_response_files	(	$name,
		$draftidname,
		$postdata = `null`,
		$text = `null`
	)

protected

Handle a submitted variable representing uploaded files.

Parameters

string	$name	the field name.
string	$draftidname	the field name holding the draft file area id.
array	$postdata	(optional, only inteded for testing use) take the data from this array, instead of from $_POST. At the moment, this behaves as if there were no files.
string	$text	optional reponse text.

Return values

question_file_saver that can be used to save the files later.

◆ regrade()

question_attempt::regrade	(	question_attempt	$oldqa,
			$finished
	)

Perform a regrade.

This replays all the actions from $oldqa into this attempt.

Parameters

question_attempt	$oldqa	the attempt to regrade.
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).

◆ render()

question_attempt::render	(	$options,
		$number,
		$page = `null`
	)

Get the }, in collaboration with appropriate * qbehaviour_renderer} and qtype_renderer subclasses, to generate the HTML to display this question attempt in its current state.

Parameters

question_display_options	$options	controls how the question is rendered.
string \| null	$number	The question number to display.
moodle_page \| null	$page	the page the question is being redered to. (Optional. Defaults to $PAGE.)

Return values

string HTML fragment representing the question.

◆ render_at_step()

question_attempt::render_at_step	(	$seq,
		$options,
		$number,
		$preferredbehaviour
	)

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

Parameters

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.
string	$preferredbehaviour	the preferred behaviour. It is slightly annoying that this needs to be passed, but unavoidable for now.

Return values

string HTML fragment representing the question.

◆ render_head_html()

question_attempt::render_head_html ( $page = null )

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

Return values

string HTML fragment.

◆ rewrite_pluginfile_urls()

question_attempt::rewrite_pluginfile_urls	(	$text,
		$component,
		$filearea,
		$itemid
	)

Calls question_rewrite_question_urls() with appropriate parameters for content belonging to this question.

Parameters

string	$text	the content to output.
string	$component	the component name (normally 'question' or 'qtype_...')
string	$filearea	the name of the file area.
int	$itemid	the item id.

Return values

string the content with the URLs rewritten.

◆ rewrite_response_pluginfile_urls()

question_attempt::rewrite_response_pluginfile_urls	(		$text,
			$contextid,
			$name,
		question_attempt_step	$step
	)

Calls question_rewrite_question_urls() with appropriate parameters for content belonging to responses to this question.

Parameters

string	$text	the text to update the URLs in.
int	$contextid	the id of the context the quba belongs to.
string	$name	the variable name the files belong to.
question_attempt_step	$step	the step the response is coming from.

Return values

string the content with the URLs rewritten.

◆ select_variant()

question_attempt::select_variant ( question_variant_selection_strategy $variantstrategy )

Use a strategy to pick a variant.

Parameters

question_variant_selection_strategy $variantstrategy a strategy.

Return values

int	the selected variant.

◆ set_database_id()

question_attempt::set_database_id ( $id )

For internal use only.

Set the id of the corresponding database row.

Parameters

int $id the id of row for this question_attempt, if it is stored in the database.

Reimplemented in question_attempt_with_restricted_history.

◆ set_flagged()

question_attempt::set_flagged ( $flagged )

Set the flagged state of this question.

Parameters

bool $flagged the new state.

Reimplemented in question_attempt_with_restricted_history.

◆ set_max_mark()

question_attempt::set_max_mark ( $maxmark )

Change the max mark for this question_attempt.

Parameters

float $maxmark the new max mark.

◆ set_metadata()

question_attempt::set_metadata	(	$name,
		$value
	)

Set some metadata for this question attempt.

Parameters

string	$name	the name of the metadata variable to return.
string	$value	the value to set that metadata variable to.

◆ set_observer()

question_attempt::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 qa.

◆ set_question_summary()

question_attempt::set_question_summary ( $questionsummary )

Change the quetsion summary.

Note, that this is almost never necessary. This method was only added to work around a limitation of the Opaque protocol, which only sends questionLine at the end of an attempt.

Parameters

string $questionsummary the new summary to set.

Reimplemented in question_attempt_with_restricted_history.

◆ set_slot()

question_attempt::set_slot ( $slot )

Set the number used to identify this question_attempt within the usage.

For internal use only.

Parameters

int $slot

Reimplemented in question_attempt_with_restricted_history.

◆ set_usage_id()

question_attempt::set_usage_id ( $usageid )

Set the id of the question_usage_by_activity we belong to.

For internal use only.

Parameters

int|string the new id.

Reimplemented in question_attempt_with_restricted_history.

◆ start()

question_attempt::start	(	$preferredbehaviour,
		$variant,
		$submitteddata = `array()`,
		$timestamp = `null`,
		$userid = `null`,
		$existingstepid = `null`
	)

Start this question attempt.

You should not call this method directly. Call question_usage_by_activity::start_question() instead.

Parameters

string \| question_behaviour	$preferredbehaviour	the name of the desired archetypal behaviour, or an actual model instance.
int	$variant	the variant of the question to start. Between 1 and $this->get_question()->get_num_variants() inclusive.
array	$submitteddata	optional, used when re-starting to keep the same initial state.
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.
int	$existingstepid	optional, if this step is going to replace an existing step (for example, during a regrade) this is the id of the previous step we are replacing.

Reimplemented in question_attempt_with_restricted_history.

◆ start_based_on()

question_attempt::start_based_on ( question_attempt $oldqa )

Start this question attempt, starting from the point that the previous attempt $oldqa had reached.

You should not call this method directly. Call question_usage_by_activity::start_question_based_on() instead.

Parameters

question_attempt $oldqa a previous attempt at this quetsion that defines the starting point.

◆ summarise_action()

question_attempt::summarise_action ( question_attempt_step $step )

Produce a plain-text summary of what the user did during a step.

Parameters

question_attempt_step $step the step in quetsion.

Return values

string a summary of what was done during that step.

◆ validate_manual_mark()

question_attempt::validate_manual_mark ( $currentmark )

Validate the manual mark for a question.

Parameters

string $currentmark the user input (e.g. '1,0', '1,0' or 'invalid'.

Return values

string any errors with the value, or '' if it is OK.

Member Data Documentation

◆ $autosavedstep

question_attempt_step question_attempt::$autosavedstep = null

protected

if, when we loaded the step from the DB, there was an autosaved step, we save a pointer to it here.

(It is also added to the $steps array.)

◆ $behaviour

question_behaviour question_attempt::$behaviour = null

protected

the behaviour controlling this attempt.

null until start() is called.

◆ $maxmark

float question_attempt::$maxmark

protected

the maximum mark that can be scored at this question.

Actually, this is only really a nominal maximum. It might be better thought of as the question weight.

◆ $questionsummary

string question_attempt::$questionsummary = null

protected

plain text summary of the variant of the question the student saw.

Intended for reporting purposes.

◆ $responsesummary

string question_attempt::$responsesummary = null

protected

plain text summary of the response the student gave.

Intended for reporting purposes.

◆ $rightanswer

string question_attempt::$rightanswer = null

protected

plain text summary of the correct response to this question variant the student saw.

The format should be similar to responsesummary. Intended for reporting purposes.

◆ $steps

array question_attempt::$steps = array()

protected

of .

The steps in this attempt.

◆ PARAM_MARK

string const question_attempt::PARAM_MARK = PARAM_RAW_TRIMMED

Should not longer be used.

Deprecated:: since Moodle 3.0

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

question/engine/questionattempt.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ add_autosaved_step()

◆ add_step()

◆ can_finish_during_attempt()

◆ check_file_access()

◆ check_qt_var_name_restrictions()

◆ classify_response()

◆ extra_file_path_components()

◆ finish()

◆ format_fraction_as_mark()

◆ format_mark()

◆ format_max_mark()

◆ fraction_to_mark()

◆ get_all_submitted_qt_vars()

◆ get_applicable_hint()

◆ get_behaviour()

◆ get_behaviour_field_name()

◆ get_behaviour_name()

◆ get_control_field_name()

◆ get_correct_response()

◆ get_current_manual_comment()

◆ get_current_manual_mark()

◆ get_database_id()

◆ get_expected_data()

◆ get_field_prefix()

◆ get_flag_field_name()

◆ get_fraction()

◆ get_full_qa()

◆ get_full_step_iterator()

◆ get_last_action_time()

◆ get_last_behaviour_var()

◆ get_last_qt_data()

◆ get_last_qt_files()

◆ get_last_qt_var()

◆ get_last_step()

◆ get_last_step_with_behaviour_var()

◆ get_last_step_with_qt_var()

◆ get_manual_comment()

◆ get_mark()

◆ get_max_fraction()

◆ get_max_mark()

◆ get_metadata()

◆ get_min_fraction()

◆ get_num_steps()

◆ get_outer_question_div_unique_id()

◆ get_qt_field_name()

◆ get_question()

◆ get_question_summary()

◆ get_response_file_url()

◆ get_response_summary()

◆ get_resume_data()

◆ get_reverse_step_iterator()

◆ get_right_answer_summary()

◆ get_sequence_check_count()

◆ get_slot()

◆ get_state()

◆ get_state_class()

◆ get_state_string()

◆ get_step()

◆ get_step_iterator()

◆ get_steps_with_submitted_response_iterator()

◆ get_submitted_data()

◆ get_submitted_var()

◆ get_usage_id()

◆ get_variant()

◆ has_autosaved_step()

◆ has_manual_comment()

◆ has_marks()

◆ is_flagged()

◆ load_from_records()

◆ manual_grade()

◆ prepare_response_files_draft_itemid()