How plugins add template sentences and functions without overriding the core Birkly language.
In short: Core registers built-in fieldtype shelf helpers (media_url, gallery_html, …) for every site. Plugins can add more (Commerce cart URLs, Events .ics, user “logged in” checks, etc.). At runtime the engine loads plugin language first, then core last — core keywords win on conflicts (CSS-like cascade). Extend; don’t override {for each}, {from}, or format.
Beginner
Core shelf (always available)
No plugin required — see Core template shelf:
| Helper | Use |
|---|---|
{media_url('field')} | Public URL for a file field |
{media_img('field', 'Alt')} | <img> for a media id |
{gallery_html('field')} | Gallery grid |
{oembed_html('field')} | Embed iframe |
{relation_titles('field')} | Related entry titles |
{relation_links('field')} | Linked list to related entries |
{dynamicitems_html('field')} | Dynamic items blocks |
What you might see from plugins
When a plugin is active, new placeholders appear in docs for that plugin:
| Plugin | Examples |
|---|---|
| Commerce | {commerce_cart_count}, {commerce_buy_url …} — Commerce functions |
| Events | {upcoming_events}, {event_ics_url …} — Events functions |
| User Management | Phrases like user_logged_in, user_current (when registered) |
If the plugin is inactive, those helpers are omitted — the rest of your templates still run.
Owner tip
Install/activate plugins from Admin → Plugins / Hub. Template extras appear only after activation. See Plugins.
Advanced Users
For developers & AI
Load order
- Plugin language definitions
- Core / template language definitions (win on conflict)
Registration
Plugins typically call register_template_function() (or the language-module equivalent) from plugin.php. Gate on “plugin active” so inactive plugins leave no global names.
Design rules
- Prefer distinctive prefixes (
commerce_,event_,user_). - Do not redefine
for each,from,if,format,ordered by. - Document public helpers in Birkly-Docs under
03-templating/and link from the plugin’s extensibility page. - Storefront behavior (cart, auth gate, RSVP) ships in
*-storefront.jsand auto-loads viaplugin.json— see Project sites and plugins. - Keep Shadow DOM policy: helpers still run through the string engine; discovery remains Light DOM.
Testing
- Activate plugin → reference project or minimal HTML → confirm helper output.
- Deactivate → page must not throw; helper should be absent.
- Validator: do not teach phantoms alongside real plugin APIs.
Related platform surfaces
- Website tools (WebMCP) are not template language — Website tools.
- AI app connections: Settings → AI — MCP connections.