Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
question_attempt Class Reference

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

Inheritance diagram for question_attempt:
question_attempt_with_restricted_history testable_question_attempt

Public Member Functions

 __construct (question_definition $question, $usageid, question_usage_observer $observer=null, $maxmark=null)
 #-
 
 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.
 
 check_file_access ($options, $component, $filearea, $args, $forcedownload)
 Checks whether the users is allow to be served a particular file.
 
 classify_response ($whichtries=self::LAST_TRY)
 Break down a student response by sub part and classification.
 
 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.
 
 format_fraction_as_mark ($fraction, $dp)
 The a mark, formatted to the stated number of decimal places.
 
 format_mark ($dp)
 The current mark, formatted to the stated number of decimal places.
 
 format_max_mark ($dp)
 The maximum mark for this question attempt, formatted to the stated number of decimal places.
 
 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.
 
 get_applicable_hint ()
 Return the hint that applies to the question in its current state, or null.
 
 get_behaviour ($requirequestioninitialised=true)
 For internal use only.
 
 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.
 
 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.
 
 get_correct_response ()
 Get a set of response data for this question attempt that would get the best possible mark.
 
 get_current_manual_comment ()
 This is used by the manual grading code, particularly in association with validation.
 
 get_current_manual_mark ()
 This is used by the manual grading code, particularly in association with validation.
 
 get_database_id ()
 
 get_field_prefix ()
 Get the prefix added to variable names to give field names for this 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.
 
 get_fraction ()
 Get the current fraction of this question attempt.
 
 get_full_qa ()
 This method exists so that question_attempt_with_restricted_history can override it.
 
 get_full_step_iterator ()
 The same as get_step_iterator().
 
 get_last_action_time ()
 
 get_last_behaviour_var ($name, $default=null)
 Get the latest value of a particular behaviour variable.
 
 get_last_qt_data ($default=array())
 Get the qt data from the latest step that has any qt data.
 
 get_last_qt_files ($name, $contextid)
 Get the latest set of files for a particular question type variable of type question_attempt\PARAM_FILES.
 
 get_last_qt_var ($name, $default=null)
 Get the latest value of a particular question type variable.
 
 get_last_step ()
 Return the latest step in this question_attempt.
 
 get_last_step_with_behaviour_var ($name)
 Get the last step with a particular behaviour variable set.
 
 get_last_step_with_qt_var ($name)
 Get the last step with a particular question type varialbe set.
 
 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.
 
 get_min_fraction ()
 
 get_num_steps ()
 Get the number of steps in this attempt.
 
 get_outer_question_div_unique_id ()
 When the question is rendered, this unique id is added to the outer div of the question.
 
 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.
 
 get_question ($requirequestioninitialised=true)
 Get the question that is being attempted.
 
 get_question_id ()
 Get the id of the question being attempted.
 
 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.
 
 get_response_summary ()
 
 get_reverse_step_iterator ()
 
 get_right_answer_summary ()
 
 get_sequence_check_count ()
 Get the number of real steps in this attempt.
 
 get_slot ()
 
 get_state ()
 Get the current state of this question attempt.
 
 get_state_class ($showcorrectness)
 
 get_state_string ($showcorrectness)
 
 get_step ($i)
 Get one of the steps in this attempt.
 
 get_step_iterator ()
 
 get_steps_with_submitted_response_iterator ()
 Allow access to steps with responses submitted by students for grading in a question attempt.
 
 get_submitted_data ($postdata=null)
 Get all the sumbitted data belonging to this question attempt from the current request.
 
 get_submitted_var ($name, $type, $postdata=null)
 Get a particular parameter from the current request.
 
 get_usage_id ()
 
 get_variant ()
 Get the variant of the question being used in a given slot.
 
 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.
 
 prepare_response_files_draft_itemid ($name, $contextid)
 Prepare a draft file are for the files belonging the a response variable of this question attempt.
 
 process_action ($submitteddata, $timestamp=null, $userid=null, $existingstepid=null)
 Perform the action described by $submitteddata.
 
 process_autosave ($submitteddata, $timestamp=null, $userid=null)
 Process an autosave.
 
 regrade (question_attempt $oldqa, $finished)
 Perform a regrade.
 
 render ($options, $number, $page=null)
 Get the core_question_renderer, in collaboration with appropriate qbehaviour_renderer and qtype_renderer subclasses, to generate the HTML to display this question attempt in its current state.
 
 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.
 
 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.
 
 rewrite_pluginfile_urls ($text, $component, $filearea, $itemid)
 Calls question_rewrite_question_urls() with appropriate parameters for content belonging to this question.
 
 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.
 
 select_variant (question_variant_selection_strategy $variantstrategy)
 Use a strategy to pick a variant.
 
 set_database_id ($id)
 For internal use only.
 
 set_flagged ($flagged)
 Set the flagged state of this question.
 
 set_max_mark ($maxmark)
 Change the max mark for this question_attempt.
 
 set_metadata ($name, $value)
 Set some metadata for this question attempt.
 
 set_observer ($observer)
 You should almost certainly not call this method from your code.
 
 set_question_summary ($questionsummary)
 Change the quetsion summary.
 
 set_slot ($slot)
 Set the number used to identify this question_attempt within the usage.
 
 set_usage_id ($usageid)
 Set the id of the question_usage_by_activity we belong to.
 
 start ($preferredbehaviour, $variant, $submitteddata=array(), $timestamp=null, $userid=null, $existingstepid=null)
 Start this question attempt.
 
 start_based_on (question_attempt $oldqa)
 Start this question attempt, starting from the point that the previous attempt $oldqa had reached.
 
 summarise_action (question_attempt_step $step)
 Produce a plain-text summary of what the user did during a step.
 
 validate_can_regrade_with_other_version (question_definition $otherversion)
 Verify if this question_attempt in can be regraded with that other question version.
 
 validate_manual_mark ($currentmark)
 Validate the manual mark for a question.
 

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.
 

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.
 
