Plugin events

A plugin listens on an event by name. It uses MishkaInstaller.Event.Hook and defines call/1, or call/2 to receive the read-only meta. It answers {:reply, payload} to hand the payload to the next plugin, or {:reply, :halt, payload} to stop the chain. The registration below adds an audit check to the editor:

defmodule MyApp.AuditPlugin do
  use MishkaInstaller.Event.Hook, event: "builder:audit:checks", initial: %{priority: 50}

  def call(%{checks: checks} = payload) do
    {:reply, %{payload | checks: checks ++ [MyCheck.descriptor()]}}
  end
end

The CMS passes these options when it fires an event.

An event that no plugin listens on gives the payload back unchanged. A plugin chain that raises is logged, and the call site gets its payload back.

Kinds

The Kind column of the tables below uses these words.

Core, blog and document resources fire events from their Ash actions. The event name is <prefix>:<resource>:<stage>_<name>. The prefix is the extension: cms_core for the core, blog for the blog and document for the document extension. The resource is the last part of the module name in snake case, such as page for MishkaCmsCore.Runtime.Page and blog_post for MishkaBlog.BlogPost. A plugin can build the name with MishkaCmsCore.Runtime.Resources.Notifiers.PluginHook.event_name/2 instead of spelling it.

These resources fire the after_ events.

The before_ events exist on these actions only.

The query_ events exist on these read actions only.

The render_content events exist on blog:blog_post, blog:comment and document:section, which each have a rendered_content calculation.

The visual editor is a plugin surface. The core fills each list through the same events an extension uses. The sections below list the registries, the transforms, the gates and the announcements.

Registries

Each payload is a map with one key that holds the list. The core entries come first.

Transforms

Gates

A gate is a transform whose payload carries error, which starts as nil. Set it to a message to refuse. While the plugins of a gate cannot run, the gate refuses with a message that says an extension is not loaded.

Announcements

These events fire while the CMS turns saved pages, layouts, components and styles into running modules and bundles. Most are announcements. The two that carry a bundle are transforms.

The CMS keeps sites, pages, assets and more in memory. These announcements say that an entry changed on this node.

The host app serves database pages through MishkaCmsWeb.RuntimeLive. These events follow a page through mount, live navigation, events, messages and render. The names start with a capital letter, as the older events do.

MishkaCmsWeb.RuntimeLive fires these two events once the page, its language, the query parameters and the visitor are known. They run in this order: runtime:page:source, runtime:page:frame, then runtime:page:seo in the next section. The frame and the head are handed the source, and the head reads the frame's languages. A plugin answers for the pages it owns and hands every other page back untouched. {:reply, :halt, payload} keeps later plugins from answering for a page this one owns.

These events fire from plugs and controllers. Most hand a conn to the plugins. A plugin that halts the conn takes over the answer.

Web requests

API requests

The controller events keep the same capitalised names as the page events. Their payloads are maps that carry the conn, and a plugin that halts the conn takes over where the table says so.

These announcements report a write that the CMS refused. A plugin can log them or raise an alert.

These events collect lists from extensions. The payload carries the list, and a plugin returns it with its own entries added.

• Extensions and plugins: how an extension registers plugins and menus.
• Visual editor keys, commands, blocks and starters: what the editor registries hold.
• Settings: the settings that settings:register adds to.
• How a page reaches visitors: the compile and build events in order.
• Page source: the rows a page shows, read once and handed to its head, frame and blocks.
• Page frame: the languages and the bar a page hands the layout.
• Translate an extension's words: keep the words a plugin looks up.