mod_quiz\structure Class Reference

Quiz structure class. More...

Public Member Functions
	add_section_heading ($pagenumber, $heading=null)
	Add a section heading on a given page and return the sectionid. More...
	can_add_random_questions ()
	Whether the current user can add random questions to the quiz or not. More...
	can_add_section_heading ($pagenumber)
	Check whether adding a section heading is possible. More...
	can_be_edited ()
	Quizzes can only be edited if they have not been attempted. More...
	can_be_repaginated ()
	Quizzes can only be repaginated if they have not been attempted, the questions are not shuffled, and there are two or more questions. More...
	can_finish_during_the_attempt ($slotnumber)
	Whether it is possible for another question to depend on this one finishing. More...
	can_question_depend_on_previous_slot ($slotnumber)
	Whether it would be possible, given the question types, etc. More...
	check_can_be_edited ()
	This quiz can only be edited if they have not been attempted. More...
	formatted_question_grade ($slotnumber)
	Get the maximum mark for a question, formatted for display. More...
	formatted_quiz_grade ()
	Get the overall quiz grade formatted for display. More...
	get_cmid ()
	Get the course module id of the quiz. More...
	get_courseid ()
	Get the course id that the quiz belongs to. More...
	get_dates_summary ()
	Get the date information about the current state of the quiz. More...
	get_decimal_places_for_grades ()
	Get the number of decimal places for displyaing overall quiz grades or marks. More...
	get_decimal_places_for_question_marks ()
	Get the number of decimal places for displyaing question marks. More...
	get_displayed_number_for_slot ($slotnumber)
	Get the displayed question number (or 'i') for a given slot. More...
	get_edit_page_warnings ()
	Get any warnings to show at the top of the edit page. More...
	get_last_slot ()
	Get the final slot in the quiz. More...
	get_page_number_for_slot ($slotnumber)
	Get the page a given slot is on. More...
	get_question_by_id ($questionid)
	Get the information about the question with this id. More...
	get_question_count ()
	Get the number of questions in the quiz. More...
	get_question_in_slot ($slotnumber)
	Get the information about the question in a given slot. More...
	get_question_type_for_slot ($slotnumber)
	Get the question type in a given slot. More...
	get_questions_per_page ()
	How many questions are allowed per page in the quiz. More...
	get_quiz ()
	Get the quiz object. More...
	get_quizid ()
	Get id of the quiz. More...
	get_section_by_id ($sectionid)
	Get a particular section by id. More...
	get_section_count ()
	Get the number of questions in the quiz. More...
	get_sections ()
	Get all the sections of the quiz. More...
	get_slot_by_id ($slotid)
	Get a slot by it's id. More...
	get_slot_by_number ($slotnumber)
	Get a slot by it's slot number. More...
	get_slot_id_for_slot ($slotnumber)
	Get the slot id of a given slot slot. More...
	get_slot_tags_for_slot_id ($slotid)
	Retrieve the list of slot tags for the given slot id. More...
	get_slots ()
	Get quiz slots. More...
	get_slots_in_section ($sectionid)
	Get all the slots in a section of the quiz. More...
	has_questions ()
	Whether there are any questions in the quiz. More...
	is_first_section ($section)
	Is this the first section in the quiz? More...
	is_first_slot_on_page ($slotnumber)
	Is this slot the first one on its page? More...
	is_last_section ($section)
	Is this the last section in the quiz? More...
	is_last_slot_in_quiz ($slotnumber)
	Is this slot the last one in the quiz? More...
	is_last_slot_in_section ($slotnumber)
	Is this slot the last one in its section? More...
	is_last_slot_on_page ($slotnumber)
	Is this slot the last one on its page? More...
	is_only_one_slot_in_section ($section)
	Does this section only contain one slot? More...
	is_only_slot_in_section ($slotnumber)
	Is this slot the only one in its section? More...
	is_question_dependent_on_previous_slot ($slotnumber)
	Whether it would be possible, given the question types, etc. More...
	is_real_question ($slotnumber)
	Is a particular question in this attempt a real question, or something like a description. More...
	move_slot ($idmove, $idmoveafter, $page)
	Move a slot from its current location to a new location. More...
	populate_slots_with_sections ()
	Fill in the section ids for each slot.
	populate_structure ($quiz)
	Set up this class with the structure for a given quiz. More...
	refresh_page_numbers ($slots=array())
	Refresh page numbering of quiz slots. More...
	refresh_page_numbers_and_update_db ()
	Refresh page numbering of quiz slots and save to the database. More...
	remove_section_heading ($sectionid)
	Remove the section heading with the given id. More...
	remove_slot ($slotnumber)
	Remove a slot from a quiz. More...
	set_section_heading ($id, $newheading)
	Change the heading for a section. More...
	set_section_shuffle ($id, $shuffle)
	Change the shuffle setting for a section. More...
	update_page_break ($slotid, $type)
	Add/Remove a pagebreak. More...
	update_question_dependency ($slotid, $requireprevious)
	Set whether the question in a particular slot requires the previous one. More...
	update_slot_maxmark ($slot, $maxmark)
	Change the max mark for a slot. More...

