Search moodle.org's
Developer Documentation


  • Bug fixes for general core bugs in 2.8.x ended 9 November 2015 (12 months).
  • Bug fixes for security issues in 2.8.x ended 9 May 2016 (18 months).
  • minimum PHP 5.4.4 (always use latest PHP 5.4.x or 5.5.x on Windows - http://windows.php.net/download/), PHP 7 is NOT supported
  • Differences Between: [Versions 28 and 29] [Versions 28 and 30] [Versions 28 and 31] [Versions 28 and 32] [Versions 28 and 33] [Versions 28 and 34] [Versions 28 and 35] [Versions 28 and 36] [Versions 28 and 37]

    Library of functions used by the quiz module. This contains functions that are called from within the quiz module only Functions that are also called by core Moodle are in {@link lib.php} This script also loads the code in {@link questionlib.php} which holds the module-indpendent code for handling questions and which in turn initialises all the questiontype classes.

    Copyright: 1999 onwards Martin Dougiamas and others {@link http://moodle.com}
    License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
    File Size: 2047 lines (77 kb)
    Included or required: 3 times
    Referenced: 38 times
    Includes or requires: 0 files

    Defines 2 classes

    mod_quiz_display_options:: (2 methods):
      make_from_quiz()
      extract()

    qubaids_for_quiz:: (6 methods):
      __construct()
      quiz_question_tostring()
      quiz_require_question_use()
      quiz_has_question_use()
      quiz_add_quiz_question()
      quiz_add_random_questions()

    Defines 6 functions


    Class: mod_quiz_display_options  - X-Ref

    An extension of question_display_options that includes the extra options used
    by the quiz.

    make_from_quiz($quiz, $when)   X-Ref
    Set up the various options from the quiz settings, and a time constant.

    return: mod_quiz_display_options set up appropriately.
    param: object $quiz the quiz settings.
    param: int $one of the {@link DURING}, {@link IMMEDIATELY_AFTER},

    extract($bitmask, $bit,$whenset = self::VISIBLE, $whennotset = self::HIDDEN)   X-Ref
    No description

    Class: qubaids_for_quiz  - X-Ref

    A {@link qubaid_condition} for finding all the question usages belonging to
    a particular quiz.

    __construct($quizid, $includepreviews = true, $onlyfinished = false)   X-Ref
    No description

    quiz_question_tostring($question, $showicon = false, $showquestiontext = true)   X-Ref
    Creates a textual representation of a question for display.

    return: string
    param: object $question A question object from the database questions table
    param: bool $showicon If true, show the question's icon with the question. False by default.
    param: bool $showquestiontext If true (default), show question text after question name.

    quiz_require_question_use($questionid)   X-Ref
    Verify that the question exists, and the user has permission to use it.
    Does not return. Throws an exception if the question cannot be used.

    param: int $questionid The id of the question.

    quiz_has_question_use($quiz, $slot)   X-Ref
    Verify that the question exists, and the user has permission to use it.

    return: bool whether the user can use this question.
    param: object $quiz the quiz settings.
    param: int $slot which question in the quiz to test.

    quiz_add_quiz_question($questionid, $quiz, $page = 0, $maxmark = null)   X-Ref
    Add a question to a quiz

    Adds a question to a quiz by updating $quiz as well as the
    quiz and quiz_slots tables. It also adds a page break if required.
    return: bool false if the question was already in the quiz
    param: int $questionid The id of the question to be added
    param: object $quiz The extended quiz object as used by edit.php
    param: int $page Which page in quiz to add the question on. If 0 (default),
    param: float $maxmark The maximum mark to set for this question. (Optional,

    quiz_add_random_questions($quiz, $addonpage, $categoryid, $number,$includesubcategories)   X-Ref
    Add a random question to the quiz at a given point.

    param: object $quiz the quiz settings.
    param: int $addonpage the page on which to add the question.
    param: int $categoryid the question category to add the question from.
    param: int $number the number of random questions to add.
    param: bool $includesubcategories whether to include questoins from subcategories.

    Functions that are not part of a class:

    quiz_create_attempt(quiz $quizobj, $attemptnumber, $lastattempt, $timenow, $ispreview = false, $userid = null)   X-Ref
    Creates an object to represent a new attempt at a quiz

    Creates an attempt object to represent an attempt at the quiz by the current
    user starting at the current time. The ->id field is not set. The object is
    NOT written to the database.

    return: object the newly created attempt object.
    param: object $quizobj the quiz object to create an attempt for.
    param: int $attemptnumber the sequence number for the attempt.
    param: object $lastattempt the previous attempt by this user, if any. Only needed
    param: int $timenow the time the attempt was started at.
    param: bool $ispreview whether this new attempt is a preview.
    param: int $userid  the id of the user attempting this quiz.

    quiz_start_new_attempt($quizobj, $quba, $attempt, $attemptnumber, $timenow,$questionids = array()   X-Ref
    Start a normal, new, quiz attempt.

    return: object   modified attempt object
    param: quiz      $quizobj            the quiz object to start an attempt for.
    param: question_usage_by_activity $quba
    param: object    $attempt
    param: integer   $attemptnumber      starting from 1
    param: integer   $timenow            the attempt start time
    param: array     $questionids        slot number => question id. Used for random questions, to force the choice
    param: array     $forcedvariantsbyslot slot number => variant. Used for questions with variants,

    quiz_start_attempt_built_on_last($quba, $attempt, $lastattempt)   X-Ref
    Start a subsequent new attempt, in each attempt builds on last mode.

    return: object                       modified attempt object
    param: question_usage_by_activity    $quba         this question usage
    param: object                        $attempt      this attempt
    param: object                        $lastattempt  last attempt

    quiz_attempt_save_started($quizobj, $quba, $attempt)   X-Ref
    The save started question usage and quiz attempt in db and log the started attempt.

    return: object                    attempt object with uniqueid and id set.
    param: quiz                       $quizobj
    param: question_usage_by_activity $quba
    param: object                     $attempt

    quiz_get_user_attempt_unfinished($quizid, $userid)   X-Ref
    Returns an unfinished attempt (if there is one) for the given
    user on the given quiz. This function does not return preview attempts.

    return: mixed the unfinished attempt if there is one, false if not.
    param: int $quizid the id of the quiz.
    param: int $userid the id of the user.

    quiz_delete_attempt($attempt, $quiz)   X-Ref
    Delete a quiz attempt.

    param: mixed $attempt an integer attempt id or an attempt object
    param: object $quiz the quiz object.

    quiz_delete_previews($quiz, $userid = null)   X-Ref
    Delete all the preview attempts at a quiz, or possibly all the attempts belonging
    to one user.

    param: object $quiz the quiz object.
    param: int $userid (optional) if given, only delete the previews belonging to this user.

    quiz_has_attempts($quizid)   X-Ref

    return: bool whether this quiz has any (non-preview) attempts.
    param: int $quizid The quiz id.

    quiz_repaginate_questions($quizid, $slotsperpage)   X-Ref
    Repaginate the questions in a quiz

    param: int $quizid the id of the quiz to repaginate.
    param: int $slotsperpage number of items to put on each page. 0 means unlimited.

    quiz_rescale_grade($rawgrade, $quiz, $format = true)   X-Ref
    Convert the raw grade stored in $attempt into a grade out of the maximum
    grade for this quiz.

    return: float|string the rescaled grade, or null/the lang string 'notyetgraded'
    param: float $rawgrade the unadjusted grade, fof example $attempt->sumgrades
    param: object $quiz the quiz object. Only the fields grade, sumgrades and decimalpoints are used.
    param: bool|string $format whether to format the results for display

    quiz_feedback_for_grade($grade, $quiz, $context)   X-Ref
    Get the feedback text that should be show to a student who
    got this grade on this quiz. The feedback is processed ready for diplay.

    return: string the comment that corresponds to this grade (empty string if there is not one.
    param: float $grade a grade on this quiz.
    param: object $quiz the quiz settings.
    param: object $context the quiz context.

    quiz_has_feedback($quiz)   X-Ref

    return: bool Whether this quiz has any non-blank feedback text.
    param: object $quiz the quiz database row.

    quiz_update_sumgrades($quiz)   X-Ref
    Update the sumgrades field of the quiz. This needs to be called whenever
    the grading structure of the quiz is changed. For example if a question is
    added or removed, or a question weight is changed.

    You should call {@link quiz_delete_previews()} before you call this function.

    param: object $quiz a quiz.

    quiz_update_all_attempt_sumgrades($quiz)   X-Ref
    Update the sumgrades field of the attempts at a quiz.

    param: object $quiz a quiz.

    quiz_set_grade($newgrade, $quiz)   X-Ref
    The quiz grade is the maximum that student's results are marked out of. When it
    changes, the corresponding data in quiz_grades and quiz_feedback needs to be
    rescaled. After calling this function, you probably need to call
    quiz_update_all_attempt_sumgrades, quiz_update_all_final_grades and
    quiz_update_grades.

    return: bool indicating success or failure.
    param: float $newgrade the new maximum grade for the quiz.
    param: object $quiz the quiz we are updating. Passed by reference so its

    quiz_save_best_grade($quiz, $userid = null, $attempts = array()   X-Ref
    Save the overall grade for a user at a quiz in the quiz_grades table

    return: bool Indicates success or failure.
    param: object $quiz The quiz for which the best grade is to be calculated and then saved.
    param: int $userid The userid to calculate the grade for. Defaults to the current user.
    param: array $attempts The attempts of this user. Useful if you are

    quiz_calculate_best_grade($quiz, $attempts)   X-Ref
    Calculate the overall grade for a quiz given a number of attempts by a particular user.

    return: float          the overall grade
    param: object $quiz    the quiz settings object.
    param: array $attempts an array of all the user's attempts at this quiz in order.

    quiz_update_all_final_grades($quiz)   X-Ref
    Update the final grade at this quiz for all students.

    This function is equivalent to calling quiz_save_best_grade for all
    users, but much more efficient.

    param: object $quiz the quiz settings.

    quiz_update_open_attempts(array $conditions)   X-Ref
    Efficiently update check state time on all open attempts

    param: array $conditions optional restrictions on which attempts to update

    quiz_get_attempt_usertime_sql($redundantwhereclauses = '')   X-Ref
    Returns SQL to compute timeclose and timelimit for every attempt, taking into account user and group overrides.

    return: string SQL select with columns attempt.id, usertimeclose, usertimelimit.
    param: string $redundantwhereclauses extra where clauses to add to the subquery

    quiz_calculate_best_attempt($quiz, $attempts)   X-Ref
    Return the attempt with the best grade for a quiz

    Which attempt is the best depends on $quiz->grademethod. If the grade
    method is GRADEAVERAGE then this function simply returns the last attempt.
    return: object         The attempt with the best grade
    param: object $quiz    The quiz for which the best grade is to be calculated
    param: array $attempts An array of all the attempts of the user at the quiz

    quiz_get_grading_options()   X-Ref

    return: array int => lang string the options for calculating the quiz grade

    quiz_get_grading_option_name($option)   X-Ref

    return: the lang string for that option.
    param: int $option one of the values QUIZ_GRADEHIGHEST, QUIZ_GRADEAVERAGE,

    quiz_get_overdue_handling_options()   X-Ref

    return: array string => lang string the options for handling overdue quiz

    quiz_get_user_image_options()   X-Ref
    Get the choices for what size user picture to show.

    return: array string => lang string the options for whether to display the user's picture.

    quiz_questions_per_page_options()   X-Ref
    Get the choices to offer for the 'Questions per page' option.

    return: array int => string.

    quiz_attempt_state_name($state)   X-Ref
    Get the human-readable name for a quiz attempt state.

    return: string The lang string to describe that state.
    param: string $state one of the state constants like {@link quiz_attempt::IN_PROGRESS}.

    quiz_question_action_icons($quiz, $cmid, $question, $returnurl)   X-Ref

    return: string html for a number of icons linked to action pages for a
    param: object $quiz the quiz.
    param: int $cmid the course_module object for this quiz.
    param: object $question the question.
    param: string $returnurl url to return to after action is done.

    quiz_question_edit_button($cmid, $question, $returnurl, $contentaftericon = '')   X-Ref

    return: the HTML for an edit icon, view icon, or nothing for a question
    param: int $cmid the course_module.id for this quiz.
    param: object $question the question.
    param: string $returnurl url to return to after action is done.
    param: string $contentbeforeicon some HTML content to be added inside the link, before the icon.

    quiz_question_preview_url($quiz, $question)   X-Ref

    return: moodle_url to preview this question with the options from this quiz.
    param: object $quiz the quiz settings
    param: object $question the question

    quiz_question_preview_button($quiz, $question, $label = false)   X-Ref

    return: the HTML for a preview question icon.
    param: object $quiz the quiz settings
    param: object $question the question
    param: bool $label if true, show the preview question label after the icon

    quiz_get_flag_option($attempt, $context)   X-Ref

    return: int whether flags should be shown/editable to the current user for this attempt.
    param: object $attempt the attempt.
    param: object $context the quiz context.

    quiz_attempt_state($quiz, $attempt)   X-Ref
    Work out what state this quiz attempt is in - in the sense used by
    quiz_get_review_options, not in the sense of $attempt->state.

    return: int one of the mod_quiz_display_options::DURING,
    param: object $quiz the quiz settings
    param: object $attempt the quiz_attempt database row.

    quiz_get_review_options($quiz, $attempt, $context)   X-Ref
    The the appropraite mod_quiz_display_options object for this attempt at this
    quiz right now.

    return: mod_quiz_display_options
    param: object $quiz the quiz instance.
    param: object $attempt the attempt in question.
    param: $context the quiz context.

    quiz_get_combined_reviewoptions($quiz, $attempts)   X-Ref
    Combines the review options from a number of different quiz attempts.
    Returns an array of two ojects, so the suggested way of calling this
    funciton is:
    list($someoptions, $alloptions) = quiz_get_combined_reviewoptions(...)

    return: array of two options objects, one showing which options are true for
    param: object $quiz the quiz instance.
    param: array $attempts an array of attempt objects.
    param: $context the roles and permissions context,

    quiz_send_confirmation($recipient, $a)   X-Ref
    Sends a confirmation message to the student confirming that the attempt was processed.

    return: int|false as for {@link message_send()}.
    param: object $a lots of useful information that can be used in the message

    quiz_send_notification($recipient, $submitter, $a)   X-Ref
    Sends notification messages to the interested parties that assign the role capability

    return: int|false as for {@link message_send()}.
    param: object $recipient user object of the intended recipient
    param: object $a associative array of replaceable fields for the templates

    quiz_send_notification_messages($course, $quiz, $attempt, $context, $cm)   X-Ref
    Send all the requried messages when a quiz attempt is submitted.

    return: bool true if all necessary messages were sent successfully, else false.
    param: object $course the course
    param: object $quiz the quiz
    param: object $attempt this attempt just finished
    param: object $context the quiz context
    param: object $cm the coursemodule for this quiz

    quiz_send_overdue_message($attemptobj)   X-Ref
    Send the notification message when a quiz attempt becomes overdue.

    param: quiz_attempt $attemptobj all the data about the quiz attempt.

    quiz_attempt_submitted_handler($event)   X-Ref
    Handle the quiz_attempt_submitted event.

    This sends the confirmation and notification messages, if required.

    param: object $event the event object.

    quiz_groups_member_added_handler($event)   X-Ref
    Handle groups_member_added event

    param: object $event the event object.

    quiz_groups_member_removed_handler($event)   X-Ref
    Handle groups_member_removed event

    param: object $event the event object.

    quiz_groups_group_deleted_handler($event)   X-Ref
    Handle groups_group_deleted event

    param: object $event the event object.

    quiz_process_group_deleted_in_course($courseid)   X-Ref
    Logic to happen when a/some group(s) has/have been deleted in a course.

    return: void
    param: int $courseid The course ID.

    quiz_groups_members_removed_handler($event)   X-Ref
    Handle groups_members_removed event

    param: object $event the event object.

    quiz_get_js_module()   X-Ref
    Get the information about the standard quiz JavaScript module.

    return: array a standard jsmodule structure.

    Search This Site: