SIGNALS Docs
Exit Reader View
100%
Theme

Plugin UI

Config-driven plugin UI — slot types, isolation, permission gating, live slot names, modal slots, palette providers, recents API, notifications, navItem(), generated settings form, and the no-plugin-views rule.

Philosophy — no plugin-shipped views

Plugins never ship Blade views. UI extension is config-driven:

  1. Declare a slot in signals.yaml slots[].
  2. Register a core Blade component name, Livewire component name, or trusted HTML producer via PluginRegistrar::slot().
  3. Optionally add navigation with navItem().
  4. Settings UI is generated from the manifest by core (PluginSettingsForm).

Slot component types

App\Sdk\Slots\SlotComponentType:

Case Value Meaning
View view Core Blade component name + data callable → props array
Html html Callable returning a trusted HTML string
Livewire livewire Core Livewire component name + params callable
public function slot(
    string $slot,
    SlotComponentType $type,
    string $component,
    ?callable $data = null,
    int $priority = 50,
    ?string $permission = null,
    ?string $group = null,
    ?int $refreshSeconds = null,
): self

Manifest gate: slot + component pair must match an entry in slots[].

Live slot names

The following supported names are wired into core Blade hosts. The drift test compares this table with the runtime slot inventory:

Slot Host view
rental.detail.header_actions resources/views/livewire/rentals/partials/rental-header.blade.php
rental.detail.tabs …/rentals/partials/rental-tab-strip.blade.php
account.detail.header_actions resources/views/livewire/accounts/partials/account-header.blade.php
account.detail.tabs …/accounts/partials/account-tab-strip.blade.php
invoice.detail.header_actions resources/views/livewire/invoices/partials/invoice-header.blade.php
invoice.detail.tabs …/invoices/partials/invoice-tab-strip.blade.php
activity.detail.header_actions resources/views/livewire/activities/show.blade.php
catalogue_item.detail.header_actions resources/views/livewire/catalogue-items/partials/catalogue-item-header.blade.php
catalogue_item.detail.tabs …/catalogue-items/partials/catalogue-item-tab-strip.blade.php
asset.detail.header_actions resources/views/livewire/assets/partials/asset-header.blade.php
asset.detail.tabs …/assets/partials/asset-tab-strip.blade.php
credit_note.detail.tabs …/credit-notes/partials/credit-note-tab-strip.blade.php
payment.detail.tabs …/payments/partials/payment-tab-strip.blade.php
virtual_stock.detail.header_actions resources/views/livewire/virtual-stock/show.blade.php
asset_retirement.detail.header_actions resources/views/livewire/asset-retirements/show.blade.php
warehouse_transfer.detail.header_actions resources/views/livewire/warehouse-transfers/show.blade.php
fleet_vehicle.detail.header_actions …/fleet/partials/vehicle-header.blade.php
fleet_vehicle.detail.tabs …/fleet/partials/vehicle-tab-strip.blade.php
flightcase.detail.tabs …/flightcases/partials/flightcase-tab-strip.blade.php
rental_project.detail.tabs …/projects/partials/project-tab-strip.blade.php
flightcase.detail.header_actions resources/views/livewire/flightcases/show.blade.php
stock_check.detail.header_actions resources/views/livewire/stock-checks/show.blade.php
equipment_test.detail.header_actions …/equipment-tests/partials/equipment-test-header.blade.php
equipment_test.detail.tabs …/equipment-tests/partials/equipment-test-tab-strip.blade.php
equipment_test_result.detail.header_actions resources/views/livewire/equipment-test-results/show.blade.php
repair.detail.header_actions …/repairs/partials/repair-header.blade.php
repair.detail.tabs …/repairs/partials/repair-tab-strip.blade.php
purchase_order.detail.header_actions resources/views/livewire/purchase-orders/partials/purchase-order-header.blade.php
purchase_order.detail.tabs …/purchase-orders/partials/purchase-order-tab-strip.blade.php
catalogue_item_groups.index.actions …/catalogue-item-groups/partials/toolbar.blade.php
credit_notes.index.actions …/credit-notes/partials/toolbar.blade.php
payments.index.actions …/payments/partials/toolbar.blade.php
dispatch.board.actions resources/views/livewire/dispatch/board.blade.php
returns.board.actions resources/views/livewire/returns/board.blade.php
scanning.console.actions resources/views/livewire/scanning/console.blade.php
notifications.panel.actions resources/views/livewire/notifications/pane.blade.php
dashboard.widgets resources/views/livewire/dashboard/dashboard-board.blade.php
modals.global resources/views/components/layouts/app/header.blade.php (once, beside the confirm modal)

