Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 3.9.x will end* 10 May 2021 (12 months).
  • Bug fixes for security issues in 3.9.x will end* 8 May 2023 (36 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.

Differences Between: [Versions 39 and 311] [Versions 39 and 400] [Versions 39 and 401] [Versions 39 and 402] [Versions 39 and 403]

This file defines the question attempt step class, and a few related classes.

Copyright: 2009 The Open University
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 749 lines (27 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 0 files

Defines 5 classes

question_attempt_step:: (26 methods):
  __construct()
  get_id()
  get_state()
  set_state()
  get_fraction()
  set_fraction()
  get_user_id()
  get_timecreated()
  has_qt_var()
  get_qt_var()
  set_qt_var()
  get_qt_files()
  prepare_response_files_draft_itemid()
  prepare_response_files_draft_itemid_with_text()
  rewrite_response_pluginfile_urls()
  get_qt_data()
  has_behaviour_var()
  get_behaviour_var()
  set_behaviour_var()
  get_behaviour_data()
  get_submitted_data()
  get_all_data()
  set_metadata_var()
  has_metadata_var()
  get_metadata_var()
  load_from_records()

question_attempt_pending_step:: (6 methods):
  set_new_response_summary()
  get_new_response_summary()
  response_summary_changed()
  set_new_variant_number()
  get_new_variant_number()
  variant_number_changed()

question_attempt_step_read_only:: (4 methods):
  set_state()
  set_fraction()
  set_qt_var()
  set_behaviour_var()

question_null_step:: (3 methods):
  get_state()
  set_state()
  get_fraction()

question_attempt_step_subquestion_adapter:: (24 methods):
  __construct()
  add_prefix()
  remove_prefix()
  filter_array()
  get_state()
  set_state()
  get_fraction()
  set_fraction()
  get_user_id()
  get_timecreated()
  has_qt_var()
  get_qt_var()
  set_qt_var()
  get_qt_data()
  has_behaviour_var()
  get_behaviour_var()
  set_behaviour_var()
  get_behaviour_data()
  get_submitted_data()
  get_all_data()
  get_qt_files()
  prepare_response_files_draft_itemid()
  prepare_response_files_draft_itemid_with_text()
  rewrite_response_pluginfile_urls()


Class: question_attempt_step  - X-Ref

Stores one step in a {@link question_attempt}.

The most important attributes of a step are the state, which is one of the
{@link question_state} constants, the fraction, which may be null, or a
number bewteen the attempt's minfraction and maxfraction, and the array of submitted
data, about which more later.

A step also tracks the time it was created, and the user responsible for
creating it.

The submitted data is basically just an array of name => value pairs, with
certain conventions about the to divide the variables into four = two times two
categories.

Variables may either belong to the behaviour, in which case the
name starts with a '-', or they may belong to the question type in which case
they name does not start with a '-'.

Second, variables may either be ones that came form the original request, in
which case the name does not start with an _, or they are cached values that
were created during processing, in which case the name does start with an _.

That is, each name will start with one of '', '_'. '-' or '-_'. The remainder
of the name should match the regex [a-z][a-z0-9]*.

These variables can be accessed with {@link get_behaviour_var()} and {@link get_qt_var()},
- to be clear, ->get_behaviour_var('x') gets the variable with name '-x' -
and values whose names start with '_' can be set using {@link set_behaviour_var()}
and {@link set_qt_var()}. There are some other methods like {@link has_behaviour_var()}
to check wether a varaible with a particular name is set, and {@link get_behaviour_data()}
to get all the behaviour data as an associative array.

__construct($data = array()   X-Ref
You should not need to call this constructor in your own code. Steps are
normally created by {@link question_attempt} methods like
{@link question_attempt::process_action()}.

param: array $data the submitted data that defines this step.
param: int $timestamp the time to record for the action. (If not given, use now.)
param: int $userid the user to attribute the aciton to. (If not given, use the current user.)
param: int $existingstepid if this step is going to replace an existing step

get_id()   X-Ref

return: int|null The id of this step in the database. null if this step

get_state()   X-Ref
No description

set_state($state)   X-Ref
Set the state. Normally only called by behaviours.

param: question_state $state one of the {@link question_state} constants.

get_fraction()   X-Ref

return: null|number the fraction (grade on a scale of

set_fraction($fraction)   X-Ref
Set the fraction. Normally only called by behaviours.

param: null|number $fraction the fraction to set.

get_user_id()   X-Ref
No description

get_timecreated()   X-Ref
No description

has_qt_var($name)   X-Ref

param: string $name the name of a question type variable to look for in the submitted data.
return: bool whether a variable with this name exists in the question type data.

get_qt_var($name)   X-Ref

param: string $name the name of a question type variable to look for in the submitted data.
return: string the requested variable, or null if the variable is not set.

set_qt_var($name, $value)   X-Ref
Set a cached question type variable.

param: string $name the name of the variable to set. Must match _[a-z][a-z0-9]*.
param: string $value the value to set.

get_qt_files($name, $contextid)   X-Ref
Get the latest set of files for a particular question type variable of
type question_attempt::PARAM_FILES.

param: string $name the name of the associated variable.
return: array of {@link stored_files}.

prepare_response_files_draft_itemid($name, $contextid)   X-Ref
Prepare a draft file are for the files belonging the a response variable
of this step.

param: string $name the variable name the files belong to.
param: int $contextid the id of the context the quba belongs to.
return: int the draft itemid.

prepare_response_files_draft_itemid_with_text($name, $contextid, $text)   X-Ref
Prepare a draft file are for the files belonging the a response variable
of this step, while rewriting the URLs in some text.

param: string $name the variable name the files belong to.
param: int $contextid the id of the context the quba belongs to.
param: string $text the text to update the URLs in.
return: array(int, string) the draft itemid and the text with URLs rewritten.

rewrite_response_pluginfile_urls($text, $contextid, $name, $extras)   X-Ref
Rewrite the @@PLUGINFILE@@ tokens in a response variable from this step
that contains links to file. Normally you should probably call
{@link question_attempt::rewrite_response_pluginfile_urls()} instead of
calling this method directly.

param: string $text the text to update the URLs in.
param: int $contextid the id of the context the quba belongs to.
param: string $name the variable name the files belong to.
param: array $extra extra file path components.
return: string the rewritten text.

get_qt_data()   X-Ref
Get all the question type variables.

param: array name => value pairs.

has_behaviour_var($name)   X-Ref

param: string $name the name of a behaviour variable to look for in the submitted data.
return: bool whether a variable with this name exists in the question type data.

get_behaviour_var($name)   X-Ref

param: string $name the name of a behaviour variable to look for in the submitted data.
return: string the requested variable, or null if the variable is not set.

set_behaviour_var($name, $value)   X-Ref
Set a cached behaviour variable.

param: string $name the name of the variable to set. Must match _[a-z][a-z0-9]*.
param: string $value the value to set.

get_behaviour_data()   X-Ref
Get all the behaviour variables.

param: array name => value pairs.

get_submitted_data()   X-Ref
Get all the submitted data, but not the cached data. behaviour
variables have the - at the start of their name. This is only really
intended for use by {@link question_attempt::regrade()}, it should not
be considered part of the public API.

param: array name => value pairs.

get_all_data()   X-Ref
Get all the data. behaviour variables have the - at the start of
their name. This is only intended for internal use, for example by
{@link question_engine_data_mapper::insert_question_attempt_step()},
however, it can occasionally be useful in test code. It should not be
considered part of the public API of this class.

param: array name => value pairs.

set_metadata_var($name, $value)   X-Ref
Set a metadata variable.

Do not call this method directly from  your code. It is for internal
use only. You should call {@link question_usage::set_question_attempt_metadata()}.

param: string $name the name of the variable to set. [a-z][a-z0-9]*.
param: string $value the value to set.

has_metadata_var($name)   X-Ref
Whether this step has a metadata variable.

Do not call this method directly from  your code. It is for internal
use only. You should call {@link question_usage::get_question_attempt_metadata()}.

param: string $name the name of the variable to set. [a-z][a-z0-9]*.
return: bool the value to set previously, or null if this variable was never set.

get_metadata_var($name)   X-Ref
Get a metadata variable.

Do not call this method directly from  your code. It is for internal
use only. You should call {@link question_usage::get_question_attempt_metadata()}.

param: string $name the name of the variable to set. [a-z][a-z0-9]*.
return: string the value to set previously, or null if this variable was never set.

load_from_records($records, $attemptstepid, $qtype = null)   X-Ref
Create a question_attempt_step from records loaded from the database.

param: Iterator $records Raw records loaded from the database.
param: int $stepid The id of the records to extract.
param: string $qtype The question type of which this is an attempt.
return: question_attempt_step The newly constructed question_attempt_step.

Class: question_attempt_pending_step  - X-Ref

A subclass of {@link question_attempt_step} used when processing a new submission.

When we are processing some new submitted data, which may or may not lead to
a new step being added to the {@link question_usage_by_activity} we create an
instance of this class. which is then passed to the question behaviour and question
type for processing. At the end of processing we then may, or may not, keep it.

set_new_response_summary($responsesummary)   X-Ref
If as a result of processing this step, the response summary for the
question attempt should changed, you should call this method to set the
new summary.

param: string $responsesummary the new response summary.

get_new_response_summary()   X-Ref
Get the new response summary, if there is one.

return: string the new response summary, or null if it has not changed.

response_summary_changed()   X-Ref
Whether this processing this step has changed the response summary.

return: bool true if there is a new response summary.

set_new_variant_number($variant)   X-Ref
If as a result of processing this step, you identify that this variant of the
question is actually identical to the another one, you may change the
variant number recorded, in order to give better statistics. For an example
see qbehaviour_opaque.

param: int $variant the new variant number.

get_new_variant_number()   X-Ref
Get the new variant number, if there is one.

return: int the new variant number, or null if it has not changed.

variant_number_changed()   X-Ref
Whether this processing this step has changed the variant number.

return: bool true if there is a new variant number.

Class: question_attempt_step_read_only  - X-Ref

A subclass of {@link question_attempt_step} that cannot be modified.

set_state($state)   X-Ref
No description

set_fraction($fraction)   X-Ref
No description

set_qt_var($name, $value)   X-Ref
No description

set_behaviour_var($name, $value)   X-Ref
No description

Class: question_null_step  - X-Ref

A null {@link question_attempt_step} returned from
{@link question_attempt::get_last_step()} etc. when a an attempt has just been
created and there is no actual step.

get_state()   X-Ref
No description

set_state($state)   X-Ref
No description

get_fraction()   X-Ref
No description

Class: question_attempt_step_subquestion_adapter  - X-Ref

This is an adapter class that wraps a {@link question_attempt_step} and
modifies the get/set_*_data methods so that they operate only on the parts
that belong to a particular subquestion, as indicated by an extra prefix.

__construct($realqas, $extraprefix)   X-Ref
Constructor.

param: question_attempt_step $realqas the step to wrap. (Can be null if you
param: unknown_type $extraprefix the extra prefix that is used for date fields.

add_prefix($field)   X-Ref
Add the extra prefix to a field name.

param: string $field the plain field name.
return: string the field name with the extra bit of prefix added.

remove_prefix($field)   X-Ref
Remove the extra prefix from a field name if it is present.

param: string $field the extended field name.
return: string the field name with the extra bit of prefix removed, or

filter_array($data)   X-Ref
Filter some data to keep only those entries where the key contains
extraprefix, and remove the extra prefix from the reutrned arrary.

param: array $data some of the data stored in this step.
return: array the data with the keys ajusted using {@link remove_prefix()}.

get_state()   X-Ref
No description

set_state($state)   X-Ref
No description

get_fraction()   X-Ref
No description

set_fraction($fraction)   X-Ref
No description

get_user_id()   X-Ref
No description

get_timecreated()   X-Ref
No description

has_qt_var($name)   X-Ref
No description

get_qt_var($name)   X-Ref
No description

set_qt_var($name, $value)   X-Ref
No description

get_qt_data()   X-Ref
No description

has_behaviour_var($name)   X-Ref
No description

get_behaviour_var($name)   X-Ref
No description

set_behaviour_var($name, $value)   X-Ref
No description

get_behaviour_data()   X-Ref
No description

get_submitted_data()   X-Ref
No description

get_all_data()   X-Ref
No description

get_qt_files($name, $contextid)   X-Ref
No description

prepare_response_files_draft_itemid($name, $contextid)   X-Ref
No description

prepare_response_files_draft_itemid_with_text($name, $contextid, $text)   X-Ref
No description

rewrite_response_pluginfile_urls($text, $contextid, $name, $extras)   X-Ref
No description