weekly release 4.5dev

[moodle.git] / mod / quiz / upgrade.txt

=== 4.5 Onwards ===

This file has been replaced by UPGRADING.md. See MDL-81125 for further information.

===
This file describes API changes in the quiz code.

=== 4.4 ===
* A quiz_structure_modified callback has been added for quiz_ plugins, called from
  grade_calculator::recompute_quiz_sumgrades(). Plugins can implement this by creating a `quiz_structure_modified`
  class in their namespace with a static `callback` method, see quiz_statistics as an example.
* External functions returning question information, currently get_attempt_summary(), get_attempt_data() and get_attemp_review()
  now return a new field called "stateclass". A machine-readable class name for the state that this question attempt is in,
  as returned by question_usage_by_activity::get_question_state_class().
* External function mod_quiz_external::get_attempt_summary() now returns a new field "totalunanswered", with the total number of
  unanswered questions.
* quiz_settings::no_review_message now takes a new argument $attemptsubmittime for the time when the quiz attempt was
  submitted. It is strongly recommended that you always pass that.
* In the renderer, related to rendering the review page, review_summary_table and filter_review_summary_table have been
  replaced by review_attempt_summary and filter_review_attempt_summary. This is to support changing the $summarydata argument
  the review_page() method to an instance of a new templateable class attempt_summary_information for displaying this.
  The $summarydata argument of review_question_page has also been changed to an attempt_summary_information.
* In the renderer, the view_table has been deprecated. Please use the list_of_attempts renderable instead.
* There is a new function qbank_helper::get_version_information_for_questions_in_attempt to efficiently
  check whether each question in an attempt is using the latest versions. This is used by re-grading,
  replacing some old code there, and to update teacher previews automatically.
* The following previously deprecated methods have been removed and can no longer be used:
  - `get_slot_tags_for_slot_id`
  - `quiz_retrieve_tags_for_slot_ids`
* Quiz override logic has been refactored and put in a new override_manager class.
* Quiz override cache should now be accessed using the new override_cache class.
* The quiz_delete_overrides and quiz_delete_all_overrides functions are now deprecated. Please instead use:
  - override_manager::delete_override_by_id
  - override_manager::delete_overrides
  - override_manager::delete_all_overrides
* There is a new renderable grade_out_of to help with display a nicely formatted "42.00 out of 100.00" with a few variants.
* The quiz now supports computing multiple total grades for each attempt. To support this there is a new database table
  quiz_grade_items and a new column quizgradeitemid in quiz_slots. There are new methods in structure grade_calculator
  and quiz_attempt to support this, and the new grades are shown on review.php, view.php and in some of the quiz reports.
  Also, the external functions get_attempt_review and get_user_attempts return the information about the extra grades if applicable.

=== 4.3 ===

* The method get_questions() has a new parameter 'requirequestionfullyloaded' which can be used to instruct whether the
  questions should be fully loaded or not.
* the quiz_settings and quiz_attempt classes now always store the ->cm property as a cm_info class.
  In the distant past it was always a stdClass, then at one point there was an undocumented change making
  it sometimes a stdClass and sometimes a cm_info. Now it is consistently a cm_info. Type hints have been
  updated to reflect this.
* The parameter filtercondition in the web service mod_quiz_add_random_questions is now optional. This parameter is
  only used when adding random questions from an existing category. It is not required when adding random questions from
  a new category since it is not used in this case.

=== 4.2 ===

* For the three quiz web services: mod_quiz_get_attempt_data, mod_quiz_get_attempt_summary and
  mod_quiz_get_attempt_review, the ->number property of each question is now deprecated
  (It had the wrong time and was documented wrongly.) In the future, please use the new property
  ->questionnumber. Note, this question 'number' can include any string (e.g. 'Qs 1 & 2') so it is
  important to applying htmlspecialchars, or equivalent, to the value if you are outputting to HTML.

* The methods in the quiz_settings class which return a URL now all return a moodle_url. Previously
  some returns a moodle_url and others aa string.

* 'firstslotid' value is not used in section_shuffle_updated event anymore.