Static Public Member Functions
static	create ()
	Create an instance of this class representing an empty quiz. More...
static	create_for_quiz ($quizobj)
	Create an instance of this class representing the structure of a given quiz. More...

Protected Member Functions
	populate_missing_questions ($slots)
	Used by populate. More...
	populate_question_numbers ()
	Number the questions.
	populate_slot_tags ()
	Set up this class with the slot tags for each of the slots.

Protected Attributes
bool	$canaddrandom = null
	caches the results of can_add_random_question.
bool	$canbeedited = null
	caches the results of can_be_edited.
bool	$hasloadedtags = false
	tracks whether tags have been loaded
stdClass[]	$questions = array()
	the questions in this quiz. More...
quiz	$quizobj = null
	the quiz this is the structure of.
stdClass[]	$sections = array()
	currently a dummy. More...
stdClass[]	$slotsinorder = array()
	quiz_slots.slot => the quiz_slots rows for this quiz, agumented by sectionid.
stdClass[]	$slottags = array()
	the tags for slots. More...

Detailed Description

Quiz structure class.

The structure of the quiz. That is, which questions it is built up from. This is used on the Edit quiz page (edit.php) and also when starting an attempt at the quiz (startattempt.php). Once an attempt has been started, then the attempt holds the specific set of questions that that student should answer, and we no longer use this class.

Copyright

2014 The Open University

License

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

Member Function Documentation

add_section_heading()

mod_quiz\structure::add_section_heading	(		$pagenumber,
			$heading = null
	)

Add a section heading on a given page and return the sectionid.

Parameters

int	$pagenumber	the number of the page where the section heading begins.
string | null	$heading	the heading to add. If not given, a default is used.

can_add_random_questions()

mod_quiz\structure::can_add_random_questions

(

)

Whether the current user can add random questions to the quiz or not.

It is only possible to add a random question if the user has the moodle/question:useall capability on at least one of the contexts related to the one where we are currently editing questions.

Return values

bool

can_add_section_heading()

mod_quiz\structure::can_add_section_heading

(

$pagenumber

)

Check whether adding a section heading is possible.

Parameters

int

$pagenumber

the number of the page.

Return values

boolean

can_be_edited()

mod_quiz\structure::can_be_edited

(

)

Quizzes can only be edited if they have not been attempted.

Return values

bool	whether the quiz can be edited.

can_be_repaginated()

mod_quiz\structure::can_be_repaginated

(

)

Quizzes can only be repaginated if they have not been attempted, the questions are not shuffled, and there are two or more questions.

Return values

bool	whether this quiz can be repaginated.

can_finish_during_the_attempt()

mod_quiz\structure::can_finish_during_the_attempt

(

$slotnumber

)

Whether it is possible for another question to depend on this one finishing.

Note that the answer is not exact, because of random questions, and sometimes questions cannot be depended upon because of quiz options.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	can this question finish naturally during the attempt?

can_question_depend_on_previous_slot()

mod_quiz\structure::can_question_depend_on_previous_slot

(

$slotnumber

)

