Struct AdminPlugin 

pub struct AdminPlugin { /* private fields */ }

Implementations

impl AdminPlugin

pub fn register(self, model: AdminModel) -> Self

Register an AdminModel for one model. Chainable.

If two configs are registered for the same table the last one wins (a duplicate registration overwrites the earlier one).

The plugin name defaults to "admin" for models registered before the plugin is installed into the app. From M7+ plugins will pass their own name via Plugin::admin_register on the registry.

pub fn register_many(self, models: impl IntoIterator<Item = AdminModel>) -> Self

Register many AdminModels at once — the batch form of register. Lets each plugin export a Vec<AdminModel> (its admin surface, declared next to its models) and the app register them in one call instead of a .register(...) per model in main.rs.

// plugins/blog/src/lib.rs
pub fn admin_models() -> Vec<umbral_admin::AdminModel> {
    vec![post_admin(), comment_admin(), tag_admin()]
}

// main.rs
AdminPlugin::default().register_many(blog::admin_models())

pub fn register_for(self, plugin_name: &str, model: AdminModel) -> Self

Register an AdminModel for a specific plugin name.

This is the method the Plugin::routes / on_ready pathway uses when a plugin contributes its own admin registrations. The sidebar groups models by the plugin_name supplied here.

pub fn register_for_many( self, plugin_name: &str, models: impl IntoIterator<Item = AdminModel>, ) -> Self

Batch form of register_for — register many models under one plugin name (the Plugin-pathway batch entry).

pub fn register_widget(self, widget: Widget) -> Self

Register a dashboard widget. Chainable.

Example

use umbral_admin::{AdminPlugin, Widget, WidgetKind, WidgetDataFn, WidgetPayload, KpiPayload, Span};

AdminPlugin::default()
    .register_widget(Widget {
        key:          "total_posts",
        title:        "Total Posts".to_string(),
        kind:         WidgetKind::Kpi,
        default_span: Span { cols: 3, rows: 1 },
        permission:   None,
        data:         WidgetDataFn::new(|_user| async move {
            WidgetPayload::Kpi(KpiPayload {
                value: "0".to_string(),
                unit: None, delta: None, sparkline: None,
            })
        }),
    });

pub fn site_title(self, title: impl Into<String>) -> Self

Override the admin site title — shown in the browser tab, the sidebar header, and the login page.

AdminPlugin::default().site_title("Acme Backoffice")

pub fn site_description(self, description: impl Into<String>) -> Self

One-line description shown on the dashboard / login page underneath the site title.

pub fn show_version(self, show: bool) -> Self

pub fn version(self, label: impl Into<String>) -> Self