* The quiz has a lot of old classes in lib.php files. These have now been moved into the classes folder,
  and so are now in namespaces. Because of Moodle's class renaming support, your code should continue
  working, but output deprecated warnings, so you probably want to update. This should mostly be
  doable by adding use statements, and a search/replace.
  - mod_quiz_display_options => mod_quiz\question\display_options
  - qubaids_for_quiz => mod_quiz\question\qubaids_for_quiz
  - qubaids_for_quiz_user => mod_quiz\question\qubaids_for_quiz_user - which is deprecated, because
          it is almost the same as mod_quiz\question\qubaids_for_users_attempts.
  - mod_quiz_admin_setting_browsersecurity => mod_quiz\admin\browser_security_setting
  - mod_quiz_admin_setting_grademethod => mod_quiz\admin\grade_method_setting
  - mod_quiz_admin_setting_overduehandling => mod_quiz\admin\overdue_handling_setting
  - mod_quiz_admin_review_setting => mod_quiz\admin\review_setting
  - mod_quiz_admin_setting_user_image => mod_quiz\admin\user_image_setting
  - mod_quiz_admin_setting_browsersecurity => mod_quiz\admin\browser_security_setting
  - mod_quiz_admin_setting_grademethod => mod_quiz\admin\grade_method_setting
  - mod_quiz_admin_setting_overduehandling => mod_quiz\admin\overdue_handling_setting
  - mod_quiz_admin_review_setting => mod_quiz\admin\review_setting
  - mod_quiz_admin_setting_user_image => mod_quiz\admin\user_image_setting
  - mod_quiz\adminpresets\adminpresets_mod_quiz_admin_setting_browsersecurity =>
            mod_quiz\adminpresets\adminpresets_browser_security_setting
  - mod_quiz\adminpresets/adminpresets_mod_quiz_admin_setting_grademethod =>
            mod_quiz\adminpresets\adminpresets_grade_method_setting
  - mod_quiz\adminpresets\adminpresets_mod_quiz_admin_setting_overduehandling =>
            mod_quiz\adminpresets\adminpresets_overdue_handling_setting
  - mod_quiz\adminpresets\adminpresets_mod_quiz_admin_review_setting =>
            mod_quiz\adminpresets\adminpresets_review_setting
  - mod_quiz\adminpresets\adminpresets_mod_quiz_admin_setting_user_image =>
            mod_quiz\adminpresets\adminpresets_user_image_setting
  - quiz_default_report => mod_quiz\local\reports\report_base
  - quiz_attempts_report => mod_quiz\local\reports\attempts_report
  - mod_quiz_attempts_report_form => mod_quiz\local\reports\attempts_report_options_form
  - mod_quiz_attempts_report_options => mod_quiz\local\reports\attempts_report_options
  - quiz_attempts_report_table => mod_quiz\local\reports\attempts_report_table
  - quiz_access_manager => mod_quiz\access_manager
  - mod_quiz_preflight_check_form => mod_quiz\form\preflight_check_form
  - quiz_override_form => mod_quiz\form\edit_override_form
  - quiz_access_rule_base => mod_quiz\local\access_rule_base
  - quiz_add_random_form => mod_quiz\form\add_random_form
  - mod_quiz_links_to_other_attempts => mod_quiz\output\links_to_other_attempts
  - mod_quiz_view_object => mod_quiz\output\view_page
  - mod_quiz_renderer => mod_quiz\output\renderer
  - quiz_nav_question_button => mod_quiz\output\navigation_question_button
  - quiz_nav_section_heading => mod_quiz\output\navigation_section_heading
  - quiz_nav_panel_base => mod_quiz\output\navigation_panel_base
  - quiz_attempt_nav_panel => mod_quiz\output\navigation_panel_attempt
  - quiz_review_nav_panel => mod_quiz\output\navigation_panel_review
  - quiz_attempt => mod_quiz\quiz_attempt
  - quiz => mod_quiz\quiz_settings
  - quizaccess_seb\quiz_settings => quizaccess_seb\seb_quiz_settings
  - quizaccess_seb\access_manager => quizaccess_seb\seb_access_manager

* The following classes have been deprecated:
  - mod_quiz_overdue_attempt_updater - merged into mod_quiz\task\update_overdue_attempts
  - moodle_quiz_exception - just use normal moodle_exception

