The admin sidebar as data — collected from plugins at runtime, filtered by what the viewer may see, and ordered by what the admin arranged.

The nav used to be a hardcoded literal in MishkaCmsCore.Layouts: every extension's links were spelled out in the core, and every admin who reached the console saw all of them, including /admin/dashboard/account/permissions. This module replaces both halves. An extension declares its own menu and who may see it; nothing in the core names the extension.

The event

"sidebar:menus", a MishkaInstaller.Event.Hook — the sibling of "dashboard:widgets". The payload is %{groups: [Group.t()], items: [Item.t()]} and every plugin appends to either list:

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

  use Gettext, backend: MishkaCmsCore.Gettext

  @items [
    MishkaCmsCore.Sidebar.Item.new!(%{
      key: "blog",
      label: gettext_noop("Blog"),
      icon: "hero-book-open",
      path: "/admin/dashboard/blog",
      module: MishkaBlogWeb.Live.Admin.Dashboard.Home.Index,
      group: "plugins",
      order: 10,
      permissions: [
        "admin:dashboard:blog:post",
        "admin:dashboard:blog:comment"
      ],
      credit_name: "Mishka Blog",
      credit_url: "https://mishka.tools/cms/extensions/blog"
    })
  ]

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

A label is marked with gettext_noop/1 and translated when the sidebar is drawn, in the language its admin reads the dashboard in: a descriptor is built at compile time, when nobody's language is known yet.

Groups and items are two flat lists rather than a nested tree so that a group and its contents can come from different extensions — Blog and Documents each contribute one item to the Plugins group the core declares, without either knowing about the other.

Unlike widgets, the payload is seeded with core_menu/0 instead of an empty list. A widget board with no plugins registered is merely empty; a nav with no plugins registered is a console you cannot navigate — so Home, Runtime, Account and Settings are always present, whether or not mishka_installer has finished starting. Enum.uniq_by/2 keeps the FIRST declaration of a key, so a plugin can add sections but never silently redefine a core one.

Permissions

permissions on an item is a list where holding ANY entry grants; menu/1 compares it against the viewer and drops the link when nothing matches. Nothing here reads a URL: the question is "may this user see this link", and the answer needs the user and the item, nothing else.

An entry names the area its data asks for, as a plain string:

• a screen of one area — Sites, Users, Permissions, Activity, an extension's section — lists that area's name: ["admin:dashboard:runtime:site"];
• a content list every dashboard admin may read — Pages, Layouts, Components, Error Pages, Stylesheets, JS Hooks, Media, Translations — lists its area and {:under, "admin:dashboard"};
• the builder lists every name that opens a builder — the page, layout, component and error page areas and admin:dashboard:code — and the builder asks for the type it opens on;
• Home, Notifications, Settings and the Plugins section list {:under, "admin:dashboard"}.

An API admin holds nothing under admin:dashboard, so it sees no entry and opens no page.

This hides links; it does not guard pages. A hidden link is still reachable by typing its URL. Guarding the page is the page's own job — its LiveView declares who may open it — because that is a server-side check on a known module rather than a string the client controls.

Arrangement

Each group and item exposes two settings, registered by MishkaCmsCore.Sidebar.MenuSettings:

• sidebar.<key>.order — an integer; overrides the declared order
• sidebar.<key>.visible — a boolean; false hides the entry from everyone

Both are scope: :both, so a global default can be overridden per site: one CMS can put Blog above Runtime for one tenant without touching another. Values are read through MishkaCmsCore.Settings.get/3 (RAM cache), and a non-integer order or non-boolean visibility is ignored in favour of the declaration rather than crashing the chrome.

Open pages

changed/1 tells this node's open admin LiveViews that the entries' settings changed, and MishkaCmsCore.Layouts.Nav redraws their sidebar. MishkaCmsCore.Runtime.States.SettingsState calls it after it holds a sidebar.* value or an extension's <app>.active switch (MishkaCmsCore.Install.Extensions.active?/2), so a view that reads the menu again reads the new value. A site's change reaches the viewers whose menu reads that site, and the global one reaches every viewer.

Event: runtime:state:sidebar:changed — %{key: site_id}, nil for the global value.

Like the widget board, nothing here is cached: the hook is called at each mount so enabling or disabling a plugin shows up immediately. Everything else is compile-time data and ETS reads, and the viewer's permissions are loaded once per mount rather than once per item.

What is in this file

The whole concern, in one place: Group and Item, the two descriptors a plugin declares. They are small, they are useless apart, and reading the contract next to the code that applies it is the point.

The order is load-bearing: both come FIRST because @core_groups/@core_items call their new!/1 at compile time — a descriptor is built once when this module is compiled, not on every admin mount. The settings registrar stays in its own file (MishkaCmsCore.Sidebar.MenuSettings) because it is a supervised plugin, like its widget twin.