question_behaviour Class Reference

The base class for question behaviours. More...

Inheritance diagram for question_behaviour:

Public Member Functions
	__construct (question_attempt $qa, $preferredbehaviour)
	Normally you should not call this constuctor directly.
	adjust_display_options (question_display_options $options)
	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.
	apply_attempt_state (question_attempt_step $step)
	When an attempt is started based on a previous attempt (see question_attempt::start_based_on) this method is called to setup the new attempt.
	can_finish_during_attempt ()
	Whether the current attempt at this question could be completed just by the student interacting with the question, before $qa->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=question_attempt::LAST_TRY)
	Classify responses for this question into a number of sub parts and response classes as defined by question_type::get_possible_responses for this question type.
	format_comment ($comment=null, $commentformat=null, $context=null)
	get_applicable_hint ()
	Get the most applicable hint for the question in its current state.
	get_correct_response ()
	Return an array of any im variables, and the value required to get full marks.
	get_expected_data ()
	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.
	get_expected_qt_data ()
	Return an array of question type variables for the question in its current state.
	get_max_fraction ()
	Return the maximum possible fraction that can be scored for this question.
	get_min_fraction ()
	What is the minimum fraction that can be scored for this question.
	get_name ()
	get_question_summary ()
	Generate a brief, plain-text, summary of this question.
	get_renderer (moodle_page $page)
	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.
	get_right_answer_summary ()
	Generate a brief, plain-text, summary of the correct answer to this question.
	get_state_string ($showcorrectness)
	Generate a brief textual description of the current state of the question, normally displayed under the question number.
	init_first_step (question_attempt_step $step, $variant)
	Initialise the first step in a question attempt when a new question_attempt is being started.
	is_compatible_question (question_definition $question)
	Some behaviours can only work with certing types of question.
	process_action (question_attempt_pending_step $pendingstep)
	The main entry point for processing an action.
	process_autosave (question_attempt_pending_step $pendingstep)
	Auto-saved data.
	process_comment (question_attempt_pending_step $pendingstep)
	Implementation of processing a manual comment/grade action that should be suitable for most subclasses.
	render (question_display_options $options, $number, core_question_renderer $qoutput, qtype_renderer $qtoutput)
	Cause the question to be renderered.
	step_has_a_submitted_response ($step)
	Does this step include a response submitted by a student?
	summarise_action (question_attempt_step $step)
	summarise_finish ($step)
	summarise_start ($step)

Protected Member Functions
	get_our_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.
	is_same_comment ($pendingstep)
	Checks whether two manual grading actions are the same.
	summarise_manual_comment ($step)

Protected Attributes
question_attempt	$qa
	the question attempt we are managing.
question_definition	$question
	shortcut to $qa->get_question().

Detailed Description

The base class for question behaviours.

A question behaviour is used by the question engine, specifically by a 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 question_definition.

Copyright

2009 The Open University

License

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

Constructor & Destructor Documentation

__construct()

question_behaviour::__construct	(	question_attempt	$qa,
			$preferredbehaviour )

Normally you should not call this constuctor directly.

The appropriate behaviour object is created automatically as part of question_attempt::start().

Parameters

question_attempt	$qa	the question attempt we will be managing.
string	$preferredbehaviour	the type of behaviour that was actually requested. This information is not needed in most cases, the type of subclass is enough, but occasionally it is needed.

Member Function Documentation

adjust_display_options()

question_behaviour::adjust_display_options

(

question_display_options

$options

)

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.

Parameters

question_display_options

$options

the options to adjust. Just change the properties of this object - objects are passed by referece.

Reimplemented in qbehaviour_adaptive, qbehaviour_informationitem, qbehaviour_interactive, and qbehaviour_manualgraded.

apply_attempt_state()

question_behaviour::apply_attempt_state

(

question_attempt_step

$step

)

When an attempt is started based on a previous attempt (see 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.

Parameters

question_attempt_step

The first step of the question_attempt being loaded.

Reimplemented in question_behaviour_with_save.

can_finish_during_attempt()

question_behaviour::can_finish_during_attempt

(

)

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

Return values

boolean

whether the attempt can finish naturally.

Reimplemented in qbehaviour_immediatefeedback, and qbehaviour_interactive.

check_file_access()

question_behaviour::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.

classify_response()

question_behaviour::classify_response

(

$whichtries = question_attempt::LAST_TRY

)

Classify responses for this question into a number of sub parts and response classes as defined by question_type::get_possible_responses for this question type.

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|array)[]

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.