There is no DB seed of slot names — the registry is in-memory at boot. Additional hosts may be added in core over time; declare only slots that exist in a Blade host.

Blade host

{{-- Free-form surfaces (widgets, boards, modals, index toolbars) --}}
<x-signals.plugin-slot name="dashboard.widgets" :context="[]" />

{{-- Detail tabs: native strip links + panel host at /{entity}/{id}/tabs/{key} --}}
<x-signals.module-tabs
    :tabs="$coreTabs"
    :active="$activeTab"
    plugin-slot="rental.detail.tabs"
    :plugin-context="['rental' => $rental, 'activeTab' => $activeTab]"
    plugin-tab-route-name="rentals.plugin-tab"
    :plugin-tab-route-params="[$rental]"
/>

{{-- Detail header actions: merge into the page Actions menu --}}
<x-signals.actions-menu
    size="sm"
    plugin-slot="rental.detail.header_actions"
    :plugin-context="['rental' => $rental]"
>
    {{-- core actions --}}
</x-signals.actions-menu>

Detail tab Html should return either a panel HTML string or ['key' => '…', 'label' => '…', 'content' => '…']. The host builds the tab link and renders content in the entity tab panel via <x-signals.plugin-tab-panel>. Detail header-action Html should emit s-dropdown-item markup so those look native inside the Actions menu.

rental.detail.tabs is arranged into grouped menus. A plugin tab may join one by passing the optional group argument to PluginRegistrar::slot(), or by returning group (also accepted as tab_group) in its data payload. Payload metadata takes precedence over the registration argument. The supported keys are plan, fulfil, finance, docs, and more; an absent or unsupported value falls back to more. This metadata is specific to the rental tab host; other *.detail.tabs hosts continue to render their established flat strips.

$registrar->slot(
    'rental.detail.tabs',
    SlotComponentType::Html,
    'AcmeRentalFinance',
    static fn (): array => [
        'key' => 'acme-finance',
        'label' => 'Acme Finance',
        'content' => '<div>…</div>',
    ],
    group: 'finance',
);

Isolation

SlotRenderer::render() catches per-component Throwable, logs, and continues with sibling components — one failing plugin does not blank the page.

Priorities: ascending (lower first), default 50 — same ordering idea as hooks.

Permission gating

If permission is set on the registration (or declared on the manifest slot), SlotRenderer skips the component unless Auth::user()?->can($permission).

Ledger example:

$registrar->slot(
    'dashboard.widgets',
    SlotComponentType::View,
    'signals.stat-card',
    static fn (PluginContext $context, array $slotData): array => ['label' => 'Details', 'value' => 'Ready'],
    70,
    'signals.ledger.view',
);

Global modal slots

Plugins may register modals on the reserved slot modals.global. Core renders that slot once in the app shell (beside the confirm modal). Declare the slot in the existing slots[] section — no new manifest section:

slots:
  - slot: modals.global
    component: signals.plugin-modal   # or a custom Html component name
// Config-driven Flux modal (core component)
$registrar->slot(
    'modals.global',
    SlotComponentType::View,
    'signals.plugin-modal',
    static fn (): array => [
        'name' => 'acme-jobs-modal',   // unique Flux modal name
        'title' => 'Field jobs',
        'sections' => [
            ['type' => 'stat-grid', 'data' => [['label' => 'Open', 'value' => '4', 'color' => 'green']]],
            ['type' => 'table', 'data' => ['columns' => ['Job'], 'rows' => [['Install']]]],
            ['type' => 'html', 'data' => '<p>Trusted HTML</p>'],
        ],
    ],
    50,
    'acme.example.view',
);

// Or fully custom markup (same Html trust model as other slots)
$registrar->slot(
    'modals.global',
    SlotComponentType::Html,
    'AcmeCustomModal',
    static fn (): string => '<div data-flux-modal>…</div>',
);

Open a modal from any plugin surface (header action Html slot, page section, palette entry) with a plain Flux dispatch:

<button type="button" x-on:click="$dispatch('modal-show', { name: 'acme-jobs-modal' })">
  Open jobs
</button>

Or from JavaScript: window.Flux.modal('acme-jobs-modal').show().

Navigation is not a slot:

public function navItem(array|NavigationItem $item): self

Not manifest-gated. Use for sidebar / admin nav entries that point at core routes or external URLs as supported by NavigationItem.

Set show_in_palette => true to include the item in the command palette (via NavigationService::paletteCommandsFor()). Plugin enable/disable busts the navigation:* cache so sidebar lists stay fresh on the next boot cycle.

Command palette providers

For dynamic palette entries (not static navItems), register a provider:

$registrar->paletteCommands(static fn (): array => [
    [
        'key' => 'acme.open-jobs',
        'label' => 'Open Acme Jobs',
        'url' => '/plugins/acme/example/jobs',
        'icon' => 'briefcase',          // optional
        'group' => 'Acme',              // optional — defaults to plugin name
        'keywords' => 'jobs field',     // optional
        'permission' => 'acme.example.view', // null or a declared permissions[] key
    ],
]);

There is no new manifest section for palette providers — they are gated only by the plugin being enabled (disabled packages never boot). When the registrar is scoped, each command's permission must be null or one of the plugin's declared permissions[]; undeclared permissions are skipped (logged) at query time. Providers are failure-isolated like slots.

Entries merge into NavigationService::paletteCommandsFor() at query time (not cached). That resolution happens only when the palette is actually opened — the UI fetches GET /palette/commands on first open — so a provider is never invoked during an ordinary page render.

Recents API

The examples use the injected PluginContext $context; use $this->context() in a lifecycle method or PluginContext::forPackage() in a class-based extension.

Push into the same recently-viewed repository core uses (recently_viewed_items → morph PluginRecentEntry):

$context->recent([
    'label' => 'Job #12',
    'url' => '/plugins/acme/example/jobs', // must start with /
    'icon' => 'briefcase',                 // optional
    'type' => 'Acme Example',              // optional — defaults to plugin name
]);

// From a hook handler:
$context->recent(['label' => 'Job #12', 'url' => '/plugins/acme/example/jobs']);

Guards: plugin must be enabled; URL must be an internal path starting with / (external / protocol-relative URLs rejected). Entries appear in the search palette's Recently viewed list (and the matching list page's Recently viewed menu, if it has one). The SDK sets no cap of its own: each user, plugin and URL is one entry, refreshed in place on each push. The palette shows the eight newest records, and the nightly signals:recently-viewed:prune keeps the newest 50 per user by default.

Top-level nav groups & plugin pages

A plugin may declare one top-level nav group (nav) plus config-driven UI pages (pages[]) in signals.yaml — see the manifest reference. Runtime wiring is manifest-gated:

// Group must match nav.group / nav.icon; every item must match a declared nav.items[] entry.
$registrar->navGroup('Field Ops', 'map', [
    ['key' => 'jobs', 'label' => 'Jobs', 'page' => 'jobs', 'permission' => 'acme.fieldops.view'],
]);

// Key must match a declared pages[] entry; the provider supplies section data
// keyed by section index (or section type as a fallback).
$registrar->page('jobs', fn (PluginContext $context, array $pageData): array => [
    // sections[0] type stat-grid → list of ['label', 'value', 'color' (blue|green|amber|violet)]
    [['label' => 'Open Jobs', 'value' => '12', 'color' => 'green']],
    // sections[1] type table → ['columns' => list<string>, 'rows' => list<list<scalar>>] (values escaped)
    ['columns' => ['Job', 'Status'], 'rows' => [['Install rig', 'Scheduled']]],
    // sections[2] type html → trusted HTML string (same trust model as Html slots)
    '<p>Summary</p>',
]);

page() requires a plugin-scoped registrar — page metadata (title, layout, sections) comes exclusively from the manifest.

datatable sections

A fourth section type, datatable, renders a registered listing table instead of provider data:

pages:
  - key: jobs
    title: Jobs
    sections:
      - type: stat-grid
      - type: datatable
        datatable: acme.fieldops.jobs   # a declared datatables[] key

The definition is the content, so the page's data provider supplies nothing for that index. Core mounts the shared components.data-table Livewire component with the definition's params, skips the section entirely for a viewer without the definition's permission, and logs-and-skips an unknown or unnamed key rather than breaking the page. Register the table with PluginRegistrar::datatable(), or render the same definition in a UI slot with datatableSlot() — see DataTable SDK.

Runtime behaviour:

  • Pages render at /plugins/{vendor}/{name}/{page} (route plugins.page) inside the console shell, with a group sidebar showing the same items (same order, same permissions) as the header dropdown.
  • The header group appears after Finance; each item is permission-gated and a group with no visible items is hidden.
  • Disabled plugin → 404; missing item permission → 403; a throwing data provider is logged and renders empty sections (failure isolation, like slots).

Notifications

Plugins declare sendable types in signals.yaml notifications[] (vendor-prefixed keys; channels ⊂ database / mail / broadcast). Rules: notifications.namespace, notifications.malformed.

notifications:
  - key: acme.sync.failed
    label: Sync Failed
    group: Acme
    channels: [database, mail]
    description: Fired when a sync fails.
$registrar->notification('acme.sync.failed', [
    'label' => 'Sync Failed',
    'group' => 'Acme',
    'channels' => ['database', 'mail'],
    'description' => 'Fired when a sync fails.',
]);

$context->notify('acme.sync.failed', $user, [
    'title' => 'Sync failed',
    'body' => 'Could not reach API.',
    'url' => '/plugins/acme/example/jobs', // internal path only
]);

// From a hook handler:
$context->notify('acme.sync.failed', $user, ['title' => 'Sync failed']);
  • Registrar wiring ⊆ notifications[]. Types land in NotificationRegistry and are seeded into notification_types on install/update so they appear in the user preference UI.
  • Delivery uses the generic queued PluginNotification on the notifications queue. Channels are resolved per user via NotificationChannelResolver (type defaults ∩ tenant settings ∩ preferences) — muted preferences skip send.
  • Guards: plugin enabled; key declared + registered; title required; url must start with /; inactive users skipped.

Generated settings form

Manifest settings[] drive Livewire PluginSettingsForm on the Plugins admin page. See Plugin settings.

Admin page presence

Route: /plugins (plugins.index); /admin/settings/plugins redirects here — Livewire PluginManager.

Tabs include installed package overview, permissions, data access, hooks, slots, settings, and tables, plus a read-only manifest viewer. Requires plugins.manage.

Contract: Slot Registry.

Worked example

A separately installed vendor/signals/slots-demo/ example can wire every surface on this page — one slot from each family, the global modal + open snippet, a nav group with two pages, a palette provider, a recents push, and a sendable notification. Annotated tour: Plugin examples.

Typed slot context (SDK 2.1)

Type the first callback parameter after an optional PluginContext as App\Sdk\Slots\SlotContext to receive validated record identity. Call recordId() for the required ID, read($context) for guarded record data, and attribute($key, $default) for a declared scalar attribute. SlotContext::forRecord($slot, $id, $attributes, $activeTab, $revision) builds a validated context for host code and tests.

Array callbacks continue to receive their existing keys, plus subject (type, entity, id) and slot_context. Raw model keys are deprecated and are not part of the supported guarded-data contract. Prefer typed context and read().

Invalid core host contexts throw in tests or with plugins.strict_slot_context enabled; otherwise they are logged and the slot is skipped. Custom slot names receive an unvalidated context with no record identity and a warning. The test harness provides slotContext() and accepts a typed context in renderSlot().

Slot Record Entity ID source Revision Tab Attributes
account.detail.header_actions account accounts account.id aggregate_version when present no
rental.detail.header_actions rental rentals rental.id aggregate_version when present no
invoice.detail.header_actions invoice invoices invoice.id aggregate_version when present no
activity.detail.header_actions activity activities activity.id aggregate_version when present no
catalogue_item.detail.header_actions catalogue_item catalogue_items catalogue_item.id aggregate_version when present no
asset.detail.header_actions asset assets asset.id aggregate_version when present no
virtual_stock.detail.header_actions virtual_stock — virtual_stock_intake.id aggregate_version when present no
asset_retirement.detail.header_actions asset_retirement — asset_retirement.id aggregate_version when present no
warehouse_transfer.detail.header_actions warehouse_transfer — warehouse_transfer.id aggregate_version when present no
fleet_vehicle.detail.header_actions fleet_vehicle vehicles vehicle.id aggregate_version when present no
flightcase.detail.header_actions flightcase — flightcase.id aggregate_version when present no
stock_check.detail.header_actions stock_check — stock_check.id aggregate_version when present no
equipment_test.detail.header_actions equipment_test — equipment_test.id aggregate_version when present no
equipment_test_result.detail.header_actions equipment_test_result — equipment_test_result.id aggregate_version when present no
repair.detail.header_actions repair — repair.id aggregate_version when present no
purchase_order.detail.header_actions purchase_order purchase_orders purchase_order.id aggregate_version when present no
account.detail.tabs account accounts account.id aggregate_version when present yes
rental.detail.tabs rental rentals rental.id aggregate_version when present yes
catalogue_item.detail.tabs catalogue_item catalogue_items catalogue_item.id aggregate_version when present yes
fleet_vehicle.detail.tabs fleet_vehicle vehicles vehicle.id aggregate_version when present yes
flightcase.detail.tabs flightcase — flightcase.id aggregate_version when present yes
asset.detail.tabs asset assets asset.id aggregate_version when present yes
credit_note.detail.tabs credit_note credit_notes credit_note.id aggregate_version when present yes
payment.detail.tabs payment payments invoice_payment.id aggregate_version when present yes
invoice.detail.tabs invoice invoices invoice.id aggregate_version when present yes
purchase_order.detail.tabs purchase_order purchase_orders purchase_order.id aggregate_version when present yes
repair.detail.tabs repair — repair.id aggregate_version when present yes
equipment_test.detail.tabs equipment_test — equipment_test.id aggregate_version when present yes
rental_project.detail.tabs rental_project — rentalProject.id aggregate_version when present yes
catalogue_item_groups.index.actions — — — — no
credit_notes.index.actions — — — — no
payments.index.actions — — — — no
dispatch.board.actions — — — — no warehouseId: ?int
returns.board.actions — — — — no warehouseId: ?int
scanning.console.actions — — — — no sessionId: ?int
notifications.panel.actions — — — — no unreadCount: int
dashboard.widgets — — — — no
modals.global — — — — no

Actions and forms in SDK 2.1

Section form renders a declared action inline; actions renders buttons opening core modals. connections renders declared credential controls. Use actionSlot() for declared matching record header actions. See Actions and forms.

Maps

A map page section accepts the signals.map component's props from the provider under its section key: markers, height, fit, center, zoom, staleAfterSeconds, emptyText and label. Markers can be MapMarker objects or arrays with id, lat, lng, label, optional status, updatedAt, relative url, group and plain-text detail. Status is fresh, stale, offline or unknown. Core validates coordinates, limits the first 1000 entries, escapes text and drops non-relative URLs. Fresh locations become stale after the tenant threshold; offline/unknown remain unchanged. Links must start /, never //.

The table fallback is always available to assistive technology and can be displayed with Show as list. Disabled tiles or a failed loader leave the table visible. Tenant settings choose the tile provider. The current shared loader pins Leaflet 1.9.4 with SRI and anonymous cross-origin requests; no package dependency is added. Viewport coordinates are visible to the tile provider. High-volume fleets should use tenant-operated tiles. Initial fit sets the bounds; subsequent marker updates retain the user's viewport and do not refetch tiles.

Section refresh and polling

pages:
  - key: locations
    title: Locations
    sections:
      - {type: map, key: fleet, refresh_seconds: 60}

Keys are unique slugs. Refresh intervals are 15–3600 seconds. Core calls the page provider with ['package' => $package, 'page' => $page, 'section' => 'fleet', 'refresh' => true] and takes the fleet key from its response. A full response or only that keyed section is accepted. Initial rendering still accepts index/type keys after checking the section key first.

Polling occurs only while visible and pauses in hidden tabs. Every refresh checks plugin enabled status and nav permission; the server throttles each tenant/user/package/page/section until interval minus two seconds. Failed providers keep the last good data with an update notice. Slot providers opt in with the trailing refreshSeconds parameter on slot(); the core island reconstitutes its locked record context and checks the record view policy on every poll.

Providers must be idempotent and cheap. Use $context->remember() for upstream reads, never assume a poll happened, and supply timestamps so core can compute stale state. SDK 2.1 has no websocket or streaming contract for these sections. The sandbox helper refreshSection($page, $sectionKey) invokes the same guarded refresh and returns the section's data array.