* As part of the clean-up, the following files are no longer required, and if you try to
  include them, you will get a debugging notices telling you not to:
  - mod/quiz/report/attemptsreport.php
  - mod/quiz/report/attemptsreport_form.php
  - mod/quiz/report/attemptsreport_options.php
  - mod/quiz/report/attemptsreport_table.php
  - mod/quiz/report/default.php
  - mod/quiz/accessmanager.php
  - mod/quiz/accessmanager_form.php
  - mod/quiz/cronlib.php
  - mod/quiz/override_form.php
  - mod/quiz/accessrule/accessrulebase.php
  - mod/quiz/renderer.php - actually, no debugging ouput for this one because of how renderer factories work.
  - mod/quiz/attemptlib.php

* Various functions related to calculating grades have moved into a new class mod_quiz\grade_calculator.
  You get that using $quizobj->get_grade_calculator(), then the following old functions have become these new methods.
  - quiz_update_sumgrades -> recompute_quiz_sumgrades
  - quiz_update_all_attempt_sumgrades -> recompute_all_attempt_sumgrades
  - quiz_update_all_final_grades -> recompute_all_final_grades
  - quiz_set_grade -> update_quiz_maximum_grade
  - quiz_save_best_grade -> recompute_final_grade
  - quiz_calculate_best_grade -> [no public direct replacement]
  - quiz_calculate_best_attempt - [no replacement. It was not used.]

* Final deprecation (complete removal) of the following functions which were deprecated long ago:
  - quiz_groups_member_added_handler - deprecated since 2.6
  - quiz_groups_member_removed_handler - deprecated since 2.6
  - quiz_groups_group_deleted_handler - deprecated since 2.6
  - quiz_groups_members_removed_handler - deprecated since 2.6
  - The method quiz_settings::confirm_start_attempt_message - deprecated in Moodle 3.1
  - The field view_page::$startattemptwarning - deprecated in Moodle 3.1
  - attempts_report::load_relevant_students - deprecated since 3.2
  - quiz_statistics_graph_get_new_colour - deprecated since 3.2
  - The file mod/quiz/report/overview/overviewgraph.php - deprecated since 3.2
  - The file mod/quiz/report/statistics/statistics_graph.php - deprecated since 3.2
  - quiz_print_overview - deprecated since 3.3

* For properties that were previously only declared dynamically, a few classes now include property declarations to support PHP 8.2.
  The affected classes are:
   - restore_quiz_activity_structure_step
   - attempts_report_table
   - attempts_report
   - quiz_overview_report (Removing $hasgroupstudents, because the parent attempts_report class has the same variable.)

=== 4.1 ===

* quiz_has_question_use is now deprecated. Use mod_quiz\structure::has_use_capability istead.


=== 4.0.3, 4.1 ===

* If a quiz is sequential the external functions mod_quiz_external::get_attempt_data, mod_quiz_external::get_attempt_summary will not return any data
related to out of sequence question except while reviewing the quiz (MDL-75210).

=== 4.0.2, 4.1 ===

* No external code should be calling quiz_overview_report::regrade_attempt because it is an
  internal method of the quiz_overview plugin. But if you are incorrectly using it, be aware
  that the API changed slightly. It now returns an array listing any questions which could
  not be regraded.
* New method called get_number_of_unanswered_questions() has been added to mod/quiz/attemptlib.php
  to get the total number of unanswered questions in the current attempt.

=== 4.0 ===

* The following API methods have a new parameter, $studentisonline, to define whether the student is currently interacting:
  - process_finish() in mod/quiz/attemptlib.php
  - quiz_send_confirmation() in mod/quiz/locallib.php
  - quiz_send_notification_messages() in mod/quiz/locallib.php
* The completionpass criteria has been moved to core as 'completionpassgrade'. Refer to completion/upgrade.txt for
  further information.
* New argument quizhasquestions has been added to public methods: view_information in mod/quiz/renderer.php.
* The function no_questions_message() in class mod_quiz_renderer is deprecated. There is no replacement.
* Related to the Moodle 4.0 question bank changes, the quiz_slots database table.
  The fields removed are now manage by new core_question tables:
  - question_references -> Records where a specific question is used.
  - question_set_references -> Records where groups of questions are used (e.g. random questions).
* The quiz_slots_tags database table has been removed entirely, as has the get_slot_tags_for_slot_id() method
  from mod/quiz/classes/structure.php and the the locallib.php functions quiz_retrieve_slot_tags and
  quiz_retrieve_slot_tag_ids. This information is now stored in question_set_references
  and can be accessed in the results of qbank_helper::get_question_structure.