Whether it would be possible, given the question types, etc.

for the question in the given slot to require that the previous question had been answered before this one is displayed.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	can this question require the previous one.

check_can_be_edited()

mod_quiz\structure::check_can_be_edited

(

)

This quiz can only be edited if they have not been attempted.

Throw an exception if this is not the case.

create()

static mod_quiz\structure::create ( )

static

Create an instance of this class representing an empty quiz.

Return values

structure

create_for_quiz()

static mod_quiz\structure::create_for_quiz (   $quizobj )

static

Create an instance of this class representing the structure of a given quiz.

Parameters

quiz

$quizobj

the quiz.

Return values

structure

formatted_question_grade()

mod_quiz\structure::formatted_question_grade

(

$slotnumber

)

Get the maximum mark for a question, formatted for display.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

string

the maximum mark for the question in this slot.

formatted_quiz_grade()

mod_quiz\structure::formatted_quiz_grade

(

)

Get the overall quiz grade formatted for display.

Return values

string

the maximum grade for this quiz.

get_cmid()

mod_quiz\structure::get_cmid

(

)

Get the course module id of the quiz.

Return values

int	the course_modules.id for the quiz.

get_courseid()

mod_quiz\structure::get_courseid

(

)

Get the course id that the quiz belongs to.

Return values

int	the course.id for the quiz.

get_dates_summary()

mod_quiz\structure::get_dates_summary

(

)

Get the date information about the current state of the quiz.

Return values

string[]

array of two strings. First a short summary, then a longer explanation of the current state, e.g. for a tool-tip.

get_decimal_places_for_grades()

mod_quiz\structure::get_decimal_places_for_grades

(

)

Get the number of decimal places for displyaing overall quiz grades or marks.

Return values

int	the number of decimal places.

get_decimal_places_for_question_marks()

mod_quiz\structure::get_decimal_places_for_question_marks

(

)

Get the number of decimal places for displyaing question marks.

Return values

int	the number of decimal places.

get_displayed_number_for_slot()

mod_quiz\structure::get_displayed_number_for_slot

(

$slotnumber

)

Get the displayed question number (or 'i') for a given slot.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

string

the question number ot display for this slot.

get_edit_page_warnings()

mod_quiz\structure::get_edit_page_warnings

(

)

Get any warnings to show at the top of the edit page.

Return values

string[]

array of strings.

get_last_slot()

mod_quiz\structure::get_last_slot

(

)

Get the final slot in the quiz.

Return values

stdClass

the quiz_slots for for the final slot in the quiz.

get_page_number_for_slot()

mod_quiz\structure::get_page_number_for_slot

(

$slotnumber

)

Get the page a given slot is on.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

int	the page number of the page that slot is on.

get_question_by_id()

mod_quiz\structure::get_question_by_id

(

$questionid

)

Get the information about the question with this id.

Parameters

int

$questionid

The question id.

Return values

stdClass

the data from the questions table, augmented with question_category.contextid, and the quiz_slots data for the question in this quiz.

get_question_count()

mod_quiz\structure::get_question_count

(

)

Get the number of questions in the quiz.

Return values

int	the number of questions in the quiz.

get_question_in_slot()

mod_quiz\structure::get_question_in_slot

(

$slotnumber

)

Get the information about the question in a given slot.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

stdClass

the data from the questions table, augmented with question_category.contextid, and the quiz_slots data for the question in this quiz.

get_question_type_for_slot()

mod_quiz\structure::get_question_type_for_slot

(

$slotnumber

)

Get the question type in a given slot.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

string

the question type (e.g. multichoice).

get_questions_per_page()

mod_quiz\structure::get_questions_per_page

(

)

How many questions are allowed per page in the quiz.

This setting controls how frequently extra page-breaks should be inserted automatically when questions are added to the quiz.

Return values

int	the number of questions that should be on each page of the quiz by default.

get_quiz()

mod_quiz\structure::get_quiz

(

)

Get the quiz object.

Return values

stdClass

the quiz settings row from the database.

get_quizid()

mod_quiz\structure::get_quizid

(

)

