Plugin events

The data is a map. A plugin appends to header and tabs and replies with the map.

use MishkaInstaller.Event.Hook, event: "document:page:extras"

def call(%{document: %{slug: "handbook"}, header: header} = state),
  do: {:reply, %{state | header: header ++ [%{kind: :text, label: "Edition", value: "2"}]}}

def call(state), do: {:reply, state}

The event is also asked by doc-section-cards, once for each card, with card: true. A plugin that sees it answers from what it already holds and only the badges of the header are drawn.

Header facts

Tabs

A tab is %{id: "props", label: "Props", blocks: [block]}, or the one block it is. Its id is lower-case letters, digits, - and _, and never documentation. The first tab with an id is kept. Each tab links to the page with ?tab=<id>, and the page's own text shows when the URL names no tab a plugin added.

A tab whose data is still being fetched is %{id: "props", label: "Props", state: :not_ready, text: "...", failed_text: "...", pending: %{topic: "..."}}. A tab whose data could not be had is %{id: "props", label: "Props", state: :failed, text: "..."}.

A pending topic is a Phoenix.PubSub topic on MishkaCmsCore.PubSub. The plugin announces the end of its fetch on it. Once the page is connected, doc-section starts one task that asks the event again when the topic speaks, and waits up to pending_wait milliseconds, 120000 by default. A wait that runs out turns each tab still being fetched into its failed_text. Nothing polls.

The data is the head's map. Before the event, the extension fills its title, description, type, language, tags, schema, permissions, url, vars, var_docs and card, and a plugin's reply is the answer. A plugin that registers call/2 is also handed this meta:

use MishkaInstaller.Event.Hook, event: "document:page:seo"

def call(seo, %{page: %{title: title}}), do: {:reply, %{seo | title: title <> " · Docs"}}
def call(seo, _meta), do: {:reply, seo}

A plugin can give a page a share card of its own by setting image with card: false. The answer keeps redraw as the CMS handed it. It is true when a forced look at the share card asks for the head, and a plugin that draws a card of its own draws it again over the old file then.

The sections screen fires it once it has loaded a document, and again when another version is chosen. It is fired only for an account that holds admin:dashboard:document:workspace. The data holds site_id, workspace (%{id, slug, path, name}), version (%{id, version_number} or nil), actor and actions. A plugin appends to actions.

A button opens the component in the screen's dialog. The component receives the action's own assigns plus id, site_id, workspace, version and current_user, which it cannot override. While the dialog is open, each message the screen does not handle is handed to the component as update(%{info: message}, socket).

Both are fired after the transaction commits, with meta: %{actor: actor, site_id: site_id}.

Every resource of the extension except the event log fires document:<resource>:after_<action> after an action commits, handing the record to plugins with a read-only meta: %{actor:, site_id:}. A master's twin of an action fires its own event. For the name, use MishkaCmsCore.Runtime.Resources.Notifiers.PluginHook.event_name/2 instead of spelling it, as in document:section:after_create. For a plugin that reacts to any create or update, use the event save_event_name/1 returns, such as document:section:after_save. MishkaDocument.Plugins.WorkspaceShareCard and MishkaDocument.Plugins.SectionShareCard listen on the save events of documents and pages, and draw the share card again when what it shows has changed.

MishkaCmsWeb.RuntimeLive fires runtime:page:source, runtime:page:frame and runtime:page:seo in that order in handle_params/3, for every address. The extension answers all three for a page that says it shows a record of the kind docs:document, a document's front page, or docs:page, one page of a document. Its frame plugin also answers for the library, the page whose section is document. It hands every other page back untouched, before it reads anything. See Page source: read a page's rows once and Page frame: languages and the section bar.

The source

MishkaDocument.Plugins.PageSource reads the rows once and puts them under source, as a MishkaDocument.PageSource: the document the address names, its published versions, its other editions, the version shown, that version's approved pages, and the page with its text and notes. It reads as the visitor, so a locked document or page the visitor may not open is not among them. The CMS hands the rows to the frame and head plugins as source, and to the page's blocks as page_source. A live patch to another page of the same document reuses what the address before read. The plugin ends the chain for these pages. See The rules a source keeps.

The frame

MishkaDocument.Plugins.PageFrame answers the two keys the layout reads back.

The library, /:lang/docs, keeps the CMS's default for translations.

The translation key

The word Docs is a key of the site's translations. MishkaDocument.Provision registers it when it sets a site up, and the bar reads it in the language of the response, or shows the key where nobody has written a translation. No template asks for it, so the Remove unused action on the Translations screen would delete it. MishkaDocument.Plugins.UsedTranslationKeys appends it to the keys of runtime:translations:used_keys, which keeps it. See Translate an extension's words.

• Blocks that read a document.
• Titles, descriptions, sitemap and share cards.
• Plugin events of Mishka CMS: every event the CMS fires.