=== 3.11 ===

* External function mod_quiz_external::get_user_best_grade now returns and additional optional field:
  - gradetopass: The grade to pass the quiz (if set)


=== 3.10.1 ===

* External functions mod_quiz_external::get_attempt_data, mod_quiz_external::get_attempt_summary
  and mod_quiz_external::get_attempt_review now return a new additional optional field:
   - settings: Containing the question definition settings for displaying the question in an external system.

=== 3.10 ===

* External functions mod_quiz_external::get_attempt_data, mod_quiz_external::get_attempt_summary
  and mod_quiz_external::get_attempt_review now return a new additional optional field:
   - responsefileareas: Containing the user responses to questions file area names including files.

=== 3.7 ===

* Quiz_cron() has been removed. Sub-plugins should implemented scheduled tasks, however legacy cron in subplugins are
  supported.

=== 3.6 ===

* The following renamed classes have been completely removed:
  - quiz_question_bank_view (now: mod_quiz\question\bank\custom_view)
  - question_bank_add_to_quiz_action_column (now: mod_quiz\question\bank\add_action_column)
  - question_bank_question_name_text_column (now: mod_quiz\question\bank\question_name_text_column)

=== 3.5 ===
* Removed questionbank.ajax.php. Please use the quiz_question_bank fragment instead.
* Adding "random" questions to a quiz via quiz_add_quiz_question() has been deprecated. Please use quiz_add_random_questions().

=== 3.3.2 ===

* quiz_refresh_events() Now takes two additional parameters to refine the update to a specific instance. This function
  now optionally takes the module instance object or ID, and the course module object or ID. Please try to send the full
  objects instead of the ids to save DB calls.

=== 3.2 ===

* External functions mod_quiz_external::get_attempt_data, mod_quiz_external::get_attempt_summary
  and mod_quiz_external::get_attempt_review now return additional optional fields:
   - blockedbyprevious: Whether a question is blocked by the previous question.

=== 3.1 ===

* quiz_attempt::question_print_comment_fields() has been removed. It was broken
  since at least Moodle 2.0.

* quiz::confirm_start_attempt_message and mod_quiz_view_object::$startattemptwarning
  have been deprecated. This functionality is now entirely handled within the
  quiz access rule plugins.

* The third argument to mod_quiz_renderer::start_attempt_button has been changed
  from a warning string to a mod_quiz_preflight_check_form.

* mod_quiz_renderer::review_next_navigation has a new optional argument. If you
  have overridden that method, consider updating your code to match.

* mod_quiz\output\edit_renderer::start_section_list now takes $structure as an
  argument. If you have overridden this method (it's hard to believe anyone ever
  would) you will need to update your renderer.

* Several methods relating to preview links/buttons/urls have a new optional
  argument to make the preview be of a particular variant.


=== 2.9 ===

* There have been changes in classes/output/edit_renderer.php for MDL-40990.
  + Some methods use to take $structure & $question as the first two arguments.
    They now take $structure & $slot number. If you need $question, you can get
    it using $question = $structure->get_question_in_slot($slot);
  + Some methods used to take $quiz & $question. They now take $structure & $slot
    number. You can get $question as above. $quiz is $structure->get_quiz().
  + initialise_editing_javascript has had some redundant arguments removed.
  Hopefully, with these changes, we will have less need to make other changes in future.

* Due to MDL-40992, you should be aware that extra slots can get added to an attempt.
  You may get slot numbers beyone the end of the original quiz layout, and you
  may want to call $attemptobj->get_original_slot to find where the question
  originally came from.

* You now need to pass an instance of the mod_quiz_renderer if you call
  $attemptobj->render_question or $attemptobj->render_question_at_step.

* The array values in mod_quiz_links_to_other_attempts may now be either a moodle_url,
  or renderable (or null). Previously they could only be a moodle_url or null.

* The contents of the navigation block is now not just quiz_nav_question_button-s.
  It can also contain quiz_nav_section_heading-s. If you have overridden
  mod_quiz_renderer::navigation_panel, then you may need to account for this.
  This change also has implications for the Edit quiz page.


=== 2.8 ===

* Classes that were defined in various lib files have been moved to the classes
  folder to take advantage of auto-loading. This has involved renaming them.
  see the list in mod/quiz/db/renamedclasses.php.

