fixup! Add question bank filter API guide

Re-word and re-order sections to make it clearer which parts are
compulsory and which are optional.

Author: marxjohnson

docs/apis/plugintypes/qbank/filters.md

@@ -30,9 +30,10 @@ By default this will use the `core/datafilter/filtertype` "filter" class, althou
 
 ### Basic example
 
-This outlines the bare minimum required to implement a new filter condition. This will allow you to filter based on a pre-defined
-list of values, selected from an autocomplete field. This assumes that you already have the basic framework of a qbank
-plugin in place. For real-world examples, look for classes that extend `core_question\local\bank\condition`.
+This outlines the bare minimum required to implement a new filter condition. This will give you a field that allows you to
+enter keywords and add them to a list of selected search terms, the filter the questions by that list of terms.
+This assumes that you already have the basic framework of a qbank plugin in place. For real-world examples,
+look for classes that extend `core_question\local\bank\condition`.
 
 Create a `condition` class within your plugin's namespace. For a plugin called `qbank_myplugin` this would look something like:
 
@@ -63,32 +64,6 @@ public function get_condition_key(): string {
 }
 ```
 
-To define the list of possible filter values, define `get_initial_values()`, which returns an array of `['value', 'title']` for each
-option.
-
-```php title=question/bank/myplugin/classes/myfilter_condition.php
-public function get_initial_values(): string {
-    return [
-        [
-            'value' => 0,
-            'title' => 'Option 1',
-        ],
-        [
-            'value' => 1,
-            'title' => 'Option 2',
-        ]
-    ];
-}
-```
-
-To prevent additional values being added by typing them into the autocomplete, define `allow_custom()` and have it return `false`.
-
-```php title=question/bank/myplugin/classes/myfilter_condition.php
-public function allow_custom(): bool {
-    return false;
-}
-```
-
 To actually filter the results, define `build_query_from_filter()` which returns an SQL `WHERE` condition, and an array of parameters.
 The `$filter` parameter receives an array with a `'values'` key, containing an array of the selected values, and a `'jointype'` key,
 containing one of the `JOINTTYPE_ANY`, `JOINTYPE_ALL` or `JOINTYPE_NONE` constants. Use these to build your condition as required.
@@ -121,39 +96,47 @@ more complex functionality, which can be achieved through additional methods.
 
 ### Additional options
 
-#### Restrict join types
+#### Pre-defined values
 
-Not all join types are relevant to all filters. If each question will only match one of the selected values, it does not make
-sense to allow JOINTYPE_ALL. Define `get_join_list()` and return an array of the applicable jointypes.
+To define the list of possible filter values, define `get_initial_values()`, which returns an array of `['value', 'title']` for each
+option. These will then be searchable and selectable in the autocomplete field.
 
 ```php title=question/bank/myplugin/classes/myfilter_condition.php
-public function get_join_list(): array {
+public function get_initial_values(): string {
     return [
-        datafilter::JOINTYPE_ANY,
-        datafilter::JOINTYPE_NONE,
+        [
+            'value' => 0,
+            'title' => 'Option 1',
+        ],
+        [
+            'value' => 1,
+            'title' => 'Option 2',
+        ]
     ];
 }
 ```
 
-#### Custom filter class
+#### Restrict custom keywords
 
-By default, the filter will be displayed and processed using the `core/datafilter/filtertype` JavaScript class.
-This will provide a single autocomplete field for selecting one or multiple numeric IDs with textual labels.
-If this does not fit your filter's use case, you will need to define your own filter class.
+To restrict the possible filter terms to only those returned from `get_initial_values()`, define `allow_custom()` and have it return `false`.
 
-Create a new JavaScript file in your plugin under `amd/src/datafilter/filtertypes/myfilter.js`.
-In this file, export a default class that extends `core/datafilter/filtertype`
-(or another core filter type from '/lib/amd/src/datafilter/filtertypes') and override the base methods as required.
-For example, if your filter uses textual rather than numeric values, you can override `get values()` to return the raw values
-without running `parseInt()` (see `types` filter). If you want a different UI for selecting your filter values instead of a
-single autocomplete, you can override `addValueSelector()`.
+```php title=question/bank/myplugin/classes/myfilter_condition.php
+public function allow_custom(): bool {
+    return false;
+}
+```
 
-To tell your filter condition to use a custom filter class, override the `get_filter_class()` method to return the namespaced
-path to your JavaScript class.
+#### Restrict join types
+
+Not all join types are relevant to all filters. If each question will only match one of the selected values, it does not make
+sense to allow JOINTYPE_ALL. Define `get_join_list()` and return an array of the applicable jointypes.
 
 ```php title=question/bank/myplugin/classes/myfilter_condition.php
-public function get_filter_class(): string {
-    return 'qbank_myplugin/datafilter/filtertype/myfilter';
+public function get_join_list(): array {
+    return [
+        datafilter::JOINTYPE_ANY,
+        datafilter::JOINTYPE_NONE,
+    ];
 }
 ```
 
@@ -189,6 +172,33 @@ public function is_required(): bool {
 }
 ```
 
+#### Custom filter class
+
+By default, the filter will be displayed and processed using the `core/datafilter/filtertype` JavaScript class.
+This will provide a single autocomplete field for selecting one or multiple numeric IDs with textual labels.
+If this does not fit your filter's use case, you can tell your condition to use a different filter class.
+
+You can either use a different core filter type from `/lib/amd/src/datafilter/filtertypes`, or define your own.
+
+To tell your filter condition to use a different filter class, override the `get_filter_class()` method to return the namespaced
+path to your JavaScript class.
+
+```php title=question/bank/myplugin/classes/myfilter_condition.php
+public function get_filter_class(): string {
+    return 'qbank_myplugin/datafilter/filtertype/myfilter';
+}
+```
+
+To create your own filter class, a new JavaScript file in your plugin under `amd/src/datafilter/filtertypes/myfilter.js`.
+In this file, export a default class that extends `core/datafilter/filtertype`
+(or another core filter type from `/lib/amd/src/datafilter/filtertypes`) and override the base methods as required.
+For example, if your filter uses textual rather than numeric values, you can override `get values()` to return the raw values
+without running `parseInt()` (see
+[`qbank_viewquestiontype/datafilter/filtertypes/type`](https://github.com/moodle/moodle/blob/main/mod/quiz/tests/behat/editing_add_from_question_bank.feature)).
+
+If you want a different UI for selecting your filter values instead of a single autocomplete, you can override `addValueSelector()`.
+This also provides flexibility over how the values provided by `get_initial_values()` are used by the UI.
+
 #### Filter options
 
 If your condition supports additional options as to how the selected values are applied to the query, such as whether child
@@ -202,7 +212,8 @@ as an example.
 
 You JavaScript filter class will also need to support your filter options. Override the constructor an add additional code
 for the UI required to set your filter options, and override `get filterOptions()` to return the current value for any options set
-in this UI. See [`qbank_managecategories/datafilter/filtertypes/categories`](https://github.com/moodle/moodle/blob/main/question/bank/managecategories/amd/src/datafilter/filtertypes/categories.js
+in this UI. See
+[`qbank_managecategories/datafilter/filtertypes/categories`](https://github.com/moodle/moodle/blob/main/question/bank/managecategories/amd/src/datafilter/filtertypes/categories.js)
 as an example.
 
 #### Context-sensitive configuration