Extensions and plugins

An extension is a package from Hex that the host application depends on. The host's mix.exs lists it, for example as {:mishka_blog, "~> 0.0.1"}, and the host's configuration names its web module under config :mishka_cms_core, extensions: [...]. The standard host lists MishkaCmsCoreWeb, MishkaBlogWeb and MishkaDocumentWeb.

An extension can add:

• Admin screens. Its Routes module implements MishkaCmsCore.ExtensionRouter and answers for :admin, :admin_standalone, :public and :api. The host router reads those routes when it compiles.
• Permission names, such as admin:dashboard:blog:post. A site gets them when the extension is set up on it.
• Components and sample pages. The components ship as a UI kit bundle, and each site gets its own copy of them and of the pages. The pages hang on the site's site-main layout, between the header and the footer that every page of the site shares. See Draw an extension's pages in the site layout.
• JSON:API routes for its resources.
• Sidebar entries, dashboard widgets, settings and more. Each one is a plugin.

The core names no extension. Removing an extension removes its sidebar entry, and nothing in the core changes.

Having an extension's code in the host does not give a site its pages. A site gets them when it is set up, either from the Extensions card of the install wizard or from the extension's menu with its Set up button. The set-up writes, in this order, the permission names, the components, the pages and a snippet for the page editor. It writes only what the site lacks and never updates a row, so running it again keeps your edits.

The setting Active on this site switches an extension on or off for one site. Off hides its menu and stops its pages being served. Nothing is deleted.

A plugin is a module that uses MishkaInstaller.Event.Hook for one event. When the CMS reaches that point, it calls Hook.call(event, payload). The payload passes through every plugin on the event, lowest priority first, and each plugin's call/1 returns it, changed or not, as {:reply, payload}. Returning {:reply, :halt, state} ends the chain with that state.

This plugin adds a link to the admin sidebar. Its event is sidebar:menus, and the payload holds the lists groups and items:

defmodule MyExtWeb.SidebarMenu do
  use MishkaInstaller.Event.Hook, event: "sidebar:menus", initial: %{priority: 40}
  use Gettext, backend: MishkaCmsCore.Gettext

  alias MishkaCmsCore.Sidebar.Item

  @items [
    Item.new!(%{
      key: "notes",
      label: gettext_noop("Notes"),
      icon: "hero-book-open",
      path: "/admin/dashboard/notes",
      module: MyExtWeb.Live.Admin.Notes.Index,
      group: "plugins",
      order: 10,
      permissions: ["admin:dashboard:notes"]
    })
  ]

  @impl true
  def call(%{items: items} = data), do: {:reply, %{data | items: items ++ @items}}
end

The extension's OTP application starts its plugins under a supervisor. A plugin missing from that list never registers.

def start(_type, _args) do
  Supervisor.start_link([MyExtWeb.SidebarMenu], strategy: :one_for_one, name: MyExt.Supervisor)
end

Each plugin is a process of its own. Its record, with its status and priority, is stored in the database and in Mnesia. The priority is a number from 0 to 100, and plugins with the same number run in order of their names. A plugin is in one of these statuses:

These events are a sample. The core and the extensions name many more.

Resource actions have events too. A resource that adds PluginBeforeHook to an action fires <app>:<resource>:before_<action> with the changeset, and a plugin may change it or add an error to refuse the action. Every action of a resource that uses the PluginHook notifier fires <app>:<resource>:after_<action> once it has committed, and a create or an update also fires after_save. Examples are blog:blog_post:after_publish and document:section:after_update.

Mishka Blog starts 24 plugins from its application module:

• five dashboard widgets;
• three plugins for publish notifications and their setting;
• one plugin for its settings tab, one for its sidebar entry, and one for the installer;
• three SEO plugins: sitemap addresses, the records its pages can show, and each record's head;
• six plugins for share cards, and one that names the components its posts draw so the site's stylesheet carries them;
• three plugins for the page frame: the rows a blog page shows, the bar and languages the site layout draws, and the words that bar looks up.

Mishka Document registers its plugins the same way, from its own application module. None of this needs a change to the core.

• Plugin events: the events, their payloads and what a plugin returns.
• Install an extension: add a package to a host and set it up on a site.
• Permission names: the names the core and the extensions create.
• Components and UI kits: the bundle an extension ships its components in.