string const PARAM_RAW_FILES = 'paramrawfiles'
 special value to indicate a response variable that is uploaded files.
 
bool const QUESTION_STATE_APPLIED = true
 used to manage the lazy-initialisation of question objects.
 
bool const QUESTION_STATE_NOT_APPLIED = false
 used to manage the lazy-initialisation of question objects.
 
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.
 
 add_step (question_attempt_step $step)
 Add a step to this question attempt.
 
 check_qt_var_name_restrictions ($expected)
 Ensure that no reserved prefixes are being used by installed question types.
 
 convert_autosaved_step_to_real_step ()
 If there is an autosaved step, convert it into a real save, so that it is preserved.
 
 ensure_question_initialised ()
 This method is part of the lazy-initialisation of question objects.
 
 extra_file_path_components ()
 Helper function used by rewrite_pluginfile_urls() and rewrite_response_pluginfile_urls().
 
 get_attempt_state_data_to_regrade_with_version (question_attempt_step $oldstep, question_definition $otherversion)
 Helper used by regrading.
 
 get_expected_data ($expected, $postdata, $extraprefix)
 Get any data from the request that matches the list of expected params.
 
 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.
 
 process_response_files ($name, $draftidname, $postdata=null, $text=null)
 Handle a submitted variable representing uploaded files.
 

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.
 
question_behaviour $behaviour = null
 the behaviour controlling this attempt.
 
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.
 
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.
 
bool $questioninitialised
 tracks whether $question has had question_definition::start_attempt() or question_definition::apply_attempt_state() called.
 
string $questionsummary = null
 plain text summary of the variant of the question the student saw.
 
string $responsesummary = null
 plain text summary of the response the student gave.
 
string $rightanswer = null
 plain text summary of the correct response to this question variant the student saw.
 
integer $slot = null
 the number used to identify this question_attempt within the usage.
 