Show YOUR version instead of umbral’s (gaps3 #67).

AdminPlugin::default().version(concat!("MyShop v", env!("CARGO_PKG_VERSION")))

The default advertises the framework — which is what the operator of a shop almost certainly does NOT want on their staff login page. Whose version an admin shows is a product decision, so it is yours to make. Implies show_version(true).

Prefer env!("CARGO_PKG_VERSION") over a literal: a hardcoded version is a lie waiting for the next release, which is exactly how the admin came to claim v0.0.1 five releases after it stopped being true.

pub fn brand_color(self, color: impl Into<String>) -> Self

Override the brand primary color. Accepts any valid CSS color (#5b5bd6, rgb(91 91 214), hsl(240 60% 60%)). The wrapper template emits a <style> that re-assigns --primary and --primary-container so every “primary”-tinted element across the admin picks it up automatically.

pub fn at(self, path: impl Into<String>) -> Self

Gap 107: mount the admin at a path other than the default /admin. Useful when a single domain hosts multiple umbral admins, or when the operations team enforces a different vanity URL. Accepts "/myadmin", "myadmin", or "/myadmin/" — all normalise to "/myadmin".

AdminPlugin::default().at("/backoffice")
// → routes mount at /backoffice/login, /backoffice/{table}/, ...

Templates read the configured base via the admin_base Jinja global, so cross-page links resolve to the new path automatically. Handler-side redirects and sanitise_next also use the configured base.

pub fn base_path(&self) -> &str

The normalised admin base path. Public so plugin authors and the OpenAPI plugin can reference it.

pub fn dashboard_models_hidden(self) -> Self

Hide the dashboard’s “Models” cards section entirely. Use when the operator’s primary view is widget-driven and a long model grid would be noise (200-model enterprise installs, single-purpose admins, etc.).

AdminPlugin::default().dashboard_models_hidden()

pub fn dashboard_models_only<S: Into<String> + Clone>( self, tables: &[S], ) -> Self

Show only a curated subset of models on the dashboard, in the given order. Unknown table names are dropped silently (typo-safe — if one plugin is unregistered the rest still render).

AdminPlugin::default().dashboard_models_only(&[
    "product", "order", "customer",
])

Type-safe alternative coming in a follow-up: a models![Product, Order, Customer] macro that resolves each type to its Model::TABLE so a rename in the struct doesn’t require updating string references here.

pub fn dashboard_models_all(self) -> Self

Explicit reset to the default — show every registered model. Useful when a wrapper builder has previously configured a subset / hidden and you want the full grid back.

pub fn dashboard_section(self, section: WidgetSection) -> Self

Append a named widget section to the dashboard. Sections render in registration order, each with its own heading

• (optional) subtitle + widget grid:

AdminPlugin::default()
  .dashboard_section(
      WidgetSection::new("Sales overview")
          .subtitle("Daily KPIs across the storefront")
          .widget(shop_total_sales_widget())
          .widget(shop_orders_widget()))
  .dashboard_section(
      WidgetSection::new("Engagement")
          .widget(umbral_admin::builtin_recent_users_widget()))

Widgets registered via the legacy register_widget(...) land in an implicit final section titled “Widgets” so pre-existing apps keep working without refactor.

pub fn dashboard_section_at(self, index: usize, section: WidgetSection) -> Self

Insert a section at a specific position in the dashboard. Useful when a wrapper builder appended sections earlier and you want a new one above them. index is clamped at the current section count, so usize::MAX is equivalent to Self::dashboard_section.

AdminPlugin::default()
  .dashboard_section(sales_section)
  .dashboard_section(system_section)
  // Slot a new section between the two:
  .dashboard_section_at(1, alerts_section)

pub fn dashboard_models_title(self, title: impl Into<String>) -> Self

Override the heading shown above the model-cards section. Default “Models”. Pair with dashboard_models_subtitle for a one-line explainer.

pub fn dashboard_models_subtitle(self, subtitle: impl Into<String>) -> Self

Optional one-line caption under the model-cards heading.

pub fn restore_last_path(self, enabled: bool) -> Self

Control whether the admin “restore where I left off” feature is active (default: true — on by default, opt out to disable).

When enabled (true, the default):

• /admin/ 302-redirects to the last-visited changelist URL stored in admin_user_pref.preferences.last_path.
• The changelist handler writes last_path on every page visit.
• The “Home” breadcrumb carries ?dashboard=1 so the dashboard is reachable in one click (the escape hatch becomes a UI affordance).

When disabled (false):

• /admin/ always renders the dashboard directly.
• The changelist handler skips the last_path write — no dead data accumulates in admin_user_pref.preferences.

AdminPlugin::default().restore_last_path(false)

pub fn view(self, view: AdminView) -> Self

Register a custom admin view — a widget page mounted at {admin_base}/{view.path}. Chainable.

AdminPlugin::default().view(
    AdminView::new("reports/sales", "Sales report")
        .with_icon("bar-chart")
        .section(WidgetSection::new("This month").widget(revenue_kpi())),
)

pub fn views(self, views: impl IntoIterator<Item = AdminView>) -> Self

Batch form of view.

Trait Implementations

impl Clone for AdminPlugin

fn clone(&self) -> AdminPlugin

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AdminPlugin

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AdminPlugin

fn default() -> Self

Returns the “default value” for a type.

impl Plugin for AdminPlugin

fn name(&self) -> &'static str

A stable identifier. Used as the key in the migration tracking table, in dependency lists, and as the directory name under migrations/. Plugin names live in the same namespace as migrate::APP_PLUGIN_NAME ("app"), so user crates must not pick the name "app".

fn dependencies(&self) -> &'static [&'static str]

Names of plugins that must load before this one. The App::builder() topological sort uses this; cycles surface as BuildError::PluginCycle. The default is no dependencies.

fn static_files(&self) -> Vec<StaticFile>

Static files the plugin ships baked into its binary.

fn static_dirs(&self) -> Vec<StaticDir>

On-disk source directories this plugin contributes to the unified static pipeline.

fn models(&self) -> Vec<ModelMeta>

The plugin’s models, in declaration order. The M7 migration engine collects these across every registered plugin and uses them as the diff target for makemigrations.

fn routes(&self) -> Router

The plugin’s HTTP routes. Merged into the app router after the hand-written one passed to AppBuilder::routes(). Plugins choose their own path prefixes (spec 02 §“What a plugin can contribute”: routes are flat, not auto-prefixed).

fn route_paths(&self) -> Vec<RouteSpec>

Declared URL routes this plugin contributes — a companion to routes used for surfacing route lists outside the request flow (currently: the dev-mode default 404 page). axum doesn’t expose its internal route table, so plugins report what they declare here; the framework treats this as informational only — not a source of truth for routing.

fn on_ready(&self, _ctx: &AppContext) -> Result<(), PluginError>

Wire signals, start background work, seal admin registrations. Called after phase 4 (system checks) passes, in topological dependency order. Sync, on purpose; spawn async work via ctx.runtime() when the runtime handle lands.

fn openapi_paths(&self) -> Vec<(String, Value)>

OpenAPI path items the plugin contributes. Returned as a Vec<(path, value)> where path is the URL template (/api/auth/login, /api/foo/{id}) and value is the matching OpenAPI 3.0 Path Item Object serialised as a serde_json::Value.

fn system_checks(&self) -> Vec<SystemCheck>

Boot-time checks the plugin needs to pass. Run in phase 4 of App::build() alongside the framework’s built-in checks. Severity::Error blocks boot; Severity::Warning logs and continues.

fn provides_storage(&self) -> bool

true if this plugin registers a Storage backend (e.g. StoragePlugin, which calls crate::storage::set_storage in Plugin::on_ready).

fn database(&self) -> Option<&'static str>

The database alias every model this plugin contributes should be read from and written to. Returns None to use the "default" pool (the same one umbral::db::pool() returns).

fn templates_dirs(&self) -> Vec<PathBuf>

Template directories this plugin contributes.

fn template_registrars( &self, ) -> Vec<Box<dyn Fn(&mut Environment<'static>) + Sync + Send>>

Custom template tags / filters this plugin contributes (feature #67 - a loadable template tag/filter library).

fn wrap_router(&self, router: Router) -> Router

Wrap the app router with the plugin’s middleware layers.

fn middleware(&self) -> Vec<Arc<dyn Middleware>>

Framework-level request/response middleware this plugin contributes (feature #68).

fn static_root_dirs(&self) -> Vec<PathBuf>

On-disk directories served at the root of static_url — with no namespace segment.

fn commands(&self) -> Vec<Box<dyn PluginCommand>>

CLI subcommands the plugin contributes.

fn api_endpoints(&self) -> Vec<ApiEndpoint>

Callable HTTP endpoints this plugin wants advertised in a machine-readable index (e.g. a REST API root, or a client’s service-discovery fetch).