Administration

Admin

The built-in admin is available at /nb-admin/.

The admin uses DaisyUI components. The following shortcodes from core/modules/admin/lib/ handle data loading for admin views:

• [#get-resource-records resource=users role=table#] - loads all records + table-filtered fields into data.records and data.fields
• [#get-resource-record resource=users uuid=abc123#] - loads a single record for editing, with i18n and encryption handling
• [#get-resource-meta resource=users#] - loads only field definitions into data.fields

The legacy _dep_ admin UI has been removed. Active admin routes and templates live in the non-_dep_ admin paths.

Dashboard

/nb-admin/ ([#dashboard#], core/modules/admin/lib/dashboard/) is organized around what a user needs to act on, not one card per subsystem. It renders up to five bands, plus any application bands, each present only when it has something to show for the current user's role:

• Needs attention - failed jobs, a recent fatal error, low disk space, or (for pull-core-updates) stale assets: core changed build inputs (css/, js/, Tailwind config, package*.json, core templates, scripts, styles, text or static files) since the commit in ext/static/app.core, so app.css/app.js need a rebuild. app_build_stale() in core/lib/app-build.php decides; a missing stamp or unknown commit never warns. The git-pull API returns the same flag as assets_stale. Absent entirely if the role has none of the relevant view-* features.

• Site status - is the site current and healthy, in one glance. Every item follows the same shape: a dark, small uppercase label (Data/Core/Ext/System), then the one fact that actually answers "is this OK" rendered large but in a lighter tone (so labels anchor the eye and values don't shout), with supporting detail as a small caption underneath. For Data, the large fact is when ("18 hours ago", with the specific resource named in the caption below it - e.g. "Projects updated" - so it's directly checkable against the matching row in Your data, not an anonymous number). For Core/Ext, the large fact is status ("Up to date" or "N updates", amber when something's pending), with the raw "Updated X ago" timestamp demoted to the caption, plus an inline Update now for roles with pull-core-updates/pull-ext-updates. For System (view-debug), the large fact is a plain-language status - "OK" or "Low resources" (below 1GB RAM or 500MB disk free) - with the actual RAM/disk numbers as the caption and a View debug link into /nb-admin/debug. Everything here is a fact (with an action attached where one applies), never bare navigation - that's what Manage below is for.

• Visits - for roles with view-stats: visits, pageviews and bot/scanner requests over the last 30 days with the change against the 30 days before, and one bar per day (today partial, from the running log). PHP passes UTC hourly counts from stats_recent_days() in core/lib/stats.php; the dashboard_stats Alpine component groups them into the viewer's local days. See Request statistics.

• Application bands - every ext/tpl/dashboard-band.tpl and ext/modules/<name>/tpl/dashboard-band.tpl, rendered after Visits in name order (dashboard_app_bands()). This is how an application or ext module adds its own card without touching core. The template decides its own visibility (render nothing when the user may not see it) and uses the same section styling as Visits.

• Your data - the resources the current role can see, with record counts, disk usage, and last-updated time per resource.

• Manage - a section card like the others (rounded-2xl bg-neutral-50 p-6 shadow, same heading style as Your data), containing grouped clusters, one per resource, laid out with equal height (items-stretch on the row) so the row reads as one set rather than cards of mismatched size. Each cluster follows a strict internal order: a dark small uppercase heading, a caption fact (same text-neutral-500 as Site status), then - only if the cluster genuinely has one - its single most important pill (e.g. Media Library (N), Jobs (N), or Add user when a cluster's main draw is a create action rather than a list), and finally a secondary row where everything else (remaining entry pills like Users (N)/Roles (N), plus every other action) renders as plain underlined text links, all sharing one canonical link style (dashboard_secondary_link_class() in dashboard.php, reused as-is by the Site status "Update now"/"View debug" links and every quick-action-*.tpl partial - one style everywhere, not a per-context variant). A cluster has exactly one pill-weight element, never two competing for attention:

  • Users & roles: "N active sessions" caption, Add user pill (the create action is the main reason to visit this cluster), then Users (N) / Roles (N) / Sign out everyone (N) as secondary text links.
  • Media library: "Updated X ago" caption (the library's own last-modified time), Media Library (N) pill, then Clear thumbnail cache / Delete unused media as secondary text links.
  • System: "Scheduler last ran" caption, Jobs (N) pill (N = currently queued jobs - Jobs lives here, not its own cluster, since queue/scheduler and general site maintenance are the same "background infrastructure" concern), then Run jobs now / Clear data cache as secondary text links and View system log for roles with view-system-log. Data cache (ext/data/.tmp/cache/_data, the per-resource data_read_all() result cache from core/lib/data.php - normally self-invalidating on resource modification, but clearable here for troubleshooting) lives here rather than in Media library - it's a site-wide cache, not a media one, even though thumbnail cache (media-specific, ext/static/_thumb_) does belong in Media library.

  "Add role" is deliberately not a cluster action - not a daily action, so Roles is a plain secondary link, not a create button. The System cluster doubles as the only entry point into /nb-admin/jobs anywhere in the admin. Site settings is not a Manage cluster - it has no fact of its own to show, so it's a small gear-icon button in the dashboard's own header (top-right, core/modules/admin/uri/nb-admin/dashboard-settings-btn.tpl, gated on edit-.config) instead.

  Needs attention's items follow a similar "fact, then a light secondary pill action" shape (core/modules/admin/lib/dashboard/attention.tpl) - no em dashes separating message from action; the action sits on its own line below the message instead.

  Every Site status item and Manage cluster heading (dashboard_status_heading() in dashboard.php) uses the project's actual brand color (text-primary, from ext/tailwind.theme.js) rather than plain gray - one consistent accent, not a different hue per category. A per-category rainbow was tried and rejected (read as visual noise); a small colored icon badge per heading was also tried and rejected (it indented the label relative to the caption/value below it, breaking the column's flush-left edge). text-primary stays reserved for these headings only - amber/red keep their separate meaning (attention/warning) elsewhere on the page.

Users, Roles, and Media Library are not in the nimblybar's Resources sidebar dropdown (core/tpl/nimblybar/menu-resources.tpl) - that list shows only the project's own ext-defined resources. Users/Roles/Media Library are reachable from the dashboard's Manage clusters instead, keeping the sidebar scoped to "this project's data."

Roles and permissions editor

/nb-admin/roles/(id) and /nb-admin/roles/add share one permissions matrix component (core/modules/admin/lib/role-permissions/, [#role-permissions [#role-id#]#] / [#role-permissions new#]) so the add and edit flows never drift apart. The matrix renders one row per resource (including the hidden .content, .config, .files, .jobs resources) with per-operation checkboxes plus a manage-<resource> column, and a separate (all) toggle for super-admin roles. Unchecking (all) never clears the individual checkboxes underneath - they are only hidden while (all) is active, so switching it off restores whatever was set before.

Identity (name/description) and permissions are saved together from a single form (core/modules/admin/lib/role-identity/) via one PUT/POST to the generic /api/v1/roles endpoint - there is no separate role-permissions API. The client (matrix-sync.js) collapses a row's checked operations into manage-<resource> when every operation is checked, and builds the final comma-joined features string sent as a plain field alongside the role's name/description.

.files_meta, files_unused and files_usage are not resources with their own row in the matrix - they are internal, derived data. permission_normalize_hidden_alias() (core/modules/user/lib/permissions.php) aliases them to .files, so granting a role any operation on the Files row also covers file metadata lookups, the unused-file check and the "Used in" filter the media picker relies on. Do not add separate matrix rows or permission tokens for them.

Jobs and Site settings

/nb-admin/jobs (core/modules/admin/lib/jobs-panel/) is a diagnostic view over the job queue and scheduler - queued/running/done/failed counts, a table of jobs with their last error, and "Run due jobs now" / "Prune old jobs" actions, gated on view-.jobs / manage-.jobs. "Prune old jobs" removes both done jobs (aged off completed_at) and terminally failed jobs with no retries left (aged off _modified) older than 30 days - the same rule the scheduled jobs:prune --days=30 task applies, so a fixed-and-forgotten failure eventually drops off the Needs attention band on its own. Each done/failed row also has its own Delete button (gated on manage-.jobs) for clearing an individual job immediately regardless of age - queued/running rows show it disabled, since deleting an in-flight job could orphan a lock or a running process.

/nb-admin/settings (core/modules/admin/lib/site-settings/) is one flat page gated on edit-.config. It edits the site-wide .config/site record: name, description, languages, text direction (direction, ltr/rtl, rendered as <html dir>) and admin sidebar position (nimblybar.side). Name, description, direction and side are per-language values, and each field has its own language switch. On save, direction and side are filled in for every site language: Arabic, Persian and Hebrew start rtl with the sidebar on the right, and other languages start ltr and left. For users with manage-system, it also holds the custom pages switch with its page types, and the navigation editing switch (.config/managed_pages). Each switch shows only when there is a pages resource or navigation slots to switch on. Pages appear under Resources in the Nimbly bar; the Navigation admin tab is hidden for everyone while its switch is off. This is distinct from the per-page title editor behind the nimblybar gear icon, which edits page_settings.page_title for the current page only.

Resource record switcher

Generic resource edit pages (/nb-admin/(resource)/(id)) include a record switcher (core/modules/admin/lib/resource-switcher/) so an editor can jump between records without going back to the list. It picks a UI based on record count: a handful of records render as pills, up to ~100 render as a native <select> (browsers already support type-ahead-to-jump), and beyond that it switches to a debounced live-search input backed by resource_get()'s search/limit GET params (core/modules/api/lib/api.php) rather than loading every record client-side.

---

Rich content fields: end-to-end

This section shows the full flow for an editable HTML field: resource definition → template output → inline admin editing.

Step 1: Define the field in .meta

"intro": {
  "name": "Intro",
  "type": "html",
  "buttons": "bold,italic",
  "admin_col": false,
  "i18n": true
},
"body": {
  "name": "Body",
  "type": "html",
  "buttons": "h2,h3,h4,bold,italic,orderedlist,unorderedlist,quote,anchor",
  "media": true,
  "media_sizes": "sm-90,md-70,lg-60,xl-50,xxl-40",
  "admin_col": false,
  "i18n": true
}

• buttons is mandatory - always specify the exact toolbar buttons needed
• media: true enables the media browser; requires media_sizes
• admin_col: false is mandatory for html fields (too large for table view)
• Add i18n: true if the site is multi-language

Step 2: Load the record in route.inc

<?php
router_deny();
$parts = router_match(__FILE__);
if ($parts === false) return;
load_library('data');
$record = data_read('articles', $parts[0]);
if (!$record) return;
set_variable('article', $record);
router_accept();

Step 3: Output in the template

Use [#get-html#] to output an editable html field. When a logged-in admin views the page, the field becomes inline-editable directly in the frontend.

<div class="prose">
  [#get-html article.intro#]
</div>

<div class="prose prose-lg">
  [#get-html article.body#]
</div>

For multi-language content, [#get-html#] resolves i18n field objects automatically. Add a language suffix when you explicitly need one language:

[#get-html article.body#]
[#get-html article.body.nl#]

Step 4: Enable inline editing

Add [#html#] to the route and ensure the user module is active (auto-loaded). Logged-in editors (edit-inline-content) then get the page actions pill: Edit switches inline editing on and off (asking to save or discard unsaved changes), and the settings button opens page settings or the record's admin page (page-settings-link). The pill can be dragged anywhere and docks in a corner when dropped near one. While editing, the focused field shows its field bar with Save.

Inline editing attributes

For finer control over the inline editor (e.g. different toolbar than the .meta default, or to enable media on a field that doesn't have it in .meta), add data-nb-edit directly to a wrapper element:

<div data-nb-edit="event.[#record.uuid#].main_text" data-nb-edit-options='{
    "buttons":"h2,h3,bold,italic,anchor",
    "media": true,
    "media_sizes":"md-70,lg-60"}'>
  [#get-html record.main_text#]
</div>

For inline image replacement, use data-nb-edit-img on the image wrapper:

<div data-nb-edit-img="event.[#record.uuid#].main_img">
  [#get-img-html [#record.main_img#] sizes="xs-100,md-50"#]
</div>

Both attributes only activate for logged-in admins. The value format is resource.uuid.field.

---