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

Author: NeillM

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
+
+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).
+
+If you wish to use a specific template to render the content you may specify anyone by replacing `templatable` with `named_templatable` it 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 implemntation 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"

docs/guides/templates/index.md

@@ -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.

versioned_docs/version-4.1/guides/templates/index.md

@@ -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.

versioned_docs/version-4.2/guides/templates/index.md

@@ -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.

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
+
+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).
+
+If you wish to use a specific template to render the content you may specify anyone by replacing `templatable` with `named_templatable` it 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 implemntation 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"

versioned_docs/version-4.3/guides/templates/index.md

@@ -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.

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
+
+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).
+
+If you wish to use a specific template to render the content you may specify anyone by replacing `templatable` with `named_templatable` it 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 implemntation 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"

versioned_docs/version-4.4/guides/templates/index.md

@@ -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.