array $steps = array()
 of .
 
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.

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 question_attempt. Normally you should create question_attempts indirectly, by calling question_usage_by_activity::add_question().

Parameters
question_definition$questionthe question this is an attempt at.
int | string$usageidThe id of the question_usage_by_activity we belong to. Used by get_field_prefix().
question_usage_observer$observertracks changes to the useage this attempt is part of. (Optional, a question_usage_null_observer is used if one is not passed.
number$maxmarkthe 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$stepthe new step.

◆ add_step()

question_attempt::add_step ( question_attempt_step $step)
protected

Add a step to this question attempt.

Parameters
question_attempt_step$stepthe new step.

Reimplemented in question_attempt_with_restricted_history, and testable_question_attempt.

◆ 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
booleanwhether 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$optionsthe options that control display of the question.
string$componentthe name of the component we are serving files for.
string$fileareathe name of the file area.
array$argsthe remaining bits of the file path.
bool$forcedownloadwhether the user must be forced to download the file.
Return values
booltrue 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$expectedAn 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$whichtrieswhich 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.

◆ ensure_question_initialised()

question_attempt::ensure_question_initialised ( )
protected

This method is part of the lazy-initialisation of question objects.

Methods which require $this->question to be fully initialised (to have had init_first_step or apply_attempt_state called on it) should call this method before proceeding.

◆ extra_file_path_components()

question_attempt::extra_file_path_components ( )
protected

Helper function used by rewrite_pluginfile_urls() and rewrite_response_pluginfile_urls().

Return values
arrayids 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$timestampthe time to record for the action. (If not given, use now.)
int$useridthe 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$fractiona fraction.
int$dpnumber of decimal places.
Return values
stringformatted 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$dpnumber of decimal places.
Return values
stringformatted 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$dpnumber of decimal places.
Return values
stringformatted maximum mark.

◆ fraction_to_mark()

question_attempt::fraction_to_mark ( $fraction)
Parameters
number | null$fractiona fraction.
Return values
number|nullthe 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$postdatanull to use real post data, otherwise an array of data to use.
Return values
arrayname => 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_attempt_state_data_to_regrade_with_version()

question_attempt::get_attempt_state_data_to_regrade_with_version ( question_attempt_step $oldstep,
question_definition $otherversion )
protected

Helper used by regrading.

Get the data from the first step of the old attempt and, if necessary, update it to be suitable for use with the other version of the question.

Parameters
question_attempt_step$oldstepFirst step at an attempt at $otherversion of this question.
question_definition$otherversionAnother version of the question being attempted.
Return values
arrayupdated data required to restart an attempt with the current version of this question.

◆ get_behaviour()

question_attempt::get_behaviour ( $requirequestioninitialised = true)

For internal use only.

Parameters
bool$requirequestioninitialisedset this to false if you don't need the behaviour initialised, which may improve performance.
Return values
question_behaviourthe 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$varnameThe short form of the variable name.
Return values
stringThe field name to use.

◆ get_behaviour_name()

question_attempt::get_behaviour_name ( )
Return values
stringthe 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$varnameThe short form of the variable name.
Return values
stringThe 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|nullname => 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
arraywith 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
stringthe current manual mark for this question, in the format the teacher typed, if possible.

◆ get_database_id()

question_attempt::get_database_id ( )
Return values
intthe 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$expectedvariable name => PARAM_... constant.
null | array$postdatanull to use real post data, otherwise an array of data to use.
string$extraprefix'-' or ''.
Return values
arrayname => 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
stringThe 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
stringThe 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
numberthe 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_attemptreturn ourself.

Reimplemented in question_attempt_with_restricted_history.

◆ get_full_step_iterator()

question_attempt::get_full_step_iterator ( )

The same as get_step_iterator().

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_iteratorfor 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
intthe 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$namethe name of the variable to get.
mixeddefault the value to return in the variable has never been set. (Optional, defaults to null.)
Return values
mixedstring 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
mixeddefault the value to return no step has qt data. (Optional, defaults to an empty array.)
Return values
array|mixedthe 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$namethe name of the associated variable.
int$contextidthe context to which the files are linked.
Return values
arrayof 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$namethe name of the variable to get.
mixeddefault the value to return in the variable has never been set. (Optional, defaults to null.)
Return values
mixedstring 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$namethe name of the variable to get.
Return values
question_attempt_stepthe 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$namethe name of the variable to get.
Return values
question_attempt_stepthe 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
numberthe current mark for this question. get_fraction() * get_max_mark().

◆ get_max_fraction()

question_attempt::get_max_fraction ( )
Return values
floatthe maximum mark possible for this question attempt.

◆ get_max_mark()

question_attempt::get_max_mark ( )
Return values
floatthe 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$namethe name of the metadata variable to return.
Return values
stringthe value of that metadata variable.

◆ get_min_fraction()

question_attempt::get_min_fraction ( )
Return values
floatthe 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
intthe 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
stringid 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$varnameThe short form of the variable name.
Return values
stringThe field name to use.

◆ get_question()

question_attempt::get_question ( $requirequestioninitialised = true)

Get the question that is being attempted.

Parameters
bool$requirequestioninitialisedset this to false if you don't need the behaviour initialised, which may improve performance.
Return values
question_definitionthe question this is an attempt at.

◆ get_question_id()

question_attempt::get_question_id ( )

Get the id of the question being attempted.

Return values
intquestion id.

◆ get_question_summary()

question_attempt::get_question_summary ( )
Return values
stringa 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$filethe file to link to.
Return values
stringthe URL of that file.

◆ get_response_summary()

question_attempt::get_response_summary ( )
Return values
stringa 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
arrayname => value pairs.

◆ get_reverse_step_iterator()

question_attempt::get_reverse_step_iterator ( )
Return values
question_attempt_reverse_step_iteratorfor iterating over the steps in this attempt, in reverse order.

◆ get_right_answer_summary()

question_attempt::get_right_answer_summary ( )
Return values
stringa 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
inta number that summarises the current state of this question attempt.

◆ get_slot()

question_attempt::get_slot ( )
Return values
intthe 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$showcorrectnessWhether right/partial/wrong states should be distinguised.
Return values
stringa CSS class name for the current state.

◆ get_state_string()

question_attempt::get_state_string ( $showcorrectness)
Parameters
bool$showcorrectnessWhether right/partial/wrong states should be distinguised.
Return values
stringA brief textual description of the current state.

◆ get_step()

question_attempt::get_step ( $i)

Get one of the steps in this attempt.

Parameters
int$ithe step number, which counts from 0.
Return values
question_attempt_step

◆ get_step_iterator()

question_attempt::get_step_iterator ( )
Return values
question_attempt_step_iteratorfor 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_iteratorto 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
arrayname => 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$namethe paramter name.
int$typeone 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
mixedthe requested value.

◆ get_usage_id()

question_attempt::get_usage_id ( )
Return values
int|stringthe 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
intthe variant number.

◆ has_autosaved_step()

question_attempt::has_autosaved_step ( )
Return values
booleanwhether this question_attempt has autosaved data from some time in the past.

◆ has_manual_comment()

question_attempt::has_manual_comment ( )
Return values
boolWhether this question attempt has had a manual comment added.

◆ has_marks()

question_attempt::has_marks ( )
Return values
boolwhether this question attempt has a non-zero maximum mark.

◆ is_flagged()

question_attempt::is_flagged ( )
Return values
boolwhether 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$recordsRaw records loaded from the database.
int$questionattemptidThe id of the question_attempt to extract.
question_usage_observer$observerthe observer that will be monitoring changes in us.
string$preferredbehaviourthe preferred behaviour under which we are operating.
Return values
question_attemptThe 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$commentthe comment being added.
float$markthe new mark. If null, then only a comment is added.
int$commentformatthe FORMAT_... for $comment. Must be given.
int$timestampthe time to record for the action. (If not given, use now.)
int$useridthe 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$namethe variable name the files belong to.
int$contextidthe id of the context the quba belongs to.
Return values
intthe draft itemid.

◆ process_action()

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

Perform the action described by $submitteddata.

Parameters
array$submitteddatathe submitted data the determines the action.
int$timestampthe time to record for the action. (If not given, use now.)
int$useridthe user to attribute the action to. (If not given, use the current user.)
int$existingstepidused 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$submitteddatathe submitted data the determines the action.
int$timestampthe time to record for the action. (If not given, use now.)
int$useridthe user to attribute the action to. (If not given, use the current user.)
Return values
boolwhether 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$namethe field name.
string$draftidnamethe 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$textoptional reponse text.
Return values
question_file_saverthat 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$oldqathe attempt to regrade.
bool$finishedwhether 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 core_question_renderer, 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$optionscontrols how the question is rendered.
string | null$numberThe question number to display.
moodle_page | null$pagethe page the question is being redered to. (Optional. Defaults to $PAGE.)
Return values
stringHTML 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$seqthe seq number of the past state to display.
question_display_options$optionscontrols how the question is rendered.
string | null$numberThe question number to display. 'i' is a special value that gets displayed as Information. Null means no number is displayed.
string$preferredbehaviourthe preferred behaviour. It is slightly annoying that this needs to be passed, but unavoidable for now.
Return values
stringHTML 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
stringHTML 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$textthe content to output.
string$componentthe component name (normally 'question' or 'qtype_...')
string$fileareathe name of the file area.
int$itemidthe item id.
Return values
stringthe 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$textthe text to update the URLs in.
int$contextidthe id of the context the quba belongs to.
string$namethe variable name the files belong to.
question_attempt_step$stepthe step the response is coming from.
Return values
stringthe 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$variantstrategya strategy.
Return values
intthe 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$idthe 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$flaggedthe 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$maxmarkthe new max mark.

◆ set_metadata()

question_attempt::set_metadata ( $name,
$value )

Set some metadata for this question attempt.

Parameters
string$namethe name of the metadata variable to return.
string$valuethe 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_observerthat 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$questionsummarythe 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|stringthe 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$preferredbehaviourthe name of the desired archetypal behaviour, or an actual behaviour instance.
int$variantthe variant of the question to start. Between 1 and $this->get_question()->get_num_variants() inclusive.
array$submitteddataoptional, used when re-starting to keep the same initial state.
int$timestampoptional, the timstamp to record for this action. Defaults to now.
int$useridoptional, the user to attribute this action to. Defaults to the current user.
int$existingstepidoptional, 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$oldqaa 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$stepthe step in question.
Return values
stringa summary of what was done during that step.

◆ validate_can_regrade_with_other_version()

question_attempt::validate_can_regrade_with_other_version ( question_definition $otherversion)

Verify if this question_attempt in can be regraded with that other question version.

Parameters
question_definition$otherversiona different version of the question to use in the regrade.
Return values
string|nullnull if the regrade can proceed, else a reason why not.

◆ validate_manual_mark()

question_attempt::validate_manual_mark ( $currentmark)

Validate the manual mark for a question.

Parameters
string$currentmarkthe user input (e.g. '1,0', '1,0' or 'invalid'.
Return values
stringany 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.

◆ ALL_TRIES

string const question_attempt::ALL_TRIES = 'alltries'

means all tries at a question during an attempt by a user.

Constant used when calling classify response.

◆ FIRST_TRY

string const question_attempt::FIRST_TRY = 'firsttry'

means first try at a question during an attempt by a user.

Constant used when calling classify response.

◆ LAST_TRY

string const question_attempt::LAST_TRY = 'lasttry'

means last try at a question during an attempt by a user.

Constant used when calling classify response.

◆ 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: