question_with_responses Class Reference

This class represents a real question. More...

Inheritance diagram for question_with_responses:

Public Member Functions
	apply_attempt_state (question_attempt_step $step)
	When an in-progress question_attempt is re-loaded from the database, this method is called so that the question can re-initialise its internal state as needed by this attempt. More...
	check_file_access ($qa, $options, $component, $filearea, $args, $forcedownload)
	Checks whether the users is allow to be served a particular file. More...
	classify_response (array $response)
	Categorise the student's response according to the categories defined by get_possible_responses. More...
	clear_wrong_from_response (array $response)
	Given a response, rest the parts that are wrong. More...
	format_generalfeedback ($qa)
	format_questiontext ($qa)
	format_text ($text, $format, $qa, $component, $filearea, $itemid, $clean=false)
	Apply format_text() to some content with appropriate settings for this question. More...
	get_correct_response ()
	What data would need to be submitted to get this question correct. More...
	get_expected_data ()
	What data may be included in the form submission when a student submits this question in its current state? More...
	get_max_fraction ()
	Some questions can return a mark greater than the maximum. More...
	get_min_fraction ()
	Some questions can return a negative mark if the student gets it wrong. More...
	get_num_parts_right (array $response)
	Return the number of subparts of this response that are right. More...
	get_num_variants ()
	get_question_summary ()
	Generate a brief, plain-text, summary of this question. More...
	get_renderer (moodle_page $page)
	get_student_response_values_for_simulation ($realresponse)
	Does the opposite of prepare_simulated_post_data. More...
	get_type_name ()
	get_variants_selection_seed ()
	html_to_text ($text, $format)
	Convert some part of the question text to plain text. More...
	is_complete_response (array $response)
	Used by many of the behaviours, to work out whether the student's response to the question is complete. More...
	is_gradable_response (array $response)
	Use by many of the behaviours to determine whether the student has provided enough of an answer for the question to be graded automatically, or whether it must be considered aborted. More...
	is_same_response (array $prevresponse, array $newresponse)
	Use by many of the behaviours to determine whether the student's response has changed. More...
	make_behaviour (question_attempt $qa, $preferredbehaviour)
	Creat the appropriate behaviour for an attempt at this quetsion, given the desired (archetypal) behaviour. More...
	make_html_inline ($html)
	Take some HTML that should probably already be a single line, like a multiple choice choice, or the corresponding feedback, and make it so that it is suitable to go in a place where the HTML must be inline, like inside a. More...
	prepare_simulated_post_data ($simulatedresponse)
	Takes an array of values representing a student response represented in a way that is understandable by a human and transforms that to the response as the POST values returned from the HTML form that takes the student response during a student attempt. More...
	start_attempt (question_attempt_step $step, $variant)
	Start a new attempt at this question, storing any information that will be needed later in the step. More...
	summarise_response (array $response)
	Produce a plain text summary of a response. More...
	un_summarise_response (string $summary)
	If possible, construct a response that could have lead to the given response summary. More...

Public Attributes
integer	$category
	question category id.
integer	$contextid
	question context id.
integer	$createdby
	userid of the use who created this question.
number	$defaultmark = 1
	what this quetsion is marked out of, by default.
string	$generalfeedback
	question general feedback.
integer	$generalfeedbackformat
	question test format.
boolean	$hidden = 0
	whethre this question has been deleted/hidden in the question bank.
array	$hints = array()
	of question_hints.
integer	$id
	id of the question in the datase, or null if this question is not in the database.
string	$idnumber
	question idnumber.
integer	$length = 1
	How many question numbers this question consumes.
integer	$modifiedby
	userid of the use who modified this question.
string	$name
	question name.
integer	$parent = 0
	parent question id.
number	$penalty = 0
	penalty factor of this question.
question_type	$qtype
	the question type this question is.
string	$questiontext
	question text.
integer	$questiontextformat
	question test format.
string	$stamp
	unique identifier of this question.
integer	$timecreated
	timestamp when this question was created.
integer	$timemodified
	timestamp when this question was modified.
string	$version
	unique identifier of this version of this question.

Detailed Description

This class represents a real question.

That is, one that is not a question_information_item.

Copyright

2009 The Open University

License

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

Member Function Documentation

apply_attempt_state()

question_definition::apply_attempt_state ( question_attempt_step  $step )

inherited

When an in-progress question_attempt is re-loaded from the database, this method is called so that the question can re-initialise its internal state as needed by this attempt.

For example, the multiple choice question type needs to set the order of the choices to the order that was set up when start_attempt was called originally. All the information required to do this should be in the $step object, which is the first step of the question_attempt being loaded.

Parameters

question_attempt_step

The first step of the question_attempt being loaded.

Reimplemented in qtype_randomsamatch_question, qtype_numerical_question, qtype_multichoice_base, qtype_multianswer_question, qtype_match_question, qtype_gapselect_question_base, qtype_calculatedmulti_multi_question, qtype_calculatedmulti_single_question, and qtype_calculated_question.

check_file_access()

question_definition::check_file_access (   $qa,   $options,   $component,   $filearea,   $args,   $forcedownload  )

inherited

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

Parameters

question_attempt	$qa	the question attempt being displayed.
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.

Reimplemented in qtype_truefalse_question, qtype_shortanswer_question, qtype_numerical_question, qtype_multichoice_base, qtype_multianswer_question, qtype_match_question, qtype_gapselect_question_base, qtype_essay_question, qtype_ddmarker_question, and qtype_ddtoimage_question_base.

classify_response()

question_with_responses::classify_response

(

array

$response

)

Categorise the student's response according to the categories defined by get_possible_responses.

Parameters

$response

a response, as might be passed to }. * array subpartid => question_classified_response objects. returns an empty array if no analysis is possible.

Implements question_manually_gradable.

Reimplemented in qtype_truefalse_question, question_graded_by_strategy, qtype_numerical_question, qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_match_question, qtype_gapselect_question_base, qtype_ddmarker_question, and qtype_ddtoimage_question_base.

clear_wrong_from_response()

question_definition::clear_wrong_from_response ( array  $response )

inherited

Given a response, rest the parts that are wrong.

Parameters

array

$response

a response

Return values

array

a cleaned up response with the wrong bits reset.

Reimplemented in qtype_multichoice_multi_question, qtype_multianswer_question, qtype_match_question, qtype_gapselect_question_base, qtype_ddmarker_question, and qtype_ddtoimage_question_base.

format_generalfeedback()

question_definition::format_generalfeedback (   $qa )

inherited

Return values

the	result of applying format_text() to the general feedback.

format_questiontext()

question_definition::format_questiontext (   $qa )

inherited

Return values

the	result of applying format_text() to the question text.

format_text()

question_definition::format_text (   $text,   $format,   $qa,   $component,   $filearea,   $itemid,   $clean = false  )

inherited

Apply format_text() to some content with appropriate settings for this question.

Parameters

string	$text	some content that needs to be output.
int	$format	the FORMAT_... constant.
question_attempt	$qa	the question attempt.
string	$component	used for rewriting file area URLs.
string	$filearea	used for rewriting file area URLs.
bool	$clean	Whether the HTML needs to be cleaned. Generally, parts of the question do not need to be cleaned, and student input does.

Return values

string

the text formatted for output by format_text.

get_correct_response()

question_definition::get_correct_response ( )

abstractinherited

What data would need to be submitted to get this question correct.

If there is more than one correct answer, this method should just return one possibility. If it is not possible to compute a correct response, this method should return null.

Return values

array|null

parameter name => value.

Reimplemented in qtype_truefalse_question, qtype_shortanswer_question, question_graded_by_strategy, question_information_item, qtype_numerical_question, qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_multianswer_question, qtype_missingtype_question, qtype_match_question, qtype_gapselect_question_base, qtype_essay_question, qtype_ddmarker_question, and qtype_calculated_question.

get_expected_data()

question_definition::get_expected_data ( )

abstractinherited

What data may be included in the form submission when a student submits this question in its current state?

This information is used in calls to optional_param. The parameter name has question_attempt::get_field_prefix() automatically prepended.

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 qtype_truefalse_question, qtype_shortanswer_question, question_information_item, qtype_numerical_question, qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_multianswer_question, qtype_missingtype_question, qtype_match_question, qtype_gapselect_question_base, qtype_essay_question, and qtype_ddmarker_question.

get_max_fraction()

question_definition::get_max_fraction ( )

inherited

Some questions can return a mark greater than the maximum.

This method returns the lowest highest the question can return, on the fraction scale. that is, where the nominal maximum mark is 1.0.

Return values

float

maximum fraction this question will ever return.

Reimplemented in qtype_multianswer_question.

get_min_fraction()

question_definition::get_min_fraction ( )

inherited

Some questions can return a negative mark if the student gets it wrong.

This method returns the lowest mark the question can return, on the fraction scale. that is, where the maximum possible mark is 1.0.

Return values

float

minimum fraction this question will ever return.

Reimplemented in qtype_multichoice_multi_question, qtype_multichoice_single_question, and qtype_multianswer_question.

get_num_parts_right()

question_definition::get_num_parts_right ( array  $response )

inherited

Return the number of subparts of this response that are right.

Parameters

array

$response

a response

Return values

array

with two elements, the number of correct subparts, and the total number of subparts.

Reimplemented in qtype_multichoice_multi_question, qtype_multianswer_question, qtype_match_question, qtype_gapselect_question_base, and qtype_ddmarker_question.

get_num_variants()

question_definition::get_num_variants ( )

inherited

Return values

int	the number of vaiants that this question has.

Reimplemented in qtype_calculatedmulti_multi_question, qtype_calculatedmulti_single_question, and qtype_calculated_question.

get_question_summary()

question_definition::get_question_summary ( )

inherited

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.

Return values

string|null

a plain text summary of this question.

Reimplemented in question_information_item, qtype_multichoice_base, qtype_multianswer_question, qtype_match_question, qtype_gapselect_question_base, and qtype_ddtoimage_question_base.

get_renderer()

question_definition::get_renderer ( moodle_page  $page )

inherited

Parameters

moodle_page

the page we are outputting to.

Return values

qtype_renderer

the renderer to use for outputting this question.

Reimplemented in qtype_multichoice_multi_question, and qtype_multichoice_single_question.

get_student_response_values_for_simulation()

question_definition::get_student_response_values_for_simulation (   $realresponse )

inherited

Does the opposite of prepare_simulated_post_data.

This takes a student response (the POST values returned from the HTML form that takes the student response during a student attempt) it then represents it in a way that is understandable by a human.

Primarily this is used when creating a file of csv from real student responses in order later to be able to simulate the same student interaction with a quiz later.

Parameters

string[]

$realresponse

the response array as was returned from the form during a student attempt (without prefixes).

Return values

string[]

an array of data representing a student response.

Reimplemented in qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_multianswer_question, and qtype_match_question.

get_type_name()

question_definition::get_type_name ( )

inherited

Return values

the	name of the question type (for example multichoice) that this question is.

get_variants_selection_seed()

question_definition::get_variants_selection_seed ( )

inherited

Return values

string

that can be used to seed the pseudo-random selection of a variant.

Reimplemented in qtype_calculatedmulti_multi_question, qtype_calculatedmulti_single_question, and qtype_calculated_question.

html_to_text()

question_definition::html_to_text (   $text,   $format  )

inherited

Convert some part of the question text to plain text.

This might be used, for example, by get_response_summary().

Parameters

string	$text	The HTML to reduce to plain text.
int	$format	the FORMAT_... constant.

Return values

string

the equivalent plain text.

is_complete_response()

question_manually_gradable::is_complete_response ( array  $response )

inherited

Used by many of the behaviours, to work out whether the student's response to the question is complete.

That is, whether the question attempt should move to the COMPLETE or INCOMPLETE state.

Parameters

array

$response

responses, as returned by question_attempt_step::get_qt_data().

Return values

bool	whether this response is a complete answer to this question.

Implemented in qtype_truefalse_question, qtype_shortanswer_question, qtype_numerical_question, qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_multianswer_question, qtype_missingtype_question, qtype_match_question, qtype_gapselect_question_base, qtype_essay_question, and qtype_ddmarker_question.

is_gradable_response()

question_with_responses::is_gradable_response

(

array

$response

)

Use by many of the behaviours to determine whether the student has provided enough of an answer for the question to be graded automatically, or whether it must be considered aborted.

Parameters

array

$response

responses, as returned by question_attempt_step::get_qt_data().

Return values

bool	whether this response can be graded.

Implements question_manually_gradable.

Reimplemented in qtype_numerical_question, qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_multianswer_question, qtype_match_question, qtype_gapselect_question_base, qtype_essay_question, and qtype_ddmarker_question.

is_same_response()

question_manually_gradable::is_same_response ( array  $prevresponse, array  $newresponse  )

inherited

Use by many of the behaviours to determine whether the student's response has changed.

This is normally used to determine that a new set of responses can safely be discarded.

Parameters

array	$prevresponse	the responses previously recorded for this question, as returned by question_attempt_step::get_qt_data()
array	$newresponse	the new responses, in the same format.

Return values

bool	whether the two sets of responses are the same - that is whether the new set of responses can safely be discarded.

Implemented in qtype_truefalse_question, qtype_shortanswer_question, qtype_numerical_question, qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_multianswer_question, qtype_missingtype_question, qtype_match_question, qtype_gapselect_question_base, qtype_essay_question, and qtype_ddmarker_question.