Get id of the quiz.

Return values

int	the quiz.id for the quiz.

get_section_by_id()

mod_quiz\structure::get_section_by_id

(

$sectionid

)

Get a particular section by id.

Return values

stdClass

the section.

get_section_count()

mod_quiz\structure::get_section_count

(

)

Get the number of questions in the quiz.

Return values

int	the number of questions in the quiz.

get_sections()

mod_quiz\structure::get_sections

(

)

Get all the sections of the quiz.

Return values

stdClass[]

the sections in this quiz.

get_slot_by_id()

mod_quiz\structure::get_slot_by_id

(

$slotid

)

Get a slot by it's id.

Throws an exception if it is missing.

Parameters

int

$slotid

the slot id.

Return values

stdClass

the requested quiz_slots row.

Exceptions

coding_exception

get_slot_by_number()

mod_quiz\structure::get_slot_by_number

(

$slotnumber

)

Get a slot by it's slot number.

Throws an exception if it is missing.

Parameters

int

$slotnumber

The slot number

Return values

stdClass

Exceptions

coding_exception

get_slot_id_for_slot()

mod_quiz\structure::get_slot_id_for_slot

(

$slotnumber

)

Get the slot id of a given slot slot.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

int	the page number of the page that slot is on.

get_slot_tags_for_slot_id()

mod_quiz\structure::get_slot_tags_for_slot_id

(

$slotid

)

Retrieve the list of slot tags for the given slot id.

Parameters

int

$slotid

The id for the slot

Return values

stdClass[]

The list of slot tag records

get_slots()

mod_quiz\structure::get_slots

(

)

Get quiz slots.

Return values

stdClass[]

the slots in this quiz.

get_slots_in_section()

mod_quiz\structure::get_slots_in_section

(

$sectionid

)

Get all the slots in a section of the quiz.

Parameters

int

$sectionid

the section id.

Return values

int[]

slot numbers.

has_questions()

mod_quiz\structure::has_questions

(

)

Whether there are any questions in the quiz.

Return values

bool	true if there is at least one question in the quiz.

is_first_section()

mod_quiz\structure::is_first_section

(

$section

)

Is this the first section in the quiz?

Parameters

stdClass

$section

the quiz_sections row.

Return values

bool	whether this is first section in the quiz.

is_first_slot_on_page()

mod_quiz\structure::is_first_slot_on_page

(

$slotnumber

)

Is this slot the first one on its page?

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	whether this slot the first one on its page.

is_last_section()

mod_quiz\structure::is_last_section

(

$section

)

Is this the last section in the quiz?

Parameters

stdClass

$section

the quiz_sections row.

Return values

bool	whether this is first section in the quiz.

is_last_slot_in_quiz()

mod_quiz\structure::is_last_slot_in_quiz

(

$slotnumber

)

Is this slot the last one in the quiz?

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	whether this slot the last one in the quiz.

is_last_slot_in_section()

mod_quiz\structure::is_last_slot_in_section

(

$slotnumber

)

Is this slot the last one in its section?

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	whether this slot the last one on its section.

is_last_slot_on_page()

mod_quiz\structure::is_last_slot_on_page

(

$slotnumber

)

Is this slot the last one on its page?

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	whether this slot the last one on its page.

is_only_one_slot_in_section()

mod_quiz\structure::is_only_one_slot_in_section

(

$section

)

Does this section only contain one slot?

Parameters

stdClass

$section

the quiz_sections row.

Return values

bool	whether this section contains only one slot.

is_only_slot_in_section()

mod_quiz\structure::is_only_slot_in_section

(

$slotnumber

)

Is this slot the only one in its section?

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	whether this slot the only one on its section.

is_question_dependent_on_previous_slot()

mod_quiz\structure::is_question_dependent_on_previous_slot

(

$slotnumber

)

Whether it would be possible, given the question types, etc.

for the question in the given slot to require that the previous question had been answered before this one is displayed.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	can this question require the previous one.

is_real_question()

mod_quiz\structure::is_real_question

(

$slotnumber

)

Is a particular question in this attempt a real question, or something like a description.

