Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

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

Defines the \mod_quiz\structure class.

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

Defines 1 class

structure:: (65 methods):
  create()
  create_for_quiz()
  has_questions()
  get_question_count()
  get_question_by_id()
  get_question_in_slot()
  get_question_name_in_slot()
  get_displayed_number_for_slot()
  get_page_number_for_slot()
  get_slot_id_for_slot()
  get_question_type_for_slot()
  can_question_depend_on_previous_slot()
  can_finish_during_the_attempt()
  is_question_dependent_on_previous_slot()
  is_real_question()
  has_use_capability()
  get_courseid()
  get_cmid()
  get_quizid()
  get_quiz()
  can_be_repaginated()
  can_be_edited()
  check_can_be_edited()
  get_questions_per_page()
  get_slots()
  is_first_slot_on_page()
  is_last_slot_on_page()
  is_last_slot_in_section()
  is_only_slot_in_section()
  is_last_slot_in_quiz()
  is_first_section()
  is_last_section()
  is_only_one_slot_in_section()
  get_last_slot()
  get_slot_by_id()
  get_slot_by_number()
  can_add_section_heading()
  get_slots_in_section()
  get_sections()
  get_section_by_id()
  get_section_count()
  formatted_quiz_grade()
  formatted_question_grade()
  get_decimal_places_for_grades()
  get_decimal_places_for_question_marks()
  get_edit_page_warnings()
  get_dates_summary()
  populate_structure()
  populate_slots_with_sections()
  populate_question_numbers()
  get_version_choices_for_slot()
  move_slot()
  refresh_page_numbers()
  refresh_page_numbers_and_update_db()
  remove_slot()
  unset_question()
  update_slot_maxmark()
  update_question_dependency()
  update_page_break()
  add_section_heading()
  set_section_heading()
  set_section_shuffle()
  remove_section_heading()
  can_add_random_questions()
  get_slot_tags_for_slot_id()


Class: structure  - X-Ref

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.

create()   X-Ref
Create an instance of this class representing an empty quiz.

return: structure

create_for_quiz($quizobj)   X-Ref
Create an instance of this class representing the structure of a given quiz.

param: \quiz $quizobj the quiz.
return: structure

has_questions()   X-Ref
Whether there are any questions in the quiz.

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

get_question_count()   X-Ref
Get the number of questions in the quiz.

return: int the number of questions in the quiz.

get_question_by_id($questionid)   X-Ref
Get the information about the question with this id.

param: int $questionid The question id.
return: \stdClass the data from the questions table, augmented with

get_question_in_slot($slotnumber)   X-Ref
Get the information about the question in a given slot.

param: int $slotnumber the index of the slot in question.
return: \stdClass the data from the questions table, augmented with

get_question_name_in_slot($slotnumber)   X-Ref
Get the information about the question name in a given slot.

param: int $slotnumber the index of the slot in question.
return: \stdClass the data from the questions table, augmented with

get_displayed_number_for_slot($slotnumber)   X-Ref
Get the displayed question number (or 'i') for a given slot.

param: int $slotnumber the index of the slot in question.
return: string the question number ot display for this slot.

get_page_number_for_slot($slotnumber)   X-Ref
Get the page a given slot is on.

param: int $slotnumber the index of the slot in question.
return: int the page number of the page that slot is on.

get_slot_id_for_slot($slotnumber)   X-Ref
Get the slot id of a given slot slot.

param: int $slotnumber the index of the slot in question.
return: int the page number of the page that slot is on.

get_question_type_for_slot($slotnumber)   X-Ref
Get the question type in a given slot.

param: int $slotnumber the index of the slot in question.
return: string the question type (e.g. multichoice).

can_question_depend_on_previous_slot($slotnumber)   X-Ref
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.

param: int $slotnumber the index of the slot in question.
return: bool can this question require the previous one.

can_finish_during_the_attempt($slotnumber)   X-Ref
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.

param: int $slotnumber the index of the slot in question.
return: bool can this question finish naturally during the attempt?

is_question_dependent_on_previous_slot($slotnumber)   X-Ref
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.

param: int $slotnumber the index of the slot in question.
return: bool can this question require the previous one.

is_real_question($slotnumber)   X-Ref
Is a particular question in this attempt a real question, or something like a description.

param: int $slotnumber the index of the slot in question.
return: bool whether that question is a real question.

has_use_capability(int $slotnumber)   X-Ref
Does the current user have '...use' capability over the question(s) in a given slot?

param: int $slotnumber the index of the slot in question.
return: bool true if they have the required capability.

get_courseid()   X-Ref
Get the course id that the quiz belongs to.

return: int the course.id for the quiz.

get_cmid()   X-Ref
Get the course module id of the quiz.

return: int the course_modules.id for the quiz.

get_quizid()   X-Ref
Get id of the quiz.

return: int the quiz.id for the quiz.

get_quiz()   X-Ref
Get the quiz object.

return: \stdClass the quiz settings row from the database.

can_be_repaginated()   X-Ref
Quizzes can only be repaginated if they have not been attempted, the
questions are not shuffled, and there are two or more questions.

return: bool whether this quiz can be repaginated.

can_be_edited()   X-Ref
Quizzes can only be edited if they have not been attempted.

return: bool whether the quiz can be edited.

check_can_be_edited()   X-Ref
This quiz can only be edited if they have not been attempted.
Throw an exception if this is not the case.


get_questions_per_page()   X-Ref
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: int the number of questions that should be on each page of the

get_slots()   X-Ref
Get quiz slots.

return: \stdClass[] the slots in this quiz.

is_first_slot_on_page($slotnumber)   X-Ref
Is this slot the first one on its page?

param: int $slotnumber the index of the slot in question.
return: bool whether this slot the first one on its page.