format_comment()

question_behaviour::format_comment	(		$comment = null,
			$commentformat = null,
			$context = null )

Parameters

$comment	the comment text to format. If omitted, $this->qa->get_manual_comment() is used.
$commentformat	the format of the comment, one of the FORMAT_... constants.
$context	the quiz context.

Return values

string

the comment, ready to be output.

get_applicable_hint()

question_behaviour::get_applicable_hint

(

)

Get the most applicable hint for the question in its current state.

Return values

question_hint

the most applicable hint, or null, if none.

Reimplemented in qbehaviour_interactive.

get_correct_response()

question_behaviour::get_correct_response

(

)

Return an array of any im variables, and the value required to get full marks.

Return values

array

variable name => value.

Reimplemented in qbehaviour_deferredcbm, qbehaviour_immediatecbm, and qbehaviour_informationitem.

get_expected_data()

question_behaviour::get_expected_data

(

)

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 values

array

variable name => PARAM_... constant.

Reimplemented in qbehaviour_adaptive, qbehaviour_deferredcbm, qbehaviour_immediatecbm, qbehaviour_immediatefeedback, qbehaviour_informationitem, and qbehaviour_interactive.

get_expected_qt_data()

question_behaviour::get_expected_qt_data

(

)

Return an array of question type variables for the question in its current state.

Normally, if adjust_display_options() would set 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 values

array|string

variable name => PARAM_... constant, or, as a special case that should only be used in unavoidable, the constant question_attempt\USE_RAW_DATA meaning take all the raw submitted data belonging to this question.

Reimplemented in qbehaviour_interactive.

get_max_fraction()

question_behaviour::get_max_fraction

(

)

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 values

number

the maximum fraction when this question is attempted under this behaviour.

Reimplemented in qbehaviour_deferredcbm, qbehaviour_immediatecbm, and qbehaviour_missing.

get_min_fraction()

question_behaviour::get_min_fraction

(

)

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 values

number

the minimum fraction when this question is attempted under this behaviour.

Reimplemented in qbehaviour_deferredcbm, qbehaviour_deferredfeedback, qbehaviour_immediatecbm, qbehaviour_immediatefeedback, and qbehaviour_missing.

get_name()

question_behaviour::get_name

(

)

Return values

string

the name of this behaviour. For example the name of qbehaviour_mymodle is 'mymodel'.

get_our_resume_data()

question_behaviour::get_our_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

unknown_type

Reimplemented in qbehaviour_deferredcbm, and qbehaviour_immediatecbm.

get_question_summary()

question_behaviour::get_question_summary

(

)

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 values

string|null

a plain text summary of this question.

get_renderer()

question_behaviour::get_renderer

(

moodle_page

$page

)

Parameters

moodle_page

$page

the page to render for.

Return values

qbehaviour_renderer

get the appropriate renderer to use for this model.

get_resume_data()

question_behaviour::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.

Return values

array

name => value pairs.

get_right_answer_summary()

question_behaviour::get_right_answer_summary

(

)

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 values

string|null

a plain text summary of the right answer to this question.

Reimplemented in qbehaviour_adaptive, qbehaviour_deferredcbm, qbehaviour_deferredfeedback, qbehaviour_immediatecbm, qbehaviour_immediatefeedback, and qbehaviour_interactive.

get_state_string()

question_behaviour::get_state_string

(

$showcorrectness

)

Generate a brief textual description of the current state of the question, normally displayed under the question number.

Parameters

bool

$showcorrectness

Whether right/partial/wrong states should be distinguised.

Return values

string

a brief summary of the current state of the qestion attempt.

Reimplemented in qbehaviour_adaptive, qbehaviour_immediatefeedback, qbehaviour_informationitem, and qbehaviour_interactive.

init_first_step()

question_behaviour::init_first_step	(	question_attempt_step	$step,
			$variant )

Initialise the first step in a question attempt when a new 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.

Parameters

question_attempt_step	$step	the first step of the question_attempt being started.
int	$variant	which variant of the question to use.

Reimplemented in qbehaviour_interactive, and qbehaviour_missing.

is_compatible_question()

question_behaviour::is_compatible_question ( question_definition $question )

abstract

Some behaviours can only work with certing types of question.

This method allows the behaviour to verify that a question is compatible.

This implementation is only provided for backwards-compatibility. You should override this method if you are implementing a behaviour.

