Commit 1f736c

2026-11-15 16:46:00 Ralph Thesen: Document navbar, admin menu and template_folders plugin hooks
plugins.md ..
@@ 25,6 25,7 @@
- [sidebarpageindex](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_sidebarpageindex) demonstrates the sidebar page index filter and sort hooks.
- [authorsignature](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_authorsignature) adds a footer with the original author and last editor.
- [redlinks](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_redlinks) marks WikiLinks to non-existent pages in red, like MediaWiki's redlinks.
+- [userinfo](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_userinfo) shows the logged-in user in the navbar, optionally with the Gravatar icon, and comes with an admin page. It demonstrates the navbar and admin menu hooks, and how a plugin ships its own templates.
## What a plugin is
@@ 168,6 169,13 @@
- `template_html_body_inject(page)` injects HTML before the closing `</body>`.
- `template_html_sidebar_left_inject(page)` appends HTML to the left sidebar (menu and page index).
- `template_html_sidebar_right_inject(page)` appends HTML to the right sidebar (the "On this page" block).
+- `template_html_navbar_inject(page)` injects HTML into the navbar, after the search field and before the menu button.
+- `template_html_navbar_dropdown_inject(page)` injects HTML at the top of the navbar dropdown menu.
+- `template_html_admin_menu_inject()` appends HTML to the admin section of the settings sidebar, e.g. a link to a page served via `url_admin_request`.
+
+**Templates**
+
+- `template_folders()` returns a list of folders with Jinja templates shipped by the plugin, see [Shipping templates](#shipping-templates).
**Per-element rendering**
@@ 203,6 211,61 @@
- `sidebar_page_index_filter_entries(entries, mode)` filters the sidebar page index entries in place.
- `sidebar_page_index_sort_entries(entries, mode)` sorts the sidebar page index entries in place.
+### Shipping templates
+
+A plugin that serves its own pages via `url_request` or `url_admin_request`
+can render them from Jinja templates. For this, the plugin must be a package
+instead of a single module, because a wheel built from a single module
+contains only the `.py` file. Hatchling adds all files in the package
+directory to the wheel, so no extra configuration in `pyproject.toml` is
+needed:
+
+```
+plugin_userinfo/
+├── pyproject.toml
+└── otterwiki_userinfo/
+ ├── __init__.py
+ └── templates/
+ └── userinfo/
+ └── settings.html
+```
+
+The plugin returns its template folder via the `template_folders` hook and
+renders the template with `flask.render_template`:
+
+```python
+import os
+from flask import render_template
+from otterwiki.plugins import hookimpl, plugin_manager
+
+class UserInfo:
+ @hookimpl
+ def template_folders(self):
+ return [os.path.join(os.path.dirname(__file__), "templates")]
+
+ @hookimpl
+ def url_admin_request(self, plugin, extra, method="GET", values=None):
+ if plugin != "userinfo" or extra != "settings":
+ return None
+ return render_template("userinfo/settings.html", title="User Info")
+
+plugin_manager.register(UserInfo())
+```
+
+An Otter Wiki searches the plugin folders after its own templates:
+
+- A plugin cannot override a core template. A plugin file named `layout.html`
+ has no effect.
+- A plugin template can extend a core template. For example, an admin page
+ that starts with `{% extends "settings.html" %}` has the same layout and
+ sidebar as the other admin pages.
+
+To prevent name conflicts between plugins, put the templates in a subfolder
+named after the plugin, e.g. `templates/userinfo/`, and render them as
+`render_template("userinfo/settings.html")`. The
+[userinfo](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_userinfo)
+example plugin shows the complete setup.
+
### Testing a plugin
You do not need to install a plugin to test it. The example plugins use an
@@ 211,7 274,8 @@
that loads a plugin straight from its directory and unregisters it again on
teardown. Add a `test_<name>.py` next to the existing ones, load your plugin with
`example_plugin_loader("plugin_<name>")`, and if it implements `setup()` call it
-on the loaded instance. Run the suite with:
+on the loaded instance. The fixture loads single modules (`otterwiki_<name>.py`)
+and packages (`otterwiki_<name>/__init__.py`). Run the suite with:
```bash
OTTERWIKI_SETTINGS="" venv/bin/pytest docs/plugin_examples/tests
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9