MDL-73975 course: Remove course_search_form template
[moodle.git] / question / upgrade.txt
blobb2a9d4281c81aa206cafbf5239318abdfcd85d42
1 This files describes API changes for code that uses the question API.
3 === 4.4 ===
4 * The following previously deprecated methods have been removed and can no longer be used:
5   - `submit_tags_form`
6   - `get_bulk_action_key`
7   - `preview_question_url`
8   - `process_actions`
9   - `process_actions_needing_ui`
10   - `question_is_only_child_of_top_category_in_context`
11   - `question_is_top_category`
12   - `question_can_delete_cat`
13   - `print_choose_qtype_to_add_form`
14   - `create_new_question_button`
15   - `question_preview_link`
16   - `core_question_output_fragment_tags_form`
17   - `render_qbank_chooser`
18   - `qbank_chooser`
19   - `qbank_chooser_types`
20   - `qbank_chooser_qtype`
21   - `qbank_chooser_title`
23 * The following previously deprecated files have been removed and can no longer be used:
24   - `question/amd/src/edit_tags.js`
25   - `question/amd/src/repository.js`
26   - `question/amd/src/selectors.js`
27   - `question/category_class.php`
28   - `question/category_form.php`
29   - `question/export_form.php`
30   - `question/import_form.php`
31   - `question/move_form.php`
32   - `question/previewlib.php`
33   - `question/yui/src/preview/js/preview.js`
35 * The following previously deprecated JS functions have been removed and can no longer be used:
36   - `M.core_scroll_manager.scroll_to_saved_pos`
37   - `M.core_question_engine.init_form`
38   - `M.core_question_engine.prevent_repeat_submission`
40 === 4.3 ===
42 1) The core_question_generator::update_question has been changed so that it no longer modifies the $question
43    object that was passed in. Instead, the update question is returned (which was already the case).
44    If you were relying on the old behavioru in your tests, you will need a change like
45        $questiongenerator->update_question($question, ...);
46    to
47        $question = $questiongenerator->update_question($question, ...);
48    Also, the $question object returned now has fields questionbankentryid, versionid, version and status.
50 2) question_stats_cleanup_task has been removed. It is no longer required. Instead,
51    older statistics are deleted whenever a new set are calculated for a particular quiz.
53 3) In the past, the methods get_last_calculated_time() and get_cached() of \core_question\statistics\responses\analyser
54    and \core_question\statistics\questions\all_calculated_for_qubaid_condition
55    only returned the pre-computed statistics if they were computed less than 15 minutes ago. Now, they will
56    always return any computed statistics that exist. Therefore, the constants TIME_TO_CACHE in those classes
57    have been deprecated.
59 4) The cache() methods of classes analysis_for_question, analysis_for_subpart, analysis_for_class
60    and analysis_for_actual_response now take an optional $calculationtime, which is used the time
61    stored in the database. If not given, time() is used.
63 5) The "Start again with these options" text is changed "Save preview options and start again". If you use this text in behat test, please use the new text
64    or use the id of the button id_saverestart instead.
66 6) The question bank tertiary navigation is now built using the `plugin_feature::get_navigation_node()` functions from qbank plugins.
67    This allows plugins to extend the navigation with their own links.
69 7) The tertiary navigation now allows pages to add their own action button next to the navigation menu by calling
70    `set_action_button()` on the `qbank_action_menu` object. This means plugin pages can include their own button like the
71    category management page has "Add category".
73 8) The question bank view now has additional hooks for qbank plugins to modify how the question bank is displayed.
74    `\core_question\local\bank\column_manager_base` defines methods for setting the order, visibility and width of columns, and
75    for providing a list of actions to be displayed in each column's header. Any qbank plugin can return a subclass of this from
76    its `plugin_features::get_column_manager()` method to implement its own logic for these methods. Only one column manager can be
77    active at a time, so in the case of multiple enabled plugins providing a column manager, the first one will be used by component
78    name sorted alphabetically.
79    Plugins can also define `plugin_features::get_question_bank_controls()` returning a list of renderables that will be displayed
80    above the question bank table, to provide additional functionality on the question bank page.
82 9) CSS selectors using #categoryquestions to address the table on the question bank page have now been changed to use
83   .question-bank-table. This applies to the same styles to preview on the qbank_columnsortorder admin screen. It is important
84   that the styles match on these pages so that the defaults have the expected result in the question bank.
86 === 4.2 ===
88 1) The question/qengine.js has been deprecated. We create core_question/question_engine
89    and core/scroll_manager to replace it.
91 2) For properties that were previously only declared dynamically, a few classes now include property declarations to support PHP 8.2.
92    The affected classes are:
93    * restore_qbank_customfields_plugin
94    * category_condition
95    * tag_condition
96    * question_behaviour_attempt_updater
97    * question_engine_attempt_upgrader
98    * qformat_blackboard_six
99    * qtype_multianswer_edit_form
100    * qtype_ddimageortext_drop_zone
101    * qtype_randomsamatch_qe2_attempt_updater
102    * qformat_default
104    Some existing code and variables must be removed while working on this issue, including:
105    * Removed $replace in class qtype_calculated_variable_substituter
106    * Removed $wizarddisplay qtype_calculatedsimple_edit_form::definition_inner()
107    * Removed '$question->places[$placeno]->fieldname = $fieldname' in qtype_ddtoimage_renderer_base::formulation_and_controls()
108    * Removed $mc->single in qtype_multianswer_test_helper::make_multianswer_question_multiple()
110 3) display_move_form() in qbank_managecategories\question_category_object class is deprecated and moved the logic to
111    the question/bank/managecategories/category.php.
113 === 4.1 ===
115 1) get_bulk_action_key() in core_question\local\bank\bulk_action_base class is deprecated and renamed to get_key().
117 === 4.0.5 ===
119 1) Question bank plugins can now define more than one bulk action. Therefore, plugin_features_base::get_bulk_actions has been
120    changed to return an array, rather than a single bulk action class. Please update the plugin_features class in your plugin if necessary.
122 === 4.0 ===
124 Moodle 4.0 included the results of a major project to re-work the question bank.
126 1) Database changes (as usual, all existing data is updated automatically).
127    * Previously there was a single {question} table. This has now been split into three to handle versionning questions:
128      - question              - This now has a row for each version of each question. Therefore, some of the metadata
129                                (e.g. category) is moved to the next table. However, data that defines how a question works
130                                is unchanged, so question type plugins will mostly keep working.
131      - question_bank_entries - Each question bank entry is a question that appears in the question bank, which can
132                                have many versions.
133      - question_versions     - This joins all the versions of a question in the {question} table to the
134                                {question_bank_entries} row they belong to.
135    * Also, how other parts of the code refer to questions they want to to has changed, to be managed by the core
136      API in two new tables.
137       - question_references -> Records where a specific question is used.
138       - question_set_references -> Records where groups of questions are used (for example random questions in quizzes).
139      As a result of this, data from the two quiz tables {quiz_slot} and {quiz_slot_tags} was moved to these new tables.
141 2) There is a new plugin type 'qbank' for adding features to the question bank. See question/bank/upgrade.txt.
143 3) Many previously core features have been moved into new plugins, meaning that many old functionsand classes in
144    lib/questionlib.php and other locations have been deprecated and moved:
145     * Moved to qbank_previewquestion:
146        - question_preview_url() is moved to qbank_previewquestion\helper::question_preview_url()
147        - question_preview_popup_params() is moved to qbank_previewquestion\helper::question_preview_popup_params()
148       the following were really part of the internal implementation of preview, so should not have been used elsewhere,
149       but they were also moved (from previewlib.php).
150        - restart_preview() => qbank_previewquestion\helper::restart_preview(),
151        - question_preview_form_url() => qbank_previewquestion\helper::question_preview_form_url(),
152        - question_preview_action_url() => qbank_previewquestion\helper::question_preview_action_url(),
153        - question_preview_question_pluginfile() => qbank_previewquestion\helper::question_preview_question_pluginfile(),
154        - class preview_options_form => 'qbank_previewquestion\form\preview_options_form',
155        - class question_preview_options => 'qbank_previewquestion\output\question_preview_options',
156     * Moved to qbank_managecategories:
157        - qbank_managecategories\helper::question_remove_stale_questions_from_category()
158        - flatten_category_tree() => qbank_managecategories\helper::flatten_category_tree()
159        - add_indented_names() => qbank_managecategories\helper::add_indented_names()
160        - question_category_select_menu() => qbank_managecategories\helper::question_category_select_menu()
161        - get_categories_for_contexts() => qbank_managecategories\helper::get_categories_for_contexts()
162        - question_category_options() => qbank_managecategories\helper::question_category_options()
163        - question_add_context_in_key() => qbank_managecategories\helper::question_add_context_in_key()
164        - question_fix_top_names() => qbank_managecategories\helper::question_fix_top_names()
165        - class category_form => qbank_managecategories\form\category_form
166        - class question_category_list => qbank_managecategories\question_category_list
167        - class question_category_list_item => 'bank_managecategories\question_category_list_item
168        - class question_category_object => qbank_managecategories\question_category_object
169        - class question_category_edit_form => qbank_managecategories\form\category_form
170        - class question_move_form => qbank_managecategories\form\question_move_form
171     * Moved to qbank_exporttoxml:
172        - question_get_export_single_question_url() -> qbank_exporttoxml\helper::question_get_export_single_question_url().
173     * Moved to qbank_exportquestions:
174        - class question_export_form => qbank_exportquestions\form\export_form
175        - class export_form => qbank_exportquestions\form\export_form
176     * Moved to qbank_importquestions:
177        - class question_import_form => qbank_importquestions\form\question_import_form
178     * Moved to qbank_tagquestion:
179        - submit_tags_form and associated external services for question tag,
180        - tags_form in question/type,
181        - core_question_output_fragment_tags_form() => /question/bank/qbank_tagquestion/lib.php.
183 4) The following functions in questionlib.php now using type hinting. So, if you call them with the wrong types,
184    you will now get fatal errors.
185     - is_latest()
186     - get_next_version()
187     - get_question_version()
188     - get_question_bank_entry()
189     - core_question_find_next_unused_idnumber()
190     - question_module_uses_questions()
191     - question_page_type_list()
192     - core_question_question_preview_pluginfile()
193     - question_rewrite_question_preview_urls()
194     - question_rewrite_question_urls()
195     - question_get_all_capabilities()
196     - question_get_question_capabilities()
197     - question_require_capability_on()
198     - question_has_capability_on()
199     - question_default_export_filename()
200     - get_import_export_formats()
201     - question_categorylist_parents()
202     - question_categorylist()
203     - question_make_default_categories()
204     - question_get_top_categories_for_contexts()
205     - sort_categories_by_tree()
206     - print_question_icon()
207     - question_sort_tags()
208     - _tidy_question()
209     - question_preload_questions()
210     - question_move_category_to_context()
211     - move_question_set_references()
212     - question_move_questions_to_category()
213     - idnumber_exist_in_question_category()
214     - question_move_question_tags_to_new_context()
215     - question_delete_activity()
216     - question_delete_course_category()
217     - question_delete_course()
218     - question_delete_context()
219     - question_delete_question()
220     - delete_question_bank_entry()
221     - question_category_in_use()
222     - question_category_delete_safe()
223     - question_context_has_any_questions()
224     - questions_in_use()
225     - question_save_qtype_order()
226     - question_reorder_qtypes()
228 5) Function question_hash() from questionlib.php is deprecated without replacement.
230 6) The following classes have been moved, to better follow Moodle's name-space usage rules:
231    'core_question\bank\action_column_base' => 'core_question\local\bank\action_column_base',
232    'core_question\bank\checkbox_column' => 'core_question\local\bank\checkbox_column',
233    'core_question\bank\column_base' => 'core_question\local\bank\column_base',
234    'core_question\bank\edit_menu_column' => 'core_question\local\bank\edit_menu_column',
235    'core_question\bank\menu_action_column_base' => 'core_question\local\bank\menu_action_column_base',
236    'core_question\bank\menuable_action' => 'core_question\local\bank\menuable_action',
237    'core_question\bank\random_question_loader' => 'core_question\local\bank\random_question_loader',
238    'core_question\bank\row_base' => 'core_question\local\bank\row_base',
239    'core_question\bank\view' => 'core_question\local\bank\view',
240    'core_question\bank\copy_action_column' => 'qbank_editquestion\copy_action_column',
241    'core_question\bank\edit_action_column' => 'qbank_editquestion\edit_action_column',
242    'core_question\bank\creator_name_column' => 'qbank_viewcreator\creator_name_column',
243    'core_question\bank\question_name_column' => 'qbank_viewquestionname\viewquestionname_column_helper',
244    'core_question\bank\question_name_idnumber_tags_column' => 'qbank_viewquestionname\question_name_idnumber_tags_column',
245    'core_question\bank\delete_action_column' => 'qbank_deletequestion\delete_action_column',
246    'core_question\bank\export_xml_action_column' => 'qbank_exporttoxml\export_xml_action_column',
247    'core_question\bank\preview_action_column' => 'qbank_previewquestion\preview_action_column',
248    'core_question\bank\question_text_row' => 'qbank_viewquestiontext\question_text_row',
249    'core_question\bank\question_type_column' => 'qbank_viewquestiontype\question_type_column',
250    'core_question\bank\tags_action_column' => 'qbank_tagquestion\tags_action_column',
251    'core_question\form\tags' => '\qbank_tagquestion\form\tags_form',
252    'core_question\output\qbank_chooser' => 'qbank_editquestion\qbank_chooser',
253    'core_question\output\qbank_chooser_item' => 'qbank_editquestion\qbank_chooser_item',
255 7) The Behat class for question-related steps has been renamed to behat_core_question
256     to match the expected naming convention. In the unlikely event that you are directly
257     referring to the behat_question class name (nothing in the standard Moodle code was)
258     then you will have to update your reference.
261 === 3.9 ===
263 1) For years, the ..._questions_in_use callback has been the right way for plugins to
264    tell the core question system if questions are required. Previously this callback
265    only worked in mods. Now it works in all plugins.
267    At the same time, if you are still relying on the legacy ..._question_list_instances
268    callback for this, you will now get a debugging warning telling you to upgrade.
270 2) Previously, the functions question_delete_activity, question_delete_course and
271    question_delete_course_category would echo output. This was not correct behaviour for
272    a low-level API function. Now, they no longer output. Related to this, the helper
273    function they use, question_delete_context, now always returns an empty array.
275    This probably won't acutally cause you any problems. However, you may previously
276    have had to add expectOutputRegex calls to your unit tests to avoid warnings about
277    risky tests. If you have done that, those tests will now fail until you delete that expectation.
280 === 3.8 ===
282 If you have customised the display of the question bank (using $CFG->questionbankcolumns)
283 then be aware that the default configuration has changed, and you may wish to make
284 equivalent changes in your customised version. The old column question_name_column
285 has been replaced by question_name_idnumber_tags_column. The old question_name_column
286 still exists, so it is safe to continue using it.
288 There is a new question bank column edit_menu_column which displays all actions
289 in a drop-down menu, instead of as separate icons. This is now used by default.
290 Specifically, it gathers all other columns which implement the new interface
291 menuable_action. If you have made a custom subclasses of action_column_base,
292 you probably want to implement the new interface. If your column is a simple action,
293 the easiest way to do this will be to subclass menu_action_column_base. If your action
294 is more complex, and does not follow the simple pattern that menu_action_column_base
295 uses, then you will need to implement menuable_action yourself. The commit for
296 MDL-66816 updates all the core action columns. Looking at that change should make
297 it clearly the changes you need to make to your columns.
300 === 3.7 ===
302 The code for the is_valid_number function that was duplicated in the
303 qtype_numerical and qtype_multianswer plugins in the qtype_numerical_edit_form
304 and qtype_multianswer_edit_form classes has been moved to a static function
305 in the qtype_numerical class of the qtype_numerical plugin.
307 The exportprocess function of the qformat_default class doesn't output a blank line
308 if the result of the writequestion function is null. This permit to qformat plugins
309 to ignore some questions without the need to overwrite this function.
311 * The question_preview_cron() has been deleted. Please use \core\task\question_cron_task::execute().
312 * The question_usage_statistics_cron() has been deleted. Please use \core\task\question_cron_task::execute().
313 * The method question_bank::cron() has been deleted, please use question related scheduled tasks.
315 === 3.5 ===
317 1) The question format exportprocess function now adds a
318    $checkcapabilities boolean to allow questions to be exported in
319    certain circumstances.
321 === 3.2 ===
323 1) The following renderers have been deprecated in favour of the renderable
324    core_question\output\qbank_chooser and associated render_* method.
325     * qbank_chooser
326     * qbank_chooser_types
327     * qbank_chooser_qtype
328     * qbank_chooser_title
330 === 3.1 ===
332 1) The argument $requirecourseid was removed from question_edit_setup() and
333    is no longer respected. The behaviour was found to be buggy and now throws
334    debugging notices if passed.
336 === 2.9 ===
338 1) Some functions in questionlib.php which were deprecated in the past have now
339    been deleted:
341    Deprecated since 2.1
342     * question_list_instances
343     * get_grade_options
344     * question_category_isused
345     * save_question_options
346     * question_get_real_state
348    Deprecated since 2.6
349     * question_rewrite_questiontext_preview_urls
350     * question_send_questiontext_file
351     * question_pluginfile no longer falls back to using the old
352       {$previewcomponent}_questiontext_preview_pluginfile callback if the new
353       {$previewcomponent}_question_preview_pluginfile callback is missing.
356 === 2.8 ===
358 1) This is just a warning that some methods of the question_engine_data_mapper
359    class have changed. All these methods are ones that you should not have been
360    calling directly from your code, so this should not cause any problems.
361    The changed methods are:
362     * insert_question_attempt
363     * insert_step_data
364     * update_question_attempt_step
367 === 2.7 ===
369 1)  Changes to class question_bank_view:
371     Filters, including $recurse and $showhidden, are now implemented as
372     pluggable \core_question\bank\search\condition classes.
374     Therefore $recurse and $showhidden are no longer passed to the following functions:
375         protected function display_options [deprecated, use display_options_form()]
376         protected function build_query_sql [deprecated, use build_query()]
378     protected function display_category_form() is deprecated. Use \core_question\bank\search\category_condition
380     protected function display_category_form_checkbox deprecated use html_writer::checkbox and separate JavaScript
382 To add filters, local plugins can now implement the function local_[pluginname]_get_question_bank_search_conditions,
384 2) To make columns available to question_bank_view, plugins can extend core_question\bank\column_base.
385    Users may choose to display additional columns by setting $CFG->questionbankcolumns to a comma-delimited list of columns.
387 3) The subsort separator has changed from _ to - in order to distinuguish subsorts vs frankenstyle component separators.
389 4) Because of the move to autoloading, $knowncolumntypes and known_field_types() are no longer used.
391 5) question_bank_column_base and it's derived classes have been namespaced to core_question\bank\column_base.
394 === 2.6 ===
396 1) Modules using the question bank MUST now declare their use of it with the xxx_supports()
397    flag FEATURE_USES_QUESTIONS. question_module_uses_questions() should be used to determine
398    if a module uses questions.
400 2) It is sometimes necessary to display bits of question content without having
401    and attempt (question_usage) in progress. Two examples of this are the option
402    in the question bank to display the questiontext, and in the quiz statistics
403    report, where it displays the question text above the report.
405    Previously, this display was done using a special method that only worked for
406    the question text, but which would not work for other parts of the question.
407    That old mechanism has been deprecated, and there is a new method that you
408    should use.
410    To display the question, replace calls to question_rewrite_questiontext_preview_urls
411    with calls to question_rewrite_question_preview_urls. Because the new function
412    is more flexibile, you have to pass more arguments.
414    To perform the necessary permission checks when the file is downloaded, you need
415    to implement the callback [component name]_question_preview_pluginfile.
416    (Previously you implemented [component name]_questiontext_preview_pluginfile.)
417    quiz_statistics_question_preview_pluginfile is an example of what to do.
419    question_send_questiontext_file has been deprecated. It is no longer necessary.
421    To ensure you are no longer using or defining any deprecated functions,
422    search for the regular expression:
423    question_rewrite_questiontext_preview_urls|_questiontext_preview_pluginfile|question_send_questiontext_file
425 3) The argument list for core_question_renderer::mark_summary has changed.
426    Please update your calls. (The most likely scenario for this is if you have
427    overridden core_question_renderer::info in your own renderer.) You need to
428    make a change like:
429    - $this->mark_summary($qa, $options);
430    + $this->mark_summary($qa, $behaviouroutput, $options);