Plugin hooks

95 hooks — 50 filters, 45 events — and 6 UI regions. 25 are wired: something in the board fires them today, and the rest are declared but not yet reached by a call site.

The wired column is derived from the tree by scripts/hook-callsites.mjs, not maintained by hand — a registry entry with no call site is a promise about code that never runs, and it fails in the quietest possible way: the plugin installs, the handler registers, nothing happens. plugins/reference is required by its own test to handle every wired hook, so a hook cannot join that column without something proving it fires.

A filter is handed a value and returns a replacement; its result is used, so a filter that throws or returns nothing leaves the value as it was and the chain carries on with the next plugin. An event is told what happened and its return value is discarded — which is why anything that only wants to observe should be one: it cannot corrupt the thing it is watching even when it is wrong.

Handlers run in (priority, plugin key) order. Both halves are declared, so two plugins compose the same way on every request and on every instance.

Every handler is called inside the host’s try/catch and is timed. A plugin that fails repeatedly is switched off for the rest of the process and says so in its health row. See plugin-api.md for the policy, the lifecycle and the limits.

Content rendering

• markdown.parse.text — The raw Markdown source, before it is parsed. Last chance to rewrite input.
• markdown.render.html — Rendered HTML, after the renderer has constructed it. Anything added here is trusted output and nothing escapes it afterwards.
• markdown.directives — The declarative directive list, so a plugin can add a :::name block or :name[…] span without core changes.
• post.body.html — One post’s rendered body, in the context of the thread it is being read in.
• signature.html — A member’s rendered signature, wherever it appears.
• smilies.list — The smilie set offered by the editor and substituted at render.
• word-filter.patterns — The render-time word filter’s pattern list.

View models

• view.header — The header model, before the theme renders it.
• view.user-panel — The user panel model: greeting, counts, account links.
• view.navigation — The breadcrumb trail.
• view.footer — The footer model, including its link list.
• view.forum-jump — The jump box model. A plugin adding a destination must give it a real forum id — the route re-authorises whatever is submitted.
• view.announcement — One announcement, on its way to the theme. Its body is already rendered HTML from the boardu2019s own renderer, so a plugin replacing it is replacing trusted markup — the one hook where that is true of a body.
• view.board-index — The index page model.
• view.forum-row — One forum row in a listing. Runs once per row — keep it cheap.
• view.thread-row — One thread row in a listing. Runs once per row.
• view.post-bit — One post as the theme will receive it. The busiest hook on the board: it runs once per post on every thread page.
• view.post-actions — The per-post control links. Adding one here does not create permission to use it.
• view.member-profile — A member’s profile model, including its custom fields and action links.
• view.board-stats — The board totals block.
• view.who-is-online — The online list, already resolved against the reader.
• view.latest-threads — The index sidebar’s newest-threads panel. Runs again on every refresh of the live region, not only on the page load — keep it cheap.
• view.latest-posts — The index sidebar’s newest-posts panel. Same refresh cost as view.latest-threads.
• view.pagination — A resolved page-link window.
• view.search-form — The search form model, including its filter options.
• view.error-notice — The error page model. Runs on the page that renders when things are broken.
• view.shell — The page frame’s model. Runs on every page including the error pages.
• view.notice — A board notice or flash message, before the theme renders it.
• view.category-block — One category on the index, with its rendered forum rows.
• view.subforum-list — The compact child-forum list above a thread listing.
• view.forum-display — A forum page’s model, including its rendered regions.
• view.thread-view — A thread page’s model, including its rendered post list.
• view.post-form — The composer page’s model. The form itself is app-rendered and arrives as a region.
• view.redirect-notice — The interstitial shown after a mutation, before the meta refresh fires.

Posting

• thread.create.validate — Validation messages for a new thread. Returning a non-empty list refuses the post.
• thread.create.before — The thread draft, before it is written. Subject, body, prefix, options.
• thread.created — A thread was created and committed.
• post.create.validate — Validation messages for a reply.
• post.create.before — The reply draft, before it is written.
• post.created — A reply was created and committed.
• post.edit.before — An edit’s new body and reason, before the revision is written.
• post.edited — A post was edited and a revision recorded.
• post.delete.before — A post is about to be soft-deleted. Observation only: refusing is a permission.
• post.deleted — A post was soft-deleted.
• post.restored — A soft-deleted post was restored.
• thread.moved — A thread changed forum. Carries both forum ids.
• thread.merged — Two threads became one.
• thread.split — Posts were split out into a new thread.
• thread.locked — A thread was opened or closed.
• thread.stickied — A thread was pinned or unpinned.
• attachment.upload.validate — Validation messages for an upload, after the magic-byte check. A plugin may refuse a file core would accept; it can never accept one core refused.
• attachment.uploaded — A file finished uploading and re-encoding.
• attachment.deleted — An attachment was removed, by a member or by the orphan sweep.
• poll.created — A poll was attached to a thread.
• poll.voted — A vote was cast. Fires once; the database enforces one per member.
• rating.recorded — A thread rating was recorded or changed.

Moderation

• report.created — Something was reported. The hook a notifier or a webhook wants.
• report.resolved — A report was closed, with the resolution.
• approval.queued — Content entered the approval queue.
• approval.decided — Queued content was approved or rejected.
• warning.issued — A warning was issued, with its points and expiry.
• warning.revoked — A warning was revoked or expired.
• moderation.logged — A moderation action was written to the log.

Identity

• user.register.validate — Validation messages for a registration. Where a custom question or an external blocklist belongs.
• user.registered — An account was created, before or after activation depending on the mode.
• user.activated — An account finished activation.
• user.login.attempted — A sign-in was attempted, with the outcome. Never carries the password or the session token.
• user.logged-in — A session was established.
• user.logged-out — A session was ended, by the member or by revocation.
• user.banned — A member was banned, with the expiry when there is one.
• user.unbanned — A ban was lifted or expired and the prior group restored.
• user.groups.changed — Primary or secondary group membership changed.
• user.profile.updated — A member saved profile or option changes.
• user.merged — Two accounts were merged. Carries the winner and the account that went.
• user.deleted — An account was pruned or deleted.

Mail, notifications, messages

• notification.create.before — A notification about to be created. Returning null suppresses it.
• notification.created — A notification was stored.
• mail.send.before — A queued message, before it is handed to the mail driver. Subject, body and recipient; returning null drops it.
• mail.sent — A message was accepted by the driver. Not proof of delivery.
• pm.send.before — A private message, before it is stored.
• pm.sent — A private message was delivered to its recipients’ folders.
• subscription.changed — A member subscribed to or unsubscribed from a thread or forum.
• reputation.changed — Reputation was given, changed or removed.

Search, discovery, syndication

• search.query.before — The parsed search terms, before the query runs. The scope is not filterable.
• search.results — A page of results, already permission-filtered in SQL. A plugin may reorder or drop; adding a row here would add one the viewer may not see.
• feed.items — The items of a feed, rendered as a guest. Anything added is public.
• sitemap.entries — One chunk of the sitemap.
• metadata.page — Title, description and social card for a page.

Admin and system

• admin.navigation — The admin panel’s section links, so a plugin page can be reached.
• settings.saved — Board settings changed. Carries the keys, never the values.
• task.run.before — A scheduled task is about to run.
• task.run.after — A scheduled task finished, with its outcome and duration.
• cache.invalidated — A cache tag was invalidated.
• plugin.enabled — A plugin was enabled — including this one, which is how it learns it is on.
• plugin.disabled — A plugin was disabled, by an operator or by the host after repeated failures. Carries the reason.

UI regions

Regions are not theme slots. A theme owns its slots; a region is an explicit "plugins may add something here" point that a theme chooses to render, so the theme keeps control of where plugin output appears and the plugin keeps control of what it is. Several plugins contributing to one region compose by concatenation, in the same deterministic order as hooks.

• header.notice — Directly below the board header, above the page body. Board-wide notices.
• index.footer — The bottom of the board index, below the statistics block.
• postbit.badges — Beside a post author’s name. Runs once per post on every thread page — the most expensive region on the board, and the one to keep trivial.
• postbit.footer — Below a post body, above its actions.
• profile.panel — A panel on a member’s profile, below the standard fields.
• admin.dashboard — A card on the admin dashboard. Only rendered for administrators.