question/type/upgrade.txt

   1 This files describes API changes for question type plugins.
   2
   3 === 4.0.2, 4.1 ===
   4
   5 * There was one issue caused by the changes in Moodle 4.0 which requires changes in question types,
   6   and that is regrading. There are two new methods which some question types will need to implement,
   7    - validate_can_regrade_with_other_version
   8    - update_attempt_state_data_for_new_version
   9   these methods are introduced in this commit, and there are details PHPdoc comments about what they
  10   must do. Then the immediately following commits implement them in the core question types where
  11   they are required.
  12   Generally, you will need to implement one or both of these if you question type does something
  13   significant in the apply_attempt_state method. If you have not implemented that method, then
  14   almost certainly you don't need to worry about this.
  15
  16
  17 === 4.0 ===
  18
  19 * The major question bank changes should not affect most basic question type plugins.
  20   The navigation changes may affect Behat tests. If you encounter this,
  21   the best way to fix it is to use the new navigation steps in MDL-74130.
  22
  23 * The qualification 'most' is because some question types do more complex things, which
  24   will require changes related to question versionning. Some examples that come to mind:
  25    - the way qtype_mulitanswer (or qtype_combined) aggregates several sub-questions into a parent question.
  26    - the way some contrib plugins (e.g. qtype_stack, qtype_pmatch) store additional data (question tests)
  27      linked to questions. That relationship will need to be updated.
  28
  29
  30 === 3.11 ===
  31
  32 * Introducing the following \question_type base class methods to save/fetch the last form values
  33   that were used when creating questions as the new defaults when creating new questions:
  34   - \question_type::get_default_value()
  35     - Fetches the default value for a given question field from the user preference.
  36       Question type plugins can use this in edit_{qtypename}_form.php when using $mform->setDefault().
  37   - \question_type::set_default_value()
  38     - Saves the default value for a given question form field in the user preferences.
  39   - \question_type::save_defaults_for_new_questions()
  40     - Saves the question type plugin's defined form defaults into the user preferences.
  41       It calls \question_type::set_default_value() to save each form field default value
  42       into the user preferences.
  43     - Question type plugins using \question_type::get_default_value() for their form fields must implement
  44       this in order to save the values from these form fields as defaults for new questions.
  45
  46   This will help teachers who repeatedly create questions and use the same values for the fields
  47   (e.g. Default mark, Penalty for each incorrect try, etc.) in the question edit form.
  48
  49
  50 === 3.8 ===
  51
  52 * There is a new method for question types get_extra_question_bank_actions.
  53   Assuming the question bank display is using the new 'edit_menu_column'
  54   (which it will be by default) this method lets you add question-type-specific
  55   actions to the menu. The question_type base class has extensive PHPdoc comments
  56   on the method to explain what you should do, and there is an example of how to
  57   use it in a question type at
  58   https://github.com/moodleou/moodle-qtype_pmatch/commit/2aefa8b5dcc7bab768f4707a4ffb7befcf4c2540.
  59
  60
  61 === 3.8, 3.7.3, 3.6.7 ===
  62
  63 * Coming up in Moodle 3.8 are some changes to the question bank UI. These will break any
  64   Behat automated tests which use the common pattern
  65     When I click on "Duplicate" "link" in the "Test question" "table_row"
  66   to trigger actions on questions when looking at the question bank screen. Therefore,
  67   a new step has been introduced:
  68     When I choose "Duplicate" action for "Test question" in the question bank
  69   If you want your Behat tests to continue working with Moodle 3.8, you will need to use
  70   the new step. The new step has been back-ported, so you can start updating your tests
  71   and have them work with Moodle 3.6 and 3.7. In addition, if you want to trigger the
  72   "Edit" action, you should change that to "Edit question".
  73
  74
  75 === 3.5 ===
  76
  77   + Added new classes backup_qtype_extrafields_plugin and restore_qtype_extrafields_plugin
  78    in order to use extra fields method in backup/restore question type. Require and inherit new classes for using it. See
  79    backup_qtype_shortanswer_plugin and restore_qtype_shortanswer_plugin for an example of using this.
  80   + The declaration of is_gradable_response has been moved from question_automatically_gradable to
  81    question_manually_gradable.
  82   + The default implementation of is_gradable_response has been moved from question_graded_automatically to
  83    question_with_responses.
  84   + Note that format_text() is no longer applied to the results of
  85    qtype_elements_embedded_in_question_text_renderer::embedded_element(). If question type overrides
  86    this method make sure you apply format_text() to any text that came from a user.
  87
  88 === 3.1.5, 3.2.2, 3.3 ===
  89
  90 * If you are using check_combined_feedback_file_access in your check_file_access method,
  91   then you must now pass $args as the 4th argument, so the correct permission checks
  92   can be performed. If you don't, you will get a developer debug notice.
  93
  94 === 3.1 ===
  95
  96 * The following functions, previously used (exclusively) by upgrade steps are not available
  97   anymore because of the upgrade cleanup performed for this version. See MDL-51580 for more info:
  98     - qtype_essay_convert_to_html()
  99
 100 === 2.7 ===
 101   + We have added a new method to the question_type base class 'break_down_stats_and_response_analysis_by_variant'. By default it
 102    returns true. If your question type does not have variants of question instances then you can ignore this method as it only
 103    applies to question types that have variants. If a question type does have variants the default action is to break down
 104    response analysis and question stats by variant. But for some question types there might be an almost infinite quantity of
 105    variants for the question, in this case you can suppress break down by variant by returning false from this method. See for
 106    example the non-core question type varnumeric or the slightly more complex stack question type.
 107   + We have added a pair of methods to the question_definition class 'prepare_simulated_post_data' and
 108   'get_student_response_values_for_simulation'. You may want to override these methods in question.php in your question type plug
 109    -in. These methods are used to convert data from a csv file of simulated step data into the simulated post data that is fed
 110    to the question engine. These csv files can be used for unit testing or manual testing the use of your question type within the
 111    quiz module.  You  can use the simulate quiz report for manual testing and also to easily generate csv test files. You can
 112    run a number of students through a test and then download a csv file representing their interaction with the quiz. For most
 113    question types the default of just passing csv data as post data, directly from the csv file will probably work fine. But for
 114    certain question types where the meaning of the post data is deliberately obfuscated it might be necessary to convert from a
 115    human friendly format in the csv file to response data expected by the question type using 'prepare_simulated_post_data' and
 116    to convert back from a question type response array to values for download in a csv file using
 117    'get_student_response_values_for_simulation'.
 118 === 2.6 ===
 119   + The changes in MDL-32750 were reverted in favour of the new pdw toggle toolbars
 120     plugin for TinyMCE. The get_non_collapsible_editor_options method has been deprecated.
 121
 122 === 2.5 ===
 123
 124 * There have been some tweaks to the helper class that is used to write
 125   walkthrough tests. You should not have to change your code, but you might
 126   like to take a look at some of the new helper methods available. In particular,
 127   if you had any code that did
 128   $this->process_submission(array('-finish' => 1));
 129   you should change that to
 130   $this->finish();
 131
 132 * There have been lots of usability improvements to the question editing forms.
 133   MDL-37417 links to all the changes. There are only a few API changes that
 134   *require* you to upgrade your question type, but you are strongly recommended
 135   to make similar usability improvements in your own question types.
 136
 137   + Some of the ids used in the form HTML have had ‘id_’ added at the front.
 138     Take care if you refer to these in your JavasSript or CSS.
 139
 140   + MDL-32750 The HTML editing tools are now collapsed. This is applied by default
 141     to all HTML editors except question text and general feedback. If you want to
 142     add more exceptions, see the get_non_collabsible_editor_options method.
 143
 144   + Form fields have been grouped onto one line where appropriate, to reduce
 145     the height of the form. qtype_numerical is a good example of this.
 146
 147   + Where elements are in groups, we have changed the normal accesshide CSS, so
 148     that their labels are visible. If you were using grouped elements in the past
 149     with static elements to lable the fields, then you will need to remove the statics.
 150
 151   + All the choices / answers have been merged into a single section of the form.
 152     This works better with the new 'shortforms' MDL-30637. Also the
 153     "Add blanks for more ..." buttons are now inside that section. This probably
 154     requries that you remove any headings from your per-answer fields, and change
 155     some of the labels.
 156
 157   + Having merged all the elements into one form section, we then used CSS to
 158     visually group the fields for one choice, answer, etc.
 159
 160   + When editing an existing question, we only show as many repeats are are
 161     actually needed until the user clicks the "Add blanks for more ..." button.
 162     Where you have your own repeat elements, you may need to change the
 163     number of repeats calculation.
 164
 165   + As with all forms, setType() is now required for all text form elements.
 166
 167   + A good example of a question type being upgraded to take account of all these
 168     changes is
 169     https://github.com/moodleou/moodle-qtype_pmatch/commit/9d8e1beb9f780246416a0f3a7622f700b8fa90c8
 170
 171
 172 === 2.3.5 / 2.4.2 / 2.5 ===
 173
 174 * The special value question_attempt::PARAM_CLEANHTML_FILES that could be used
 175   in the get_expected_data method was renamed to question_attempt::PARAM_RAW_FILES
 176   in order to fix a bug. We failed to think this throught, and so did not realised
 177   that this might break some question types. If this affected your question type,
 178   please accept our apologies. Details in MDL-37847.
 179
 180
 181 === 2.3 ===
 182
 183 * Support for backwards-compatible string names dropped. MDL-30120. (See under 2.2 below.)
 184 * If you are overriding export_to_xml and import_from_xml to provide Moodle XML format
 185   import and export, then you will probably get PHP strict syntax notices in developer
 186   debug mode until you change the method signature to include qformat_xml $format.
 187   That is, you need to specify the argument type.
 188 * qtype_xxx_pluginfile() is now given the 7th parameter (hopefully the last
 189   one) that contains additional options for the file serving. The array should
 190   be re-passed to question_pluginfile() as is.
 191
 192
 193 === 2.2 ===
 194
 195 * The XML import/export base class has had some minor API changes. The
 196   - write_combined_feedback method now requires that you pass the questionid and
 197     contextid. (MDL-29058)
 198   - calls to the import_hints and import_answer methods now should pass the question
 199     text format as the last argument, to be used as a default if necessary. (MDL-29739)
 200   If you do not upgrade your code, it will not break, but there will be PHP
 201   warnings, and it the export will not work 100% correctly.
 202
 203 * The old
 204     public function requires_qtypes()
 205 method is no more. Instead use the ->dependencies facility in version.php. E.g.
 206 $plugin->dependencies = array(
 207     'qtype_numerical' => 2011102700,
 208 );
 209
 210 * The plugin name and related strings used to be defined in language strings
 211 called the same thing as the format, for example:
 212
 213 $string['addingdescription'] = 'Adding a Description';
 214 $string['description'] = 'Description';
 215 $string['description_help'] = 'A description is not really a question type. It simply enables text to be displayed without requiring any answers, similar to a label on the course page.
 216 $string['description_link'] = 'A description is not really a question type. It simply enables text to be displayed without requiring any answers, similar to a label on the course page.
 217 $string['descriptionsummary'] = 'This is not actually a question. Instead it is a way to add some instructions, rubric or other content to the activity. This is similar to the way that labels can be used to add content to the course page.';
 218 $string['editingdescription'] = 'Editing a Description';
 219
 220 All these need to be changed to use the standard string name pluginname, as for
 221 other plugin types, and similar for the other strings.
 222
 223 $string['pluginname'] = 'Description';
 224 $string['pluginname_help'] = 'A description is not really a question type. It simply enables text to be displayed without requiring any answers, similar to a label on the course page.
 225 $string['pluginname_link'] = 'A description is not really a question type. It simply enables text to be displayed without requiring any answers, similar to a label on the course page.
 226 $string['pluginnameadding'] = 'Adding a Description';
 227 $string['pluginnameediting'] = 'Editing a Description';
 228 $string['pluginnamesummary'] = 'This is not actually a question. Instead it is a way to add some instructions, rubric or other content to the activity. This is similar to the way that labels can be used to add content to the course page.';
 229
 230 The old strings will continue to work, but only until Moodle 2.3 is released.
 231
 232 * If you are using the facilities provided by overriding the extra_answer_fields
 233   or questionid_column_name methods, then you must change these to be public
 234   methods. (This is required so that backup and restore can be made to work
 235   automatically. MDL-24408, MDL-25617, MDL-30562)
 236
 237
 238 === 2.1 ===
 239
 240 * Lots of API changes due to the new question engine. See
 241 http://docs.moodle.org/dev/Developing_a_Question_Type#Converting_a_Moodle_2.0_question_type
 242
 243
 244 === 2.0 ===
 245
 246 * Lots of changes due to all the API changes in Moodle 2.0.
 247
 248 * This plugin type now supports cron in the standard way. If required, Create a
 249   lib.php file containing
 250 function qtype_mypluginname_cron() {};