Parameters

question_definition

$question

the question.

Reimplemented in qbehaviour_adaptive, qbehaviour_deferredfeedback, qbehaviour_immediatefeedback, qbehaviour_informationitem, qbehaviour_interactive, qbehaviour_interactivecountback, qbehaviour_manualgraded, and qbehaviour_missing.

is_same_comment()

question_behaviour::is_same_comment ( $pendingstep )

protected

Checks whether two manual grading actions are the same.

That is, whether the comment, and the mark (if given) is the same.

Parameters

question_attempt_step

$pendingstep

contains the new responses.

Return values

bool	whether the new response is the same as we already have.

process_action()

question_behaviour::process_action ( question_attempt_pending_step $pendingstep )

abstract

The main entry point for processing an action.

All the various operations that can be performed on a question_attempt get channeled through this function, except for question_attempt::start() which goes to init_first_step(). question_attempt::finish() becomes an action with im vars finish => 1, and manual comment/grade becomes an action with im vars comment => comment text, and mark => ..., max_mark => ... if the question is graded.

This method should first determine whether the action is significant. For example, if no actual action is being performed, but instead the current responses are being saved, and there has been no change since the last set of responses that were saved, this the action is not significatn. In this case, this method should return question_attempt::DISCARD. Otherwise it should return question_attempt::KEEP.

If the action is significant, this method should also perform any necessary updates to $pendingstep. For example, it should call question_attempt_step::set_state() to set the state that results from this action, and if this is a grading action, it should call question_attempt_step::set_fraction().

This method can also call question_attempt_step::set_behaviour_var() to store additional infomation. There are two main uses for this. This can be used to store the result of any randomisation done. It is important to store the result of randomisation once, and then in future use the same outcome if the actions are ever replayed. This is how regrading works. The other use is to cache the result of expensive computations performed on the raw response data, so that subsequent display and review of the question does not have to repeat the same expensive computations.

Often this method is implemented as a dispatching method that examines the pending step to determine the kind of action being performed, and then calls a more specific method like process_save() or process_comment(). Look at some of the standard behaviours for examples.

Parameters

question_attempt_pending_step

$pendingstep

a partially initialised step containing all the information about the action that is being peformed. This information can be accessed using question_attempt_step::get_behaviour_var().

Return values

bool	either question_attempt::KEEP or question_attempt::DISCARD

Reimplemented in qbehaviour_adaptive, qbehaviour_deferredfeedback, qbehaviour_immediatefeedback, qbehaviour_informationitem, qbehaviour_interactive, qbehaviour_manualgraded, and qbehaviour_missing.

process_autosave()

question_behaviour::process_autosave

(

question_attempt_pending_step

$pendingstep

)

Auto-saved data.

By default this does nothing. interesting processing is done in question_behaviour_with_save.

Parameters

question_attempt_pending_step

$pendingstep

a partially initialised step containing all the information about the action that is being peformed. This information can be accessed using question_attempt_step::get_behaviour_var().

Return values

bool	either question_attempt::KEEP or question_attempt::DISCARD

Reimplemented in question_behaviour_with_save.

process_comment()

question_behaviour::process_comment

(

question_attempt_pending_step

$pendingstep

)

Implementation of processing a manual comment/grade action that should be suitable for most subclasses.

Parameters

question_attempt_pending_step

$pendingstep

a partially initialised step containing all the information about the action that is being peformed.

Return values

bool	either question_attempt::KEEP

Reimplemented in qbehaviour_informationitem.

render()

question_behaviour::render	(	question_display_options	$options,
			$number,
		core_question_renderer	$qoutput,
		qtype_renderer	$qtoutput )

Cause the question to be renderered.

This gets the appropriate behaviour renderer using get_renderer(), and adjusts the display options using adjust_display_options() and then calls core_question_renderer::question() to do the work.

Parameters

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

Return values

string

HTML fragment.

step_has_a_submitted_response()

question_behaviour::step_has_a_submitted_response

(

$step

)

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.

Parameters

question_attempt_step

$step

Return values

bool	is this a step within a question attempt that includes a submitted response by a student.

Reimplemented in question_behaviour_with_multiple_tries.

summarise_manual_comment()

question_behaviour::summarise_manual_comment ( $step )

protected

Return values

string

a summary of a manual comment action.

Parameters

question_attempt_step

$step

---

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

• question/behaviour/behaviourbase.php