From 03953e528450149359f0073b19cbcd15aa59189f Mon Sep 17 00:00:00 2001
From: Neill Magill <neill.magill@nottingham.ac.uk>
Date: Wed, 21 Aug 2024 10:09:35 +0100
Subject: [PATCH 1/2] [docs] Document named_templates

We probably want to let people know about named templates and the ability
to save on writing some boiler plate code when using templates in the Output API

Much of this seems to apply to all versions of Moodle supported by the developer docs
---
 docs/apis/subsystems/output/index.md          | 33 ++++++++++++++++---
 docs/guides/templates/index.md                | 18 +++++++++-
 .../version-4.1/guides/templates/index.md     | 18 +++++++++-
 .../apis/subsystems/output/index.md           | 33 ++++++++++++++++---
 .../version-4.3/guides/templates/index.md     | 18 +++++++++-
 .../apis/subsystems/output/index.md           | 33 ++++++++++++++++---
 .../version-4.4/guides/templates/index.md     | 18 +++++++++-
 .../apis/subsystems/output/index.md           | 33 ++++++++++++++++---
 .../version-4.5/guides/templates/index.md     | 18 +++++++++-
 9 files changed, 201 insertions(+), 21 deletions(-)

diff --git a/docs/apis/subsystems/output/index.md b/docs/apis/subsystems/output/index.md
index a9becaa651..f912bab1de 100644
--- a/docs/apis/subsystems/output/index.md
+++ b/docs/apis/subsystems/output/index.md
@@ -116,9 +116,9 @@ In the code above, we created a renderable. This is a class that you have to add
 
 namespace tool_demo\output;
 
