Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
  • Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
  • PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/question/behaviour/ -> behaviourbase.php (source)

[Source view]

Defines the question behaviour base class

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

Defines 4 classes

question_behaviour:: (29 methods):
  __construct()
  get_name()
  can_finish_during_attempt()
  render()
  check_file_access()
  get_renderer()
  adjust_display_options()
  get_applicable_hint()
  get_min_fraction()
  get_max_fraction()
  get_expected_data()
  get_expected_qt_data()
  get_correct_response()
  get_question_summary()
  get_right_answer_summary()
  get_resume_data()
  get_our_resume_data()
  classify_response()
  get_state_string()
  init_first_step()
  apply_attempt_state()
  is_same_comment()
  process_autosave()
  process_comment()
  format_comment()
  summarise_manual_comment()
  summarise_start()
  summarise_finish()
  step_has_a_submitted_response()

question_behaviour_with_save:: (9 methods):
  required_question_definition_type()
  apply_attempt_state()
  is_same_response()
  is_complete_response()
  process_autosave()
  process_save()
  summarise_submit()
  summarise_save()
  summarise_finish()

question_behaviour_with_multiple_tries:: (1 method):
  step_has_a_submitted_response()

question_cbm:: (7 methods):
  default_certainty()
  adjust_fraction()
  get_string()
  get_short_string()
  summary_with_certainty()
  optimal_probablility_low()
  optimal_probablility_high()


Class: question_behaviour  - X-Ref

The base class for question behaviours.

A question behaviour is used by the question engine, specifically by
a {@link question_attempt} to manage the flow of actions a student can take
as they work through a question, and later, as a teacher manually grades it.
In turn, the behaviour will delegate certain processing to the
relevant {@link question_definition}.

__construct(question_attempt $qa, $preferredbehaviour)   X-Ref
Normally you should not call this constuctor directly. The appropriate
behaviour object is created automatically as part of
{@link question_attempt::start()}.

param: question_attempt $qa the question attempt we will be managing.
param: string $preferredbehaviour the type of behaviour that was actually

get_name()   X-Ref

return: string the name of this behaviour. For example the name of

can_finish_during_attempt()   X-Ref
Whether the current attempt at this question could be completed just by the
student interacting with the question, before $qa->finish() is called.

return: boolean whether the attempt can finish naturally.

render(question_display_options $options, $number,core_question_renderer $qoutput, qtype_renderer $qtoutput)   X-Ref
Cause the question to be renderered. This gets the appropriate behaviour
renderer using {@link get_renderer()}, and adjusts the display
options using {@link adjust_display_options()} and then calls
{@link core_question_renderer::question()} to do the work.

return: string HTML fragment.
param: question_display_options $options controls what should and should not be displayed.
param: string|null $number the question number to display.
param: core_question_renderer $qoutput the question renderer that will coordinate everything.
param: qtype_renderer $qtoutput the question type renderer that will be helping.

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

return: bool true if the user can access this file.
param: question_display_options $options the options that control display of the question.
param: string $component the name of the component we are serving files for.
param: string $filearea the name of the file area.
param: array $args the remaining bits of the file path.
param: bool $forcedownload whether the user must be forced to download the file.

get_renderer(moodle_page $page)   X-Ref

return: qbehaviour_renderer get the appropriate renderer to use for this model.
param: moodle_page $page the page to render for.

adjust_display_options(question_display_options $options)   X-Ref
Make any changes to the display options before a question is rendered, so
that it can be displayed in a way that is appropriate for the statue it is
currently in. For example, by default, if the question is finished, we
ensure that it is only ever displayed read-only.

param: question_display_options $options the options to adjust. Just change

get_applicable_hint()   X-Ref
Get the most applicable hint for the question in its current state.

return: question_hint the most applicable hint, or null, if none.

get_min_fraction()   X-Ref
What is the minimum fraction that can be scored for this question.
Normally this will be based on $this->question->get_min_fraction(),
but may be modified in some way by the behaviour.