Parameters

int

$slotnumber

the index of the slot in question.

Return values

bool	whether that question is a real question.

move_slot()

mod_quiz\structure::move_slot	(		$idmove,
			$idmoveafter,
			$page
	)

Move a slot from its current location to a new location.

After callig this method, this class will be in an invalid state, and should be discarded if you want to manipulate the structure further.

Parameters

int	$idmove	id of slot to be moved
int	$idmoveafter	id of slot to come before slot being moved
int	$page	new page number of slot being moved
bool	$insection	if the question is moving to a place where a new section starts, include it in that section.

Return values

void

populate_missing_questions()

mod_quiz\structure::populate_missing_questions (   $slots )

protected

Used by populate.

Make up fake data for any missing questions.

Parameters

stdClass[]

$slots

the data about the slots and questions in the quiz.

Return values

stdClass[]

updated $slots array.

populate_structure()

mod_quiz\structure::populate_structure

(

$quiz

)

Set up this class with the structure for a given quiz.

Parameters

stdClass

$quiz

the quiz settings.

refresh_page_numbers()

mod_quiz\structure::refresh_page_numbers

(

$slots = array()

)

Refresh page numbering of quiz slots.

Parameters

stdClass[]

$slots

(optional) array of slot objects.

Return values

stdClass[]

array of slot objects.

refresh_page_numbers_and_update_db()

mod_quiz\structure::refresh_page_numbers_and_update_db

(

)

Refresh page numbering of quiz slots and save to the database.

Parameters

stdClass

$quiz

the quiz object.

Return values

stdClass[]

array of slot objects.

remove_section_heading()

mod_quiz\structure::remove_section_heading

(

$sectionid

)

Remove the section heading with the given id.

Parameters

int

$sectionid

the section to remove.

remove_slot()

mod_quiz\structure::remove_slot

(

$slotnumber

)

Remove a slot from a quiz.

Parameters

int

$slotnumber

The number of the slot to be deleted.

Exceptions

coding_exception

set_section_heading()

mod_quiz\structure::set_section_heading	(		$id,
			$newheading
	)

Change the heading for a section.

Parameters

int	$id	the id of the section to change.
string	$newheading	the new heading for this section.

set_section_shuffle()

mod_quiz\structure::set_section_shuffle	(		$id,
			$shuffle
	)

Change the shuffle setting for a section.

Parameters

int	$id	the id of the section to change.
bool	$shuffle	whether this section should be shuffled.

update_page_break()

mod_quiz\structure::update_page_break	(		$slotid,
			$type
	)

Add/Remove a pagebreak.

Saves changes to the slot page relationship in the quiz_slots table and reorders the paging for subsequent slots.

Parameters

int	$slotid	id of slot.
int	$type	repaginate::LINK or repaginate::UNLINK.

Return values

stdClass[]

array of slot objects.

update_question_dependency()

mod_quiz\structure::update_question_dependency	(		$slotid,
			$requireprevious
	)

Set whether the question in a particular slot requires the previous one.

Parameters

int	$slotid	id of slot.
bool	$requireprevious	if true, set this question to require the previous one.

update_slot_maxmark()

mod_quiz\structure::update_slot_maxmark	(		$slot,
			$maxmark
	)

Change the max mark for a slot.

Saves changes to the question grades in the quiz_slots table and any corresponding question_attempts. It does not update 'sumgrades' in the quiz table.

Parameters

stdClass	$slot	row from the quiz_slots table.
float	$maxmark	the new maxmark.

Return values

bool	true if the new grade is different from the old one.

Member Data Documentation

$questions

stdClass [] mod_quiz\structure::$questions = array()

protected

the questions in this quiz.

Contains the row from the questions table, with the data from the quiz_slots table added, and also question_categories.contextid.

$sections

stdClass [] mod_quiz\structure::$sections = array()

protected

currently a dummy.

Holds data that will match the quiz_sections, once it exists.

$slottags

stdClass [] mod_quiz\structure::$slottags = array()

protected

the tags for slots.

Indexed by slot id.

---

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

• mod/quiz/classes/structure.php