make_behaviour()

question_definition::make_behaviour ( question_attempt  $qa,   $preferredbehaviour  )

inherited

Creat the appropriate behaviour for an attempt at this quetsion, given the desired (archetypal) behaviour.

This default implementation will suit most normal graded questions.

If your question is of a patricular type, then it may need to do something different. For example, if your question can only be graded manually, then it should probably return a manualgraded behaviour, irrespective of what is asked for.

If your question wants to do somthing especially complicated is some situations, then you may wish to return a particular behaviour related to the one asked for. For example, you migth want to return a qbehaviour_interactive_adapted_for_myqtype.

Parameters

question_attempt	$qa	the attempt we are creating a behaviour for.
string	$preferredbehaviour	the requested type of behaviour.

Return values

question_behaviour

the new behaviour object.

Reimplemented in question_graded_automatically_with_countback, question_information_item, and qtype_essay_question.

make_html_inline()

question_definition::make_html_inline (   $html )

inherited

Take some HTML that should probably already be a single line, like a multiple choice choice, or the corresponding feedback, and make it so that it is suitable to go in a place where the HTML must be inline, like inside a.

tag.

Parameters

string

$html

to HTML to fix up.

Return values

string

the fixed HTML.

prepare_simulated_post_data()

question_definition::prepare_simulated_post_data (   $simulatedresponse )

inherited

Takes an array of values representing a student response represented in a way that is understandable by a human and transforms that to the response as the POST values returned from the HTML form that takes the student response during a student attempt.

Primarily this is used when reading csv values from a file of student responses in order to be able to simulate the student interaction with a quiz.

In most cases the array will just be returned as is. Some question types will need to transform the keys of the array, as the meaning of the keys in the html form is deliberately obfuscated so that someone looking at the html does not get an advantage. The values that represent the response might also be changed in order to more meaningful to a human.

See the examples of question types that have overridden this in core and also see the csv files of simulated student responses used in unit tests in :

• mod/quiz/tests/fixtures/stepsXX.csv
• mod/quiz/report/responses/tests/fixtures/steps00.csv
• mod/quiz/report/statistics/tests/fixtures/stepsXX.csv

Also see https://github.com/jamiepratt/moodle-quiz_simulate, a quiz report plug in for uploading and downloading student responses as csv files.

Parameters

array

$simulatedresponse

an array of data representing a student response

Return values

array

a response array as would be returned from the html form (but without prefixes)

Reimplemented in qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_multianswer_question, and qtype_match_question.

start_attempt()

question_definition::start_attempt ( question_attempt_step  $step,   $variant  )

inherited

Start a new attempt at this question, storing any information that will be needed later in the step.

This is where the question can do any initialisation required on a per-attempt basis. For example, this is where the multiple choice question type randomly shuffles the choices (if that option is set).

Any information about how the question has been set up for this attempt should be stored in the $step, by calling $step->set_qt_var(...).

Parameters

	question_attempt_step	The first step of the question_attempt being started. Can be used to store state.
int	$varant	which variant of this question to start. Will be between 1 and get_num_variants() inclusive.

Reimplemented in qtype_randomsamatch_question, qtype_numerical_question, qtype_multichoice_base, qtype_multianswer_question, qtype_missingtype_question, qtype_match_question, qtype_gapselect_question_base, qtype_calculatedmulti_multi_question, qtype_calculatedmulti_single_question, and qtype_calculated_question.

summarise_response()

question_manually_gradable::summarise_response ( array  $response )

inherited

Produce a plain text summary of a response.

Parameters

array

$response

a response, as might be passed to grade_response().

Return values

string

a plain text summary of that response, that could be used in reports.

Implemented in qtype_truefalse_question, qtype_shortanswer_question, qtype_numerical_question, qtype_multichoice_multi_question, qtype_multichoice_single_question, qtype_multianswer_question, qtype_missingtype_question, qtype_match_question, qtype_gapselect_question_base, qtype_essay_question, qtype_ddmarker_question, and qtype_ddtoimage_question_base.

un_summarise_response()

question_with_responses::un_summarise_response

(

string

$summary

)

If possible, construct a response that could have lead to the given response summary.

This is basically the opposite of summarise_response() but it is intended only to be used for testing.

Parameters

string

$summary

a string, which might have come from summarise_response

Return values

array

a response that could have lead to that.

Implements question_manually_gradable.

Reimplemented in qtype_truefalse_question, qtype_shortanswer_question, qtype_numerical_question, and qtype_essay_question.

---

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

• question/type/questionbase.php