return: number the minimum fraction when this question is attempted under

get_max_fraction()   X-Ref
Return the maximum possible fraction that can be scored for this question.
Normally this will be based on $this->question->get_max_fraction(),
but may be modified in some way by the behaviour.

return: number the maximum fraction when this question is attempted under

get_expected_data()   X-Ref
Return an array of the behaviour variables that could be submitted
as part of a question of this type, with their types, so they can be
properly cleaned.

return: array variable name => PARAM_... constant.

get_expected_qt_data()   X-Ref
Return an array of question type variables for the question in its current
state. Normally, if {@link adjust_display_options()} would set
{@link question_display_options::$readonly} to true, then this method
should return an empty array, otherwise it should return
$this->question->get_expected_data(). Thus, there should be little need to
override this method.

return: array|string variable name => PARAM_... constant, or, as a special case

get_correct_response()   X-Ref
Return an array of any im variables, and the value required to get full
marks.

return: array variable name => value.

get_question_summary()   X-Ref
Generate a brief, plain-text, summary of this question. This is used by
various reports. This should show the particular variant of the question
as presented to students. For example, the calculated quetsion type would
fill in the particular numbers that were presented to the student.
This method will return null if such a summary is not possible, or
inappropriate.

Normally, this method delegates to {question_definition::get_question_summary()}.

return: string|null a plain text summary of this question.

get_right_answer_summary()   X-Ref
Generate a brief, plain-text, summary of the correct answer to this question.
This is used by various reports, and can also be useful when testing.
This method will return null if such a summary is not possible, or
inappropriate.

return: string|null a plain text summary of the right answer to this question.

get_resume_data()   X-Ref
Used by {@link start_based_on()} to get the data needed to start a new
attempt from the point this attempt has go to.

return: array name => value pairs.

get_our_resume_data()   X-Ref
Used by {@link start_based_on()} to get the data needed to start a new
attempt from the point this attempt has go to.

return: unknown_type

classify_response($whichtries = question_attempt::LAST_TRY)   X-Ref
Classify responses for this question into a number of sub parts and response classes as defined by
{@link \question_type::get_possible_responses} for this question type.

return: (question_classified_response|array)[] If $whichtries is question_attempt::FIRST_TRY or LAST_TRY index is subpartid
param: string $whichtries         which tries to analyse for response analysis. Will be one of

get_state_string($showcorrectness)   X-Ref
Generate a brief textual description of the current state of the question,
normally displayed under the question number.

return: string a brief summary of the current state of the qestion attempt.
param: bool $showcorrectness Whether right/partial/wrong states should

init_first_step(question_attempt_step $step, $variant)   X-Ref
Initialise the first step in a question attempt when a new
{@link question_attempt} is being started.

This method must call $this->question->start_attempt($step, $variant), and may
perform additional processing if the behaviour requries it.

param: question_attempt_step $step the first step of the
param: int $variant which variant of the question to use.

apply_attempt_state(question_attempt_step $step)   X-Ref
When an attempt is started based on a previous attempt (see
{@link question_attempt::start_based_on}) this method is called to setup
the new attempt.

This method must call $this->question->apply_attempt_state($step), and may
perform additional processing if the behaviour requries it.

param: question_attempt_step The first step of the {@link question_attempt}

is_same_comment($pendingstep)   X-Ref
Checks whether two manual grading actions are the same. That is, whether
the comment, and the mark (if given) is the same.

return: bool whether the new response is the same as we already have.
param: question_attempt_step $pendingstep contains the new responses.

process_autosave(question_attempt_pending_step $pendingstep)   X-Ref
Auto-saved data. By default this does nothing. interesting processing is
done in {@link question_behaviour_with_save}.

return: bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
param: question_attempt_pending_step $pendingstep a partially initialised step

process_comment(question_attempt_pending_step $pendingstep)   X-Ref
Implementation of processing a manual comment/grade action that should
be suitable for most subclasses.