-use renderable
-use renderer_base
-use templatable
+use renderable;
+use renderer_base;
+use templatable;
 use stdClass;
 
 class index_page implements renderable, templatable {
@@ -142,7 +142,25 @@ class index_page implements renderable, templatable {
 }
 ```
 
-This class implements the renderable interface, which has no methods, and the templatable interface, which means that this class could be rendered with a template, so it must implement the `export_for_template` method. So in this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else fancy with the data in this example (but it could). Note that the `export_for_template` function should only return simple types (arrays, stdClass, bool, int, float, string).
+This class implements the:
+
+- `renderable` interface, which has no methods
+- `templatable` interface, which means that this class could be rendered with a template, so it must implement the `export_for_template` method
+
+In this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else with the data in this example (but it could). Note that the `export_for_template` function should only return simple types (`arrays`, `stdClass`, `bool`, `int`, `float`, `string`), or those that implement the [`Stringable`](https://www.php.net/manual/en/class.stringable.php) interface.
+
+If you wish to use a specific template to render the content you may specify anyone by replacing `templatable` with `named_templatable`, which extends templatable and requires that you implement a `get_template_name()` method that returns the name of the template you wish to use.
+
+```php title="Example implementation of get_template_name()"
+    /**
+     * Gets the name of the mustache template used to render the data.
+     *
+     * @return string
+     */
+    public function get_template_name(\renderer_base $renderer): string {
+         return 'tool_demo/index_page';
+    }
+```
 
 Now let's look at the renderer for this plugin.
 
@@ -171,6 +189,13 @@ class renderer extends plugin_renderer_base {
 
 The renderer exists to provide `render_<page>` methods for all renderables used in the plugin. A theme designer can provide a custom version of this renderer that changes the behaviour of any of the render methods and so to customize their theme. In this example, the render method for the index page (`render_index_page`) does 2 things. It asks the renderable to export it's data so that it is suitable for passing as the context to a template, and then renders a specific template with this context. A theme designer could either manipulate the data in the render method (e.g. removing menu entries), or change the template (change the generated HTML) to customize the output.
 
+You do not need to implement a renderer for a plugin if you are using templates and you either:
+
+1. Use the `templatable` interface and have a template with the same name in the same namespace
+2. Use the `named_templatable` interface
+
+In these cases the data from the renderable will be automatically routed to the correct template, however if you do implement a render method that will be used in preference to the default routing.
+
 The template used in this plugin is located in the plugin's templates folder. The template can also be overridden by a theme designer.
 
 ```xml title="admin/tool/demo/templates/index_page.mustache"
diff --git a/docs/guides/templates/index.md b/docs/guides/templates/index.md
index 85ddd48937..e83e4c2c7d 100644
--- a/docs/guides/templates/index.md
+++ b/docs/guides/templates/index.md
@@ -388,7 +388,7 @@ Templates can be effectively used in [renderers](https://docs.moodle.org/dev/Ren
 
 In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity. Passing your widget directly to `$OUTPUT->render()` will infer the name of your template, call `export_for_template()` and `render_from_template()`, then return the result.
 
-Example of the method added to the renderable `mywidget`:
+The following example shows a renderable using the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
 
 ```php
 /**
@@ -413,6 +413,22 @@ public function export_for_template(renderer_base $output) {
 }
 ```
 
+If you wish to render using any template your renderable can implement `named_templatable` interface instead of `templatable`. It will have to implement an additional new method `public function get_template_name(\renderer_base $renderer): string` that returns the name of the template to be used.
+
+Example of the method added to tell a renderable to use the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
+
+```php
+/**
+ * Get the name of the template to use for this templatable.
+ *
+ * @param renderer_base $output
+ * @return string
+ */
+public function get_template_name(\renderer_base $renderer): string {
+    return 'tool_myplugin/mywidget';
+}
+```
+
 :::tip
 
 When naming variables in your export data, be careful not to reuse names of helpers such as `str` or `js` - these will silently fail. Try to keep your variable names short but descriptive.
diff --git a/versioned_docs/version-4.1/guides/templates/index.md b/versioned_docs/version-4.1/guides/templates/index.md
index 814c686c31..c4615b30a0 100644
--- a/versioned_docs/version-4.1/guides/templates/index.md
+++ b/versioned_docs/version-4.1/guides/templates/index.md
@@ -388,7 +388,7 @@ Templates can be effectively used in [renderers](https://docs.moodle.org/dev/Ren
 
 In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity. Passing your widget directly to `$OUTPUT->render()` will infer the name of your template, call `export_for_template()` and `render_from_template()`, then return the result.
 
-Example of the method added to the renderable `mywidget`:
+The following example shows a renderable using the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
 
 ```php
 /**
@@ -413,6 +413,22 @@ public function export_for_template(renderer_base $output) {
 }
 ```
 
+If you wish to render using any template your renderable can implement `named_templatable` interface instead of `templatable`. It will have to implement an additional new method `public function get_template_name(\renderer_base $renderer): string` that returns the name of the template to be used.
+
+Example of the method added to tell a renderable to use the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
+
+```php
+/**
+ * Get the name of the template to use for this templatable.
+ *
+ * @param renderer_base $output
+ * @return string
+ */
+public function get_template_name(\renderer_base $renderer): string {
+    return 'tool_myplugin/mywidget';
+}
+```
+
 :::tip
 
 When naming variables in your export data, be careful not to reuse names of helpers such as `str` or `js` - these will silently fail. Try to keep your variable names short but descriptive.
diff --git a/versioned_docs/version-4.3/apis/subsystems/output/index.md b/versioned_docs/version-4.3/apis/subsystems/output/index.md
index ba5f13d08b..4bf1cb102e 100644
--- a/versioned_docs/version-4.3/apis/subsystems/output/index.md
+++ b/versioned_docs/version-4.3/apis/subsystems/output/index.md
@@ -116,9 +116,9 @@ In the code above, we created a renderable. This is a class that you have to add
 
 namespace tool_demo\output;
 
-use renderable
-use renderer_base
-use templatable
+use renderable;
+use renderer_base;
+use templatable;
 use stdClass;
 
 class index_page implements renderable, templatable {
@@ -142,7 +142,25 @@ class index_page implements renderable, templatable {
 }
 ```
 
-This class implements the renderable interface, which has no methods, and the templatable interface, which means that this class could be rendered with a template, so it must implement the `export_for_template` method. So in this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else fancy with the data in this example (but it could). Note that the `export_for_template` function should only return simple types (arrays, stdClass, bool, int, float, string).
+This class implements the:
+
+- `renderable` interface, which has no methods
+- `templatable` interface, which means that this class could be rendered with a template, so it must implement the `export_for_template` method
+
+In this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else with the data in this example (but it could). Note that the `export_for_template` function should only return simple types (`arrays`, `stdClass`, `bool`, `int`, `float`, `string`), or those that implement the [`Stringable`](https://www.php.net/manual/en/class.stringable.php) interface.
+
+If you wish to use a specific template to render the content you may specify anyone by replacing `templatable` with `named_templatable`, which extends templatable and requires that you implement a `get_template_name()` method that returns the name of the template you wish to use.
+
+```php title="Example implementation of get_template_name()"
+    /**
+     * Gets the name of the mustache template used to render the data.
+     *
+     * @return string
+     */
+    public function get_template_name(\renderer_base $renderer): string {
+         return 'tool_demo/index_page';
+    }
+```
 
 Now let's look at the renderer for this plugin.
 
@@ -171,6 +189,13 @@ class renderer extends plugin_renderer_base {
 
 The renderer exists to provide `render_<page>` methods for all renderables used in the plugin. A theme designer can provide a custom version of this renderer that changes the behaviour of any of the render methods and so to customize their theme. In this example, the render method for the index page (`render_index_page`) does 2 things. It asks the renderable to export it's data so that it is suitable for passing as the context to a template, and then renders a specific template with this context. A theme designer could either manipulate the data in the render method (e.g. removing menu entries), or change the template (change the generated HTML) to customize the output.
 
+You do not need to implement a renderer for a plugin if you are using templates and you either:
+
+1. Use the `templatable` interface and have a template with the same name in the same namespace
+2. Use the `named_templatable` interface
+
+In these cases the data from the renderable will be automatically routed to the correct template, however if you do implement a render method that will be used in preference to the default routing.
+
 The template used in this plugin is located in the plugin's templates folder. The template can also be overridden by a theme designer.
 
 ```xml title="admin/tool/demo/templates/index_page.mustache"
diff --git a/versioned_docs/version-4.3/guides/templates/index.md b/versioned_docs/version-4.3/guides/templates/index.md
index 85ddd48937..e83e4c2c7d 100644
--- a/versioned_docs/version-4.3/guides/templates/index.md
+++ b/versioned_docs/version-4.3/guides/templates/index.md
@@ -388,7 +388,7 @@ Templates can be effectively used in [renderers](https://docs.moodle.org/dev/Ren
 
 In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity. Passing your widget directly to `$OUTPUT->render()` will infer the name of your template, call `export_for_template()` and `render_from_template()`, then return the result.
 
-Example of the method added to the renderable `mywidget`:
+The following example shows a renderable using the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
 
 ```php
 /**
@@ -413,6 +413,22 @@ public function export_for_template(renderer_base $output) {
 }
 ```
 
+If you wish to render using any template your renderable can implement `named_templatable` interface instead of `templatable`. It will have to implement an additional new method `public function get_template_name(\renderer_base $renderer): string` that returns the name of the template to be used.
+
+Example of the method added to tell a renderable to use the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
+
+```php
+/**
+ * Get the name of the template to use for this templatable.
+ *
+ * @param renderer_base $output
+ * @return string
+ */
+public function get_template_name(\renderer_base $renderer): string {
+    return 'tool_myplugin/mywidget';
+}
+```
+
 :::tip
 
 When naming variables in your export data, be careful not to reuse names of helpers such as `str` or `js` - these will silently fail. Try to keep your variable names short but descriptive.
diff --git a/versioned_docs/version-4.4/apis/subsystems/output/index.md b/versioned_docs/version-4.4/apis/subsystems/output/index.md
index 2a4cc67850..a1879eb73e 100644
--- a/versioned_docs/version-4.4/apis/subsystems/output/index.md
+++ b/versioned_docs/version-4.4/apis/subsystems/output/index.md
@@ -116,9 +116,9 @@ In the code above, we created a renderable. This is a class that you have to add
 
 namespace tool_demo\output;
 
-use renderable
-use renderer_base
-use templatable
+use renderable;
+use renderer_base;
+use templatable;
 use stdClass;
 
 class index_page implements renderable, templatable {
@@ -142,7 +142,25 @@ class index_page implements renderable, templatable {
 }
 ```
 
-This class implements the renderable interface, which has no methods, and the templatable interface, which means that this class could be rendered with a template, so it must implement the `export_for_template` method. So in this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else fancy with the data in this example (but it could). Note that the `export_for_template` function should only return simple types (arrays, stdClass, bool, int, float, string).
+This class implements the:
+
+- `renderable` interface, which has no methods
+- `templatable` interface, which means that this class could be rendered with a template, so it must implement the `export_for_template` method
+
+In this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else with the data in this example (but it could). Note that the `export_for_template` function should only return simple types (`arrays`, `stdClass`, `bool`, `int`, `float`, `string`), or those that implement the [`Stringable`](https://www.php.net/manual/en/class.stringable.php) interface.
+
+If you wish to use a specific template to render the content you may specify anyone by replacing `templatable` with `named_templatable`, which extends templatable and requires that you implement a `get_template_name()` method that returns the name of the template you wish to use.
+
+```php title="Example implementation of get_template_name()"
+    /**
+     * Gets the name of the mustache template used to render the data.
+     *
+     * @return string
+     */
+    public function get_template_name(\renderer_base $renderer): string {
+         return 'tool_demo/index_page';
+    }
+```
 
 Now let's look at the renderer for this plugin.
 
@@ -171,6 +189,13 @@ class renderer extends plugin_renderer_base {
 
 The renderer exists to provide `render_<page>` methods for all renderables used in the plugin. A theme designer can provide a custom version of this renderer that changes the behaviour of any of the render methods and so to customize their theme. In this example, the render method for the index page (`render_index_page`) does 2 things. It asks the renderable to export it's data so that it is suitable for passing as the context to a template, and then renders a specific template with this context. A theme designer could either manipulate the data in the render method (e.g. removing menu entries), or change the template (change the generated HTML) to customize the output.
 
+You do not need to implement a renderer for a plugin if you are using templates and you either:
+
+1. Use the `templatable` interface and have a template with the same name in the same namespace
+2. Use the `named_templatable` interface
+
+In these cases the data from the renderable will be automatically routed to the correct template, however if you do implement a render method that will be used in preference to the default routing.
+
 The template used in this plugin is located in the plugin's templates folder. The template can also be overridden by a theme designer.
 
 ```xml title="admin/tool/demo/templates/index_page.mustache"
diff --git a/versioned_docs/version-4.4/guides/templates/index.md b/versioned_docs/version-4.4/guides/templates/index.md
index 85ddd48937..e83e4c2c7d 100644
--- a/versioned_docs/version-4.4/guides/templates/index.md
+++ b/versioned_docs/version-4.4/guides/templates/index.md
@@ -388,7 +388,7 @@ Templates can be effectively used in [renderers](https://docs.moodle.org/dev/Ren
 
 In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity. Passing your widget directly to `$OUTPUT->render()` will infer the name of your template, call `export_for_template()` and `render_from_template()`, then return the result.
 
-Example of the method added to the renderable `mywidget`:
+The following example shows a renderable using the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
 
 ```php
 /**
@@ -413,6 +413,22 @@ public function export_for_template(renderer_base $output) {
 }
 ```
 
+If you wish to render using any template your renderable can implement `named_templatable` interface instead of `templatable`. It will have to implement an additional new method `public function get_template_name(\renderer_base $renderer): string` that returns the name of the template to be used.
+
+Example of the method added to tell a renderable to use the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
+
+```php
+/**
+ * Get the name of the template to use for this templatable.
+ *
+ * @param renderer_base $output
+ * @return string
+ */
+public function get_template_name(\renderer_base $renderer): string {
+    return 'tool_myplugin/mywidget';
+}
+```
+
 :::tip
 
 When naming variables in your export data, be careful not to reuse names of helpers such as `str` or `js` - these will silently fail. Try to keep your variable names short but descriptive.
diff --git a/versioned_docs/version-4.5/apis/subsystems/output/index.md b/versioned_docs/version-4.5/apis/subsystems/output/index.md
index a9becaa651..f912bab1de 100644
--- a/versioned_docs/version-4.5/apis/subsystems/output/index.md
+++ b/versioned_docs/version-4.5/apis/subsystems/output/index.md
@@ -116,9 +116,9 @@ In the code above, we created a renderable. This is a class that you have to add
 
 namespace tool_demo\output;
 
-use renderable
-use renderer_base
-use templatable
+use renderable;
+use renderer_base;
+use templatable;
 use stdClass;
 
 class index_page implements renderable, templatable {
@@ -142,7 +142,25 @@ class index_page implements renderable, templatable {
 }
 ```
 
-This class implements the renderable interface, which has no methods, and the templatable interface, which means that this class could be rendered with a template, so it must implement the `export_for_template` method. So in this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else fancy with the data in this example (but it could). Note that the `export_for_template` function should only return simple types (arrays, stdClass, bool, int, float, string).
+This class implements the:
+
+- `renderable` interface, which has no methods
+- `templatable` interface, which means that this class could be rendered with a template, so it must implement the `export_for_template` method
+
+In this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else with the data in this example (but it could). Note that the `export_for_template` function should only return simple types (`arrays`, `stdClass`, `bool`, `int`, `float`, `string`), or those that implement the [`Stringable`](https://www.php.net/manual/en/class.stringable.php) interface.
+
+If you wish to use a specific template to render the content you may specify anyone by replacing `templatable` with `named_templatable`, which extends templatable and requires that you implement a `get_template_name()` method that returns the name of the template you wish to use.
+
+```php title="Example implementation of get_template_name()"
+    /**
+     * Gets the name of the mustache template used to render the data.
+     *
+     * @return string
+     */
+    public function get_template_name(\renderer_base $renderer): string {
+         return 'tool_demo/index_page';
+    }
+```
 
 Now let's look at the renderer for this plugin.
 
@@ -171,6 +189,13 @@ class renderer extends plugin_renderer_base {
 
 The renderer exists to provide `render_<page>` methods for all renderables used in the plugin. A theme designer can provide a custom version of this renderer that changes the behaviour of any of the render methods and so to customize their theme. In this example, the render method for the index page (`render_index_page`) does 2 things. It asks the renderable to export it's data so that it is suitable for passing as the context to a template, and then renders a specific template with this context. A theme designer could either manipulate the data in the render method (e.g. removing menu entries), or change the template (change the generated HTML) to customize the output.
 
+You do not need to implement a renderer for a plugin if you are using templates and you either:
+
+1. Use the `templatable` interface and have a template with the same name in the same namespace
+2. Use the `named_templatable` interface
+
+In these cases the data from the renderable will be automatically routed to the correct template, however if you do implement a render method that will be used in preference to the default routing.
+
 The template used in this plugin is located in the plugin's templates folder. The template can also be overridden by a theme designer.
 
 ```xml title="admin/tool/demo/templates/index_page.mustache"
diff --git a/versioned_docs/version-4.5/guides/templates/index.md b/versioned_docs/version-4.5/guides/templates/index.md
index 85ddd48937..e83e4c2c7d 100644
--- a/versioned_docs/version-4.5/guides/templates/index.md
+++ b/versioned_docs/version-4.5/guides/templates/index.md
@@ -388,7 +388,7 @@ Templates can be effectively used in [renderers](https://docs.moodle.org/dev/Ren
 
 In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity. Passing your widget directly to `$OUTPUT->render()` will infer the name of your template, call `export_for_template()` and `render_from_template()`, then return the result.
 
-Example of the method added to the renderable `mywidget`:
+The following example shows a renderable using the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
 
 ```php
 /**
@@ -413,6 +413,22 @@ public function export_for_template(renderer_base $output) {
 }
 ```
 
+If you wish to render using any template your renderable can implement `named_templatable` interface instead of `templatable`. It will have to implement an additional new method `public function get_template_name(\renderer_base $renderer): string` that returns the name of the template to be used.
+
+Example of the method added to tell a renderable to use the `mywidget.mustache` template in the `tool_myplugin` plugin templates directory:
+
+```php
+/**
+ * Get the name of the template to use for this templatable.
+ *
+ * @param renderer_base $output
+ * @return string
+ */
+public function get_template_name(\renderer_base $renderer): string {
+    return 'tool_myplugin/mywidget';
+}
+```
+
 :::tip
 
 When naming variables in your export data, be careful not to reuse names of helpers such as `str` or `js` - these will silently fail. Try to keep your variable names short but descriptive.

From b763e8a04d0840fda22aea7f8145fe3ac74e00d7 Mon Sep 17 00:00:00 2001
From: Andrew Nicols <andrew@nicols.co.uk>
Date: Tue, 12 Nov 2024 10:54:34 +0800
Subject: [PATCH 2/2] [docs] Miscellanous output docs tidyups

---
 docs/guides/templates/index.md                |  2 +-
 .../version-4.1/guides/templates/index.md     |  5 +-
 .../apis/subsystems/output/index.md           | 75 +++++++++++--------
 .../version-4.3/guides/templates/index.md     |  2 +-
 .../apis/subsystems/output/index.md           |  2 +-
 .../version-4.4/guides/templates/index.md     |  2 +-
 .../version-4.5/guides/templates/index.md     |  2 +-
 7 files changed, 52 insertions(+), 38 deletions(-)

diff --git a/docs/guides/templates/index.md b/docs/guides/templates/index.md
index e83e4c2c7d..37ea64d4c4 100644
--- a/docs/guides/templates/index.md
+++ b/docs/guides/templates/index.md
@@ -10,7 +10,7 @@ description: A guide to the features and use of Mustache templating in Moodle.
 
 Moodle makes use of the [Mustache](https://mustache.github.io) template system to render most of its HTML output, and in some other cases too.
 
-Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can overrides the templates defined in other components if required.
+Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can override the templates defined in other components if required.
 
 <details>
 <summary>A simple example</summary>
diff --git a/versioned_docs/version-4.1/guides/templates/index.md b/versioned_docs/version-4.1/guides/templates/index.md
index c4615b30a0..37ea64d4c4 100644
--- a/versioned_docs/version-4.1/guides/templates/index.md
+++ b/versioned_docs/version-4.1/guides/templates/index.md
@@ -10,7 +10,7 @@ description: A guide to the features and use of Mustache templating in Moodle.
 
 Moodle makes use of the [Mustache](https://mustache.github.io) template system to render most of its HTML output, and in some other cases too.
 
-Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. THe Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can overrides the templates defined in other components if required.
+Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can override the templates defined in other components if required.
 
 <details>
 <summary>A simple example</summary>
@@ -486,7 +486,7 @@ Templates.renderForPromise('block_looneytunes/profile', context)
 .catch((error) => displayException(error));
 ```
 
-Under the hood, this does a few clever things for us. It loads the template via an AJAX call if it was not cached. It finds any missing lang strings in the template and loads them in a single AJAX request. It split the JS from the HTML and returns us both in easy to use way. Read on for how to nicely deal with that `js` parameter.
+Under the hood, this does a few clever things for us. It loads the template via an AJAX call if it was not cached. It finds any missing lang strings in the template and loads them in a single AJAX request. It splits the JS from the HTML and returns both in an easy to use way. Read on for how to nicely deal with that `js` parameter.
 
 ## Templates requiring JavaScript
 
@@ -661,6 +661,7 @@ In PHP you have access to the `$CFG` object to allow access to properties. Musta
 ```
 
 The properties available on the `globals.config` object are the same as normally exposed for JavaScript; these are gathered from `get_config_for_javascript()` function in `lib/outputrequirementslib.php`.
+This object is only available when using client-side Mustache rendering in JavaScript; it is not added to templates rendered with the PHP Mustache engine.
 
 ## Core templates
 
diff --git a/versioned_docs/version-4.3/apis/subsystems/output/index.md b/versioned_docs/version-4.3/apis/subsystems/output/index.md
index 4bf1cb102e..ff25c10131 100644
--- a/versioned_docs/version-4.3/apis/subsystems/output/index.md
+++ b/versioned_docs/version-4.3/apis/subsystems/output/index.md
@@ -209,10 +209,10 @@ This is the mustache template for this demo. It uses some bootstrap classes dire
 
 ## Output Functions
 
-This section tries to explain a bit how dynamic data should be sent from Moodle to the browser in an organised and standard way.
+This section explains how dynamic data should be sent from Moodle to the web browser in an organised and standard way.
 
 :::important
-Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.
+It is possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.
 
 By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!
 :::
@@ -223,6 +223,8 @@ For each of the functions below we'll try to explain when they should be used, e
 
 ### String formatting functions
 
+The `format_string` and `format_text` functions should always be used when preparing the output of information. They may also be used to process information before it is stored in the database however, filters should only be applied at output. For example, language filters must only be applied as the content is prepared for output because we don't yet know the user's preferred language.
+
 #### p() and s()
 
 ```php
@@ -230,61 +232,74 @@ function s($var, $strip=false)
 function p($var, $strip=false)
 ```
 
-These functions share the same code, so they will be explained together. The only difference is that `s()` returns the string, while `p()` prints it directly.
+The only difference between these two functions is that `s()` returns the string, while `p()` prints it directly.
 
 These functions should be used to:
 
-- print all the **values of form fields** like `<input>` or `<textarea>` tags.
-- **show plain (non-HTML) text** that has been introduced by the user (search string, quiz responses, ...).
-- print, in general, all the **dynamic data, not being HTML**, that doesn't need to be cleaned nor processed by filters. It is important not to use these functions for strings that contain HTML markup.
+- Print all the **values of form fields** like `<input>` or `<textarea>` tags.
+- **Print plain (non-HTML) text** that has been introduced by the user (search string, quiz responses, ...).
+- Print in general as long as the text does not need to be cleaned or processed by filters.
+- Print HTML source code instead of rendering it.
 
-The functions replace certain characters that would have special meaning in HTML (`<, >, ", ', and &`) by HTML entities, so that they are displayed as intended. Note that even though the value of form fields printed with `p()` will have these characters converted to HTML entities, the submitted values will still contain the original characters.
+The functions replace certain characters that have a special meaning in HTML (`<, >, ", ', and &`) with HTML entities so that they are displayed as intended. Note that even though the value of form fields printed with `p()` will have these characters converted to HTML entities, the submitted values will still contain the original characters.
 
 The key parameter for this function is:
 
-- **strip**: it decides if we want to strip slashes from the string or not. By default, it's `false`, so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database, but from HTTP requests (forms, links, ...).
+- `strip`: Set to `true` to strip slashes from the string. Only set this parameter to `true` when the data to be processed is not coming from the database. This should be used when the string comes from HTTP requests (forms, links, ...). (Default is `false`, so no strip will be performed)
 
 #### format_text()
 
 ```php
-function format_text($text, $format = FORMAT_MOODLE, $options = null, $courseid_do_not_use = null)
+function format_text(
+    string $text,
+    $format = FORMAT_MOODLE,
+    [
+        'noclean' => false,
+        'trusted' => false,
+        'filter' => true,
+        'context' => $context,
+        'para' => true,
+        'newline' => true,
+        'allowid' => false,
+        'blanktarget' => false,
+    ],
+);
+
 ```
 
 This function should be used to:
 
 - print **any html/plain/markdown/moodle text**, needing any of the features below. It is mainly used for long strings like posts, answers, glossary items, etc.
-- filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [get_string](https://docs.moodle.org/dev/String_API#get_string.28.29) which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .
-Note that this function is really **heavy** because it supports **cleaning** of dangerous contents, delegates processing to enabled **content filter**s, supports different **formats** of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of **automatic conversions** like adding smilies, build links. Also, it includes a strong **cache mechanism** (DB based) that will alleviate the server from a lot of work processing the same texts time and again.
+- filter content through Moodle or 3rd party language filters for multi-language support. This is not to be confused with [get_string](https://docs.moodle.org/dev/String_API#get_string.28.29) which is used to access localized strings in Moodle from its language packs. Together, these functions enable Moodle multi-language support.
+Note that this function is **process intensive** because it supports **cleaning** of dangerous contents, delegates processing to enabled **content filters**, supports different **formats** of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of **automatic conversions** like adding smilies, build links. Also, it includes a strong **cache mechanism** (DB-based) that will alleviate the server from a lot of work processing the same texts time and again.
 
 Some interesting parameters for this function are:
 
-- **format**: To tell the function about how the data has been entered. It defaults to `FORMAT_MOODLE` that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are `FORMAT_HTML`, `FORMAT_PLAIN`, `FORMAT_MARKDOWN`.
-- **options**: Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:
-  - `options->noclean`: To decide if we want to skip the clean-up of text, **un-protecting us** from attacks and other security flaws (defaults to false, so protection is enabled. You **shouldn't set it to true ever** unless you are 200% sure that only controlled users can edit it (mainly admins). **Never use it for general text places** (posts...) or you will be, sooner or later, attacked! Note that this option is ignored for `FORMAT_PLAIN`, the text is never cleaned.
-  - `options->trusted`: Indicates that this content is trusted and does not need clean-up (but only if `$CFG->enabletrusttext` is true). This argument is ignored if `noclean` is specified.
-  - `options->filter`: To decide if you want to allow filters to process the text (defaults to true). This is ignored by `FORMAT_PLAIN` for which filters are never applied.
-  - `options->context`: If text is filtered (and this happens by default), it is very important to specify context (id or object) for applying filters. If context is not specified it will be taken from `$PAGE->context` and may potentially result in displaying the same text differently on different pages. For example all module-related information should have module context even when it appears in course-level reports, all course-related information such as name and description should have course context even when they are displayed on front page or system pages.
-  - `options->param`: To decide if you want every paragraph automatically enclosed between html paragraph tags (`<p>...</p>`) (defaults to true). This option only applies to `FORMAT_MOODLE`.
-  - `options->newlines`: To decide if line feeds in text should be converted to html newlines (`<br />`) (defaults to true). This option only applies to `FORMAT_MOODLE`.
-  - `options->nocache`: If true the string will not be cached and will be formatted every call. Default false.
-  - `options->overflowdiv`*: If set to true the formatted text will be encased in a div with the class no-overflow before being returned. Default false.
-  - `options->allowid` : If true then id attributes will not be removed, even when using HTML Purifier. Default false.
-  - `options->blanktarget` : If true all `<a>` tags will have `target="_blank"` added unless target is explicitly specified. Default false.
-- **courseid_do_not_use**: This parameter was earlier used to help applying filters but now is replaced with more precise `$options->context`, see above
+- **format**: This parameter specifies the format of the text. `FORMAT_MOODLE` is a useful format for processing plain text because it features automatic rendering of links and smilies, and does a good job of converting plain text to HTML output. Other supported formats include `FORMAT_HTML`, `FORMAT_PLAIN`, `FORMAT_MARKDOWN`. (Default is `FORMAT_MOODLE`)
+- **options**: Here we can specify options for processing the text. You only need to define them if they are different from the default values. The main options are:
+  - `options->noclean`: Set to `true` to skip the clean-up of text, **un-protecting us** from attacks and other security flaws. You **should never set it to `true`** unless you are 200% sure that only trusted users can edit the content such as site administrators. **Never use it for user-submitted text** (posts...) or you will be attacked sooner or later! Note that this option is ignored for `FORMAT_PLAIN` where the text is never cleaned. (Default is `false`, so protection is enabled)
+  - `options->trusted`: Set to `true` if the content is trusted and does not need clean-up. This argument is only enabled if `$CFG->enabletrusttext` is also set to `true`. It is ignored if `noclean` is specified. (Default is `false`)
+  - `options->filter`: Set to `false` if you do not want to allow filters to process the text. This is ignored by `FORMAT_PLAIN` for which filters are never applied. (Default is `true`)
+  - `options->context`: If text is filtered (and this happens by default), it is very important to specify the context (id or object) for applying filters. If context is not specified it will be taken from `$PAGE->context` and may potentially result in displaying the same text differently on different pages. For example, all module-related information should have module context even when it appears in course-level reports, all course-related information such as name and description should have course context even when displayed on the front page or system pages.
+  - `options->para`: Set to `false` if you do not want every paragraph to automatically be enclosed between HTML paragraph tags (`<p>...</p>`). This option only applies to `FORMAT_MOODLE`. (Defaults is `true`)
+  - `options->newlines`: Set to `false` if line feeds in text should be converted to HTML newlines (`<br />`). This option only applies to `FORMAT_MOODLE`. (Default to `true`)
+  - `options->overflowdiv`*: Set to `true` if you want the formatted text to automatically be encased in a div with the class no-overflow before being returned. (Default is `false`)
+  - `options->allowid`: Set to `true` to ensure that the id attributes will not be removed, even when using HTML Purifier. (Default is `false`)
+  - `options->blanktarget`: Set to `true` to have `target="_blank"` added to all `<a>` tags unless the target attribute is explicitly specified. (Default is `false`)
 
 #### format_string()
 
 ```php
-function format_string ($string, $striplinks = true, $options = null)
+function format_string(string $text, $striplinks = true, ['context' => $context, 'escape' => true, 'filter' => true])
 ```
 
 This function should be used to:
 
 - print **short non-html strings that need filter processing** (activity titles, post subjects, glossary concepts...). If the string contains HTML, it will be filtered out. If you want the HTML, use `format_text()` instead.
-- filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [get_string](https://docs.moodle.org/dev/String_API#get_string.28.29) which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support .
+- filter content through Moodle or 3rd party language filters for multi-language support. Not to be confused with [get_string](https://docs.moodle.org/dev/String_API#get_string.28.29) which is used to access localized strings in Moodle and its language packs. Together, these functions enable Moodle multi-language support.
 All enabled **heading filters** will be applied to the string.
 
-Please note that this function is basically one stripped version of the full `format_text()` function detailed above and **it doesn't offer any of its options or protections**. It simply filters the strings and returns the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper `xxx_param()` functions.
+Please note that this function is a stripped version of the full `format_text()` function detailed above. **It does not offer any of its options or protections**. It simply filters the strings and returns the result, so we must ensure that the string has been processed properly and cleaned at input time using the proper `xxx_param()` functions.
 
 Some interesting parameters for this function are:
 
@@ -294,14 +309,12 @@ Some interesting parameters for this function are:
   - `options->escape`: Set to `false` if you do not want to escape HTML entities. (Default is `true`)
   - `options->filter`: Set to `false` if you do not want to allow filters to process the text. This is ignored by `FORMAT_PLAIN` for which filters are never applied. (Default is `true`)
 
-:::note
-In earlier versions of Moodle, the third argument was integer `$courseid`. It is still supported for legacy - if the third argument is an integer instead of an array or object, it is considered to be course id and is this course's context is passed to the filters being applied.
-:::
-
 ### Simple elements rendering
 
 :::important
+
 Those methods are designed to replace the old ```html_writer::tag(...)``` methods. Even if many of them are just wrappers around the old methods, they are more semantic and could be overridden by component renderers.
+
 :::
 
 While to render complex elements, you should use [templates](../../../guides/templates/index.md), some simple elements can be rendered using the following functions:
diff --git a/versioned_docs/version-4.3/guides/templates/index.md b/versioned_docs/version-4.3/guides/templates/index.md
index e83e4c2c7d..37ea64d4c4 100644
--- a/versioned_docs/version-4.3/guides/templates/index.md
+++ b/versioned_docs/version-4.3/guides/templates/index.md
@@ -10,7 +10,7 @@ description: A guide to the features and use of Mustache templating in Moodle.
 
 Moodle makes use of the [Mustache](https://mustache.github.io) template system to render most of its HTML output, and in some other cases too.
 
-Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can overrides the templates defined in other components if required.
+Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can override the templates defined in other components if required.
 
 <details>
 <summary>A simple example</summary>
diff --git a/versioned_docs/version-4.4/apis/subsystems/output/index.md b/versioned_docs/version-4.4/apis/subsystems/output/index.md
index a1879eb73e..ff25c10131 100644
--- a/versioned_docs/version-4.4/apis/subsystems/output/index.md
+++ b/versioned_docs/version-4.4/apis/subsystems/output/index.md
@@ -307,7 +307,7 @@ Some interesting parameters for this function are:
 - `options`
   - `options->context`: Context (id or object) for applying filters. If context is not specified it will be taken from `$PAGE->context` and may potentially result in displaying the same text differently on different pages. For example, all module-related information should have module context even when it appears in course-level reports, all course-related information such as name and description should have course context even when they are displayed on the front page or system pages.
   - `options->escape`: Set to `false` if you do not want to escape HTML entities. (Default is `true`)
-  - `options->filter`: Set to `false` if you do not want to allow filters to process the text. This is ignored by `FORMAT_PLAIN` for which filters are never applied.  (Default to `true`)
+  - `options->filter`: Set to `false` if you do not want to allow filters to process the text. This is ignored by `FORMAT_PLAIN` for which filters are never applied. (Default is `true`)
 
 ### Simple elements rendering
 
diff --git a/versioned_docs/version-4.4/guides/templates/index.md b/versioned_docs/version-4.4/guides/templates/index.md
index e83e4c2c7d..37ea64d4c4 100644
--- a/versioned_docs/version-4.4/guides/templates/index.md
+++ b/versioned_docs/version-4.4/guides/templates/index.md
@@ -10,7 +10,7 @@ description: A guide to the features and use of Mustache templating in Moodle.
 
 Moodle makes use of the [Mustache](https://mustache.github.io) template system to render most of its HTML output, and in some other cases too.
 
-Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can overrides the templates defined in other components if required.
+Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can override the templates defined in other components if required.
 
 <details>
 <summary>A simple example</summary>
diff --git a/versioned_docs/version-4.5/guides/templates/index.md b/versioned_docs/version-4.5/guides/templates/index.md
index e83e4c2c7d..37ea64d4c4 100644
--- a/versioned_docs/version-4.5/guides/templates/index.md
+++ b/versioned_docs/version-4.5/guides/templates/index.md
@@ -10,7 +10,7 @@ description: A guide to the features and use of Mustache templating in Moodle.
 
 Moodle makes use of the [Mustache](https://mustache.github.io) template system to render most of its HTML output, and in some other cases too.
 
-Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can overrides the templates defined in other components if required.
+Templates are defined as plain text, which typically includes HTML, and a range of Mustache tags and placeholders. The Mustache placeholders are replaced with actual values during the render of the page. Mustache templates can be rendered both server-side in PHP, and client-side using JavaScript. Themes can override the templates defined in other components if required.
 
 <details>
 <summary>A simple example</summary>