[docs] Update output documentation for react - #1685
Open
andrewnicols wants to merge 1 commit into
Open
Conversation
✅ Deploy Preview for moodledevdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Moodle DevDocs output documentation to better cover React-based rendering and clarify how renderables, templates, and renderers fit together, including documenting html_writer::react_component().
Changes:
- Expanded and reorganised output subsystem docs to describe React component renderables, templatable/named_templatable flows, and rendering priority.
- Added API documentation for
html_writer::react_component()with an example and guidance on when it’s called automatically. - Updated the project word list to include “templatables”.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| project-words.txt | Adds “templatables” to the project dictionary. |
| docs/apis/subsystems/output/index.md | Reworks output docs with new React renderable guidance and updated rendering explanations. |
| docs/apis/core/htmlwriter/index.md | Documents html_writer::react_component() and its output attributes. |
Suppressed comments (7)
docs/apis/subsystems/output/index.md:82
- The paragraph starts using “Theme designers” but the final clause still says “themers”. Consider using the same term consistently.
This gets an instance of the `plugin_renderer_base` class that we use to create all output for our page. Theme designers can subclass this renderer to override specific render methods in order to customise Moodle's output. See [Output renderers](https://docs.moodle.org/dev/Output_renderers) for more information, and [Overriding a renderer](https://docs.moodle.org/dev/Overriding_a_renderer) for information about how themers can customise a renderer.
docs/apis/subsystems/output/index.md:212
- In the named_templatable example, the class is declared as
my_react_widgetbut the instantiation later usesmy_named_templatable_widget. Renaming the class here keeps the example consistent.
class my_react_widget implements
docs/apis/subsystems/output/index.md:243
- The explicit section id uses “templatables” but the interface name is
templatable. Using...-templatable-interfacekeeps the anchor consistent and avoids introducing a new plural form.
#### Renderables implementing the `templatable` interface {/* #renderables-implementing-the-templatables-interface */}
docs/apis/subsystems/output/index.md:255
- This code block is for a
templatableexample but the title says “named_templatable” and the class name doesn’t match themy_templatable_widgetused in the examples below.
```php title="Example named_templatable implementation"
namespace tool_demo\output;
class my_react_widget implements
\core\output\templatable,
docs/apis/subsystems/output/index.md:326
- Typo: “thd” should be “the”.
Most implementations should use either the `react_component_renderable` implementation for newer React code, or thd `named_templatable` implementation for Mustache.
docs/apis/subsystems/output/index.md:346
- Grammar: “provide a ... methods” should either be singular or remove the article; also consider showing the method form as
render_<renderable>().
Renderers _may_ provide a `render_<renderable>` methods for all renderables used in the plugin.
docs/apis/subsystems/output/index.md:350
- Spelling/grammar: “does 2 things” and “export it's data” read as informal/incorrect in docs; also “customize” is inconsistent with other uses of “customise” on this page.
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.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+73
to
+74
| The most important properties stored in `$PAGE` are the page context, URL, layout, title and headings. `$PAGE` also gives access to some other important classes such as `$PAGE->requires`, which is an instance of the `\core\output\requirements\page_requirements_manager` . The `page_requirements_manager` class lets us set dependencies for code such as JavaScript and CSS to be inserted | ||
| correctly into the page (The order in which things are inserted into the page is hugely important for performance). |
Comment on lines
+146
to
+148
| ## Renderables {/* #renderables */} | ||
|
|
||
| In the code above, we created a renderable. This is a class that you have to add to your plugin. It holds all the data required to display something on the page. Here is the renderable for this example: | ||
| In the code above we rendered a `renderable`. This class holds all the data required to display that item on the page. |
| // <span class="zombie">BRAINS</span> | ||
| ``` | ||
|
|
||
| ### react_component {/* #react-component */} |
This commit also updates the output documentation to provide better examples, and provide more context.
andrewnicols
force-pushed
the
MDL-89296-react
branch
from
August 27, 2026 04:41
9bde953 to
bfa15f1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This commit also updates the output documentation to provide better examples, and provide more context.
See MDL-89296 for information.