Developer docs/Extension reference

Widgets and slots

Every place where an addon can inject UI: 82 admin pages and 27 client pages, each with its own page slots, 8 layout slots and 11 hand-placed named slots (579 slot names in total, wildcards not counted). Generated from frontend/src/App.tsx, frontend/src/layouts/Shell.tsx and the <PluginSlot> / <PluginWidgets> calls; a test fails when the frontend renders a position the docs do not list.

#Two ways to render

• Native (default): body is a JSON node tree (cards, tables, stats, forms, …) rendered with the panel's own components and theme. No addon JavaScript runs. Node reference: UI schema.
• Iframe: frame: {src, height} loads an HTML file from the addon's assets/ in a sandboxed iframe (opaque origin, strict CSP). Needs "iframe" in capabilities.ui, approved by the admin at install. The frame talks to the panel through postMessage: pelty:ready, pelty:resize, pelty:request (own routes, plus GET on approved bridge prefixes), pelty:navigate and pelty:toast.

#Registering a slot contribution

List contributions in addon.json ui.slots. order sorts contributions in the same slot (lower first). Text that starts with plugin.<addon-id>. is translated from the manifest i18n. Page context is available as {{ctx.*}}.

{
  "ui": {
    "slots": [
      {
        "body": {
          "text": "{{t:plugin.my-addon.badge}}",
          "type": "badge"
        },
        "order": 5,
        "slot": "admin.invoices.toolbar"
      },
      {
        "body": {
          "children": [
            {
              "label": "plugin.my-addon.score",
              "type": "stat",
              "value": "{{data.score.value}}"
            }
          ],
          "type": "card"
        },
        "data": {
          "score": {
            "get": "/api/v1/addons/my-addon/score?customer={{ctx.id}}"
          }
        },
        "slot": "admin.customers.detail-panel"
      },
      {
        "frame": {
          "height": 64,
          "src": "assets/banner.html"
        },
        "slot": "client.layout.banner"
      }
    ]
  }
}

The example addon's real manifest is on Addon UI.

#Slot names

Page slots are <area>.<route-key>.<position>, with area = admin or client. Use * as route key for every page (admin.*.toolbar). Positions: before, after, toolbar, row-actions, tabs, detail-panel. Layout slots are <area>.layout.<position> with header, sidebar, footer, banner.

Replaceable sections: none are wrapped yet, so replace: slots currently render nothing.

#Named slots

Fixed slots placed on specific pages. render slots take a node tree or frame (ui.slots). widget and nav slots take stat cards and menu links from webhook plugins (ui.widgets, ui.menu).

#Admin pages

#Client area pages

A key with <param> contains the actual value of that URL segment (/admin/hub/system → hub-system). Ids (numbers, UUIDs, long hex, ABC-123) are always dropped.

#Example: native widget and iframe widget

{
  "body": {
    "text": "{{t:plugin.integration-guide.hello}}",
    "type": "alert"
  },
  "slot": "client.dashboard"
}

<!-- assets/banner.html -->
<!doctype html><meta charset="utf-8">
<p id="msg">Loading…</p>
<script>
  const send = (m) => parent.postMessage(m, "*");
  addEventListener("message", (e) => {
    if (e.data?.type === "pelty:response" && e.data.id === 1) document.getElementById("msg").textContent = e.data.body.message;
  });
  send({ type: "pelty:ready" });
  send({ type: "pelty:request", id: 1, method: "GET", path: "/api/v1/addons/my-addon/hello" });
  send({ type: "pelty:resize", height: document.body.scrollHeight });
</script>