* The quiz no longer handles its own \mod_quiz\event\attempt_becameoverdue event,
  and so the event handler function quiz_attempt_overdue_handler has been deleted.
  Also, the internal function quiz_send_overdue_message has add the arguments
  changed. It now takes the $attemptobj object, not separate stdClass objects.

* Major changes to the Edit quiz page.

  The goal of this work was to increase usability, and also clean up the page
  enough that it will be possible to add new features in future.

  Display of mod/quiz/edit.php is now entirely generated by
  mod_quiz\output\edit_renderer. This uses a helper class mod_quiz\structure
  to provide details of the structure of the quiz, and mod_quiz\repaginate to
  alter that structure. (Actually, there are still some modification methods on
  mod_quiz\structure. Expect that to be cleaned up in future.)

  The new code uses much more ajax, and there are new scripts mod/quiz/edit_rest.php
  and mod/quiz/repaginate.php to handle this. (Again, don't be surprised if those
  two scripts get merged in future.) Also questionbank.ajax.php (which may, in
  future, be made more generic, and moved into the core question bank code.)

  As a result of this, mod/quiz/editlib.php has gone. (A few remaining functions
  were moved to locallib.php.)

  Here is a list of all the old functions or classes that have changed.
  If you used any of these in custom code, you will need to update your code.
  (Note that many of these functions should have been considered private internals
  of the quiz module, and you should not have been using them!)

  From editlib.php:
      quiz_remove_slot
      quiz_delete_empty_page
      quiz_add_page_break_after_slot    - Use methods of structure or repaginate
      quiz_update_slot_maxmark          - classes instead.
      _quiz_move_question
      quiz_move_question_up
      quiz_move_question_down

      quiz_print_question_list
      quiz_print_pagecontrols
      quiz_print_singlequestion         - Use methods of edit_renderer instead.
      quiz_print_randomquestion
      quiz_print_singlequestion_reordertool
      quiz_print_randomquestion_reordertool
      print_random_option_icon
      quiz_print_grading_form
      quiz_print_status_bar

  Moved from editlib.php to locallib.php:
      quiz_question_tostring - now always returns a string (the only option used).
                               The $return argument has gone.

  Old editing JavaScript (e.g. mod/quiz/edit.js) is gone. Replaced with YUI modules.


=== 2.7.1 ===

* The function quiz_fire_attempt_started_event has been removed. This function
  should not have been used outside the quiz, but if you were using it, you should
  trigger the event outside this function. Note that the appropriate start event is
  fired automatically by the quiz_attempt_save_started function.


=== 2.7 ===

* The old quiz.questions database column (comma-separated list of question ids)
  is gone, and instead the quiz_question_instances table has been renamed to
  to quiz_slots. Some of the columns of that table have been renamed to match
  the coding guidelines. Specifically:
      quiz     -> quizid
      question -> questionid
      grade    -> maxmark
  also there are two new columns:
      slot     -  numbers the questions in the quiz in order, as on the edit quiz page.
      page     -  new way to determine which question is on which page.
  naturally, other parts of the code and APIs have been updated to reflect that
  change.

* The following functions, which were part of the internal workings of the quiz,
  have been removed.
      quiz_get_slot_for_question
      quiz_number_of_questions_in_quiz
      quiz_repaginate               (there is now a quiz_repaginate_questions with a different API).
      quiz_add_page_break_at        (see quiz_add_page_break_after_slot)
      quiz_add_page_break_after     (see quiz_add_page_break_after_slot)
      quiz_number_of_pages
      quiz_remove_question          (see quiz_remove_slot)
      quiz_update_question_instance (see quiz_update_slot_maxmark)

* The following internal functions have had their API changed.
      quiz_delete_empty_page: has had its arguments changed to $quiz and $pagenumber.
      quiz_has_question_use: now takes $quiz and $slot, not $questionid.


=== 2.6 ===

* As part of improving the page usability and accessibility, we updated the
  heading levels for quiz module so it has a proper nesting. (MDL-41615)

* mod_quiz_renderer::view_best_score has been removed. (It did not do what the
  name suggested anyway.)


=== 2.4 ===

* mod_quiz_renderer::finish_review_link now requires $attemptobj to be passed in
  instead of a moodle_url.


=== Earlier changes ===

* Were not documented in this way. Sorry.