From 89a6a7698a43539fd1d5be0950214c850e1a723f Mon Sep 17 00:00:00 2001 From: Neill Magill Date: Wed, 21 Aug 2024 10:09:35 +0100 Subject: [PATCH] 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 | 16 +++++++++ .../version-4.1/guides/templates/index.md | 16 +++++++++ .../version-4.2/guides/templates/index.md | 16 +++++++++ .../apis/subsystems/output/index.md | 33 ++++++++++++++++--- .../version-4.3/guides/templates/index.md | 16 +++++++++ .../apis/subsystems/output/index.md | 33 ++++++++++++++++--- .../version-4.4/guides/templates/index.md | 16 +++++++++ 8 files changed, 167 insertions(+), 12 deletions(-) diff --git a/docs/apis/subsystems/output/index.md b/docs/apis/subsystems/output/index.md index a9becaa651..ec09aae2a5 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 + +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_` 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..2eeabf91d8 100644 --- a/docs/guides/templates/index.md +++ b/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. diff --git a/versioned_docs/version-4.1/guides/templates/index.md b/versioned_docs/version-4.1/guides/templates/index.md index 814c686c31..fb22ad3541 100644 --- a/versioned_docs/version-4.1/guides/templates/index.md +++ b/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. diff --git a/versioned_docs/version-4.2/guides/templates/index.md b/versioned_docs/version-4.2/guides/templates/index.md index 814c686c31..fb22ad3541 100644 --- a/versioned_docs/version-4.2/guides/templates/index.md +++ b/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. 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..35018c380a 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 + +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_` 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..2eeabf91d8 100644 --- a/versioned_docs/version-4.3/guides/templates/index.md +++ b/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. 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..57938dfc22 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 + +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_` 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..2eeabf91d8 100644 --- a/versioned_docs/version-4.4/guides/templates/index.md +++ b/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.