return: bool either {@link question_attempt::KEEP}
param: question_attempt_pending_step $pendingstep a partially initialised step

format_comment($comment = null, $commentformat = null, $context = null)   X-Ref

return: string the comment, ready to be output.
param: $comment the comment text to format. If omitted,
param: $commentformat the format of the comment, one of the FORMAT_... constants.
param: $context the quiz context.

summarise_manual_comment($step)   X-Ref

return: string a summary of a manual comment action.
param: question_attempt_step $step

summarise_start($step)   X-Ref
No description

summarise_finish($step)   X-Ref
No description

step_has_a_submitted_response($step)   X-Ref
Does this step include a response submitted by a student?

This method should return true for any attempt explicitly submitted by a student. The question engine itself will also
automatically recognise any last saved response before the attempt is finished, you don't need to return true here for these
steps with responses which are not explicitly submitted by the student.

return: bool is this a step within a question attempt that includes a submitted response by a student.
param: question_attempt_step $step

Class: question_behaviour_with_save  - X-Ref

A subclass of {@link question_behaviour} that implements a save
action that is suitable for most questions that implement the
{@link question_manually_gradable} interface.

required_question_definition_type()   X-Ref
No description

apply_attempt_state(question_attempt_step $step)   X-Ref
No description

is_same_response(question_attempt_step $pendingstep)   X-Ref
Work out whether the response in $pendingstep are significantly different
from the last set of responses we have stored.

return: bool whether the new response is the same as we already have.
param: question_attempt_step $pendingstep contains the new responses.

is_complete_response(question_attempt_step $pendingstep)   X-Ref
Work out whether the response in $pendingstep represent a complete answer
to the question. Normally this will call
{@link question_manually_gradable::is_complete_response}, but some
behaviours, for example the CBM ones, have their own parts to the
response.

return: bool whether the new response is complete.
param: question_attempt_step $pendingstep contains the new responses.

process_autosave(question_attempt_pending_step $pendingstep)   X-Ref
No description

process_save(question_attempt_pending_step $pendingstep)   X-Ref
Implementation of processing a save action that should be suitable for
most subclasses.

return: bool either {@link question_attempt::KEEP} or {@link question_attempt::DISCARD}
param: question_attempt_pending_step $pendingstep a partially initialised step

summarise_submit(question_attempt_step $step)   X-Ref
No description

summarise_save(question_attempt_step $step)   X-Ref
No description

summarise_finish($step)   X-Ref
No description

Class: question_behaviour_with_multiple_tries  - X-Ref

step_has_a_submitted_response($step)   X-Ref
No description

Class: question_cbm  - X-Ref

This helper class contains the constants and methods required for
manipulating scores for certainty based marking.

default_certainty()   X-Ref

return: int the default certaintly level that should be assuemd if

adjust_fraction($fraction, $certainty)   X-Ref
Given a fraction, and a certainty, compute the adjusted fraction.

return: number the adjusted fraction taking the certainty into account.
param: number $fraction the raw fraction for this question.
param: int $certainty one of the certainty level constants.

get_string($certainty)   X-Ref

return: string a textual description of this certainty.
param: int $certainty one of the LOW/MED/HIGH constants.

get_short_string($certainty)   X-Ref

return: string a short textual description of this certainty.
param: int $certainty one of the LOW/MED/HIGH constants.

summary_with_certainty($summary, $certainty)   X-Ref
Add information about certainty to a response summary.

return: string the summary with information about the certainty added.
param: string $summary the response summary.
param: int $certainty the level of certainty to add.

optimal_probablility_low($certainty)   X-Ref

return: float the lower limit of the optimal probability range for this certainty.
param: int $certainty one of the LOW/MED/HIGH constants.

optimal_probablility_high($certainty)   X-Ref

return: float the upper limit of the optimal probability range for this certainty.
param: int $certainty one of the LOW/MED/HIGH constants.