is_last_slot_on_page($slotnumber)   X-Ref
Is this slot the last one on its page?

param: int $slotnumber the index of the slot in question.
return: bool whether this slot the last one on its page.

is_last_slot_in_section($slotnumber)   X-Ref
Is this slot the last one in its section?

param: int $slotnumber the index of the slot in question.
return: bool whether this slot the last one on its section.

is_only_slot_in_section($slotnumber)   X-Ref
Is this slot the only one in its section?

param: int $slotnumber the index of the slot in question.
return: bool whether this slot the only one on its section.

is_last_slot_in_quiz($slotnumber)   X-Ref
Is this slot the last one in the quiz?

param: int $slotnumber the index of the slot in question.
return: bool whether this slot the last one in the quiz.

is_first_section($section)   X-Ref
Is this the first section in the quiz?

param: \stdClass $section the quiz_sections row.
return: bool whether this is first section in the quiz.

is_last_section($section)   X-Ref
Is this the last section in the quiz?

param: \stdClass $section the quiz_sections row.
return: bool whether this is first section in the quiz.

is_only_one_slot_in_section($section)   X-Ref
Does this section only contain one slot?

param: \stdClass $section the quiz_sections row.
return: bool whether this section contains only one slot.

get_last_slot()   X-Ref
Get the final slot in the quiz.

return: \stdClass the quiz_slots for for the final slot in the quiz.

get_slot_by_id($slotid)   X-Ref
Get a slot by it's id. Throws an exception if it is missing.

param: int $slotid the slot id.
return: \stdClass the requested quiz_slots row.

get_slot_by_number($slotnumber)   X-Ref
Get a slot by it's slot number. Throws an exception if it is missing.

param: int $slotnumber The slot number
return: \stdClass

can_add_section_heading($pagenumber)   X-Ref
Check whether adding a section heading is possible

param: int $pagenumber the number of the page.
return: boolean

get_slots_in_section($sectionid)   X-Ref
Get all the slots in a section of the quiz.

param: int $sectionid the section id.
return: int[] slot numbers.

get_sections()   X-Ref
Get all the sections of the quiz.

return: \stdClass[] the sections in this quiz.

get_section_by_id($sectionid)   X-Ref
Get a particular section by id.

return: \stdClass the section.

get_section_count()   X-Ref
Get the number of questions in the quiz.

return: int the number of questions in the quiz.

formatted_quiz_grade()   X-Ref
Get the overall quiz grade formatted for display.

return: string the maximum grade for this quiz.

formatted_question_grade($slotnumber)   X-Ref
Get the maximum mark for a question, formatted for display.

param: int $slotnumber the index of the slot in question.
return: string the maximum mark for the question in this slot.

get_decimal_places_for_grades()   X-Ref
Get the number of decimal places for displyaing overall quiz grades or marks.

return: int the number of decimal places.

get_decimal_places_for_question_marks()   X-Ref
Get the number of decimal places for displyaing question marks.

return: int the number of decimal places.

get_edit_page_warnings()   X-Ref
Get any warnings to show at the top of the edit page.

return: string[] array of strings.

get_dates_summary()   X-Ref
Get the date information about the current state of the quiz.

return: string[] array of two strings. First a short summary, then a longer

populate_structure()   X-Ref
Set up this class with the structure for a given quiz.


populate_slots_with_sections()   X-Ref
Fill in the section ids for each slot.


populate_question_numbers()   X-Ref
Number the questions.


get_version_choices_for_slot(int $slotnumber)   X-Ref
Get the version options to show on the Questions page for a particular question.

param: int $slotnumber which slot to get the choices for.
return: \stdClass[] other versions of this question. Each object has fields versionid,

move_slot($idmove, $idmoveafter, $page)   X-Ref
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.

param: int $idmove id of slot to be moved
param: int $idmoveafter id of slot to come before slot being moved
param: int $page new page number of slot being moved
param: bool $insection if the question is moving to a place where a new
return: void

refresh_page_numbers($slots = array()   X-Ref
Refresh page numbering of quiz slots.

param: \stdClass[] $slots (optional) array of slot objects.
return: \stdClass[] array of slot objects.

refresh_page_numbers_and_update_db()   X-Ref
Refresh page numbering of quiz slots and save to the database.

param: \stdClass $quiz the quiz object.
return: \stdClass[] array of slot objects.

remove_slot($slotnumber)   X-Ref
Remove a slot from a quiz

param: int $slotnumber The number of the slot to be deleted.

unset_question($slotid)   X-Ref
Unset the question object after deletion.

param: int $slotid

update_slot_maxmark($slot, $maxmark)   X-Ref
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.

param: \stdClass $slot row from the quiz_slots table.
param: float $maxmark the new maxmark.
return: bool true if the new grade is different from the old one.

update_question_dependency($slotid, $requireprevious)   X-Ref
Set whether the question in a particular slot requires the previous one.

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

update_page_break($slotid, $type)   X-Ref
Add/Remove a pagebreak.

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

param: int $slotid id of slot which we will add/remove the page break before.
param: int $type repaginate::LINK or repaginate::UNLINK.
return: \stdClass[] array of slot objects.

add_section_heading($pagenumber, $heading = null)   X-Ref
Add a section heading on a given page and return the sectionid

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

set_section_heading($id, $newheading)   X-Ref
Change the heading for a section.

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

set_section_shuffle($id, $shuffle)   X-Ref
Change the shuffle setting for a section.

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

remove_section_heading($sectionid)   X-Ref
Remove the section heading with the given id

param: int $sectionid the section to remove.

can_add_random_questions()   X-Ref
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: bool

get_slot_tags_for_slot_id($slotid)   X-Ref
Retrieve the list of slot tags for the given slot id.

param: int $slotid The id for the slot
return: \stdClass[] The list of slot tag records