Admin UI kit: compact buttons, toolbars, badges, cards, sparklines

Every admin page of yf uses one look for its buttons: small, coloured by what they do, with a short label, and only an icon when the icon says it all (delete, edit, move). The category editor's row actions are the reference. The kit draws them, and the pieces the admin modules used to copy: badges, stat cards, inline SVG sparklines, compact tab bars and tables. It is _class('admin_ui') (class yf_admin_ui, plugin admin) and one CSS asset, yf_admin_ui, which the admin layouts load on every page (style_css). Bootstrap 3 and 5, light and dark.

Buttons

$ui = _class('admin_ui');
echo $ui->btn(t('Refresh now'), './?object=my_module&action=show', ['kind' => 'refresh', 'type' => 'primary']);
echo $ui->btn('', './?object=my_module&action=edit&id=' . $id, ['kind' => 'edit']);   // icon only, title "Edit"
echo $ui->btn('', './?object=my_module&action=delete', ['kind' => 'delete', 'post' => ['id' => $id], 'confirm' => t('Delete it?')]);
$class = $ui->btn_class('danger');   // for markup of your own: btn btn-xs btn-danger yf-btn (Bootstrap 3)

btn($label, $url, $opts) returns a link, a <button type="button"> when the URL is empty, or, with post (the hidden fields, or true for none), a POST form with the session token made by _class('admin_post')->post_form() (see admin_post). The label, the URL and every attribute are escaped. Options:

  • kind: the colour and icon of an action. delete is red and icon-only, active green, inactive yellow, edit / view / move / clone default and icon-only, add, refresh, back, download, docs default with their label, save blue, settings an icon. A site changes the map in $PROJECT_CONF['admin_ui']['KINDS']. Options you pass win over the kind.
  • type (default, primary, success, info, warning, danger), icon (a Font Awesome class), icon_only: an icon-only button always gets the label as title and aria-label;
  • title, class (more classes), btn_class (the whole class), attrs, target, html (the label is HTML); for POST also confirm (a link or plain button with confirm throws: an action worth a confirm is a POST), js, form_class, style, form_attrs, extra_html.
  • A URL must start with ./, /, #, http: or https:; anything else (javascript:, data:) becomes #.

The size is always the compact one: btn-xs under Bootstrap 3, btn-sm plus the kit class yf-btn under Bootstrap 5 (the padding and font size of Bootstrap 3's btn-xs).

HTML
<div class="yf-ui-toolbar" role="toolbar"><a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-default yf-btn yf-btn-icon" title="Move" aria-label="Move"><i class="fa fa-arrows" aria-hidden="true"></i></a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-default yf-btn yf-btn-icon" title="Clone" aria-label="Clone"><i class="fa fa-code-fork" aria-hidden="true"></i></a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-default yf-btn yf-btn-icon" title="Edit" aria-label="Edit"><i class="fa fa-edit" aria-hidden="true"></i></a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-danger yf-btn yf-btn-icon" title="Delete" aria-label="Delete"><i class="fa fa-trash" aria-hidden="true"></i></a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-success yf-btn"><i class="fa fa-check" aria-hidden="true"></i> Active</a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-warning yf-btn"><i class="fa fa-ban" aria-hidden="true"></i> Inactive</a></div>

A toolbar is a wrapping flex row with small gaps (toolbar($items, ['label' => ...])):

HTML
<div class="yf-ui-toolbar" role="toolbar" aria-label="Log tools"><a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-primary yf-btn"><i class="fa fa-refresh" aria-hidden="true"></i> Refresh now</a> <button type="button" class="btn btn-xs btn-success yf-btn"><i class="fa fa-clipboard" aria-hidden="true"></i> Copy as Markdown</button> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-default yf-btn"><i class="fa fa-download" aria-hidden="true"></i> Markdown</a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-default yf-btn"><i class="fa fa-download" aria-hidden="true"></i> JSON</a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-default yf-btn yf-btn-icon" title="Settings" aria-label="Settings"><i class="fa fa-cog" aria-hidden="true"></i></a></div>

POST buttons (the token field is in the HTML; these send the form to this page, so nothing changes):

HTML
<form method="post" class="yf-admin-post-form" action="./?object=docs&action=misc&id=admin_ui" data-confirm="Purge all caches now?" onsubmit="return confirm(this.getAttribute('data-confirm'))" style="display:inline"><input type="hidden" name="_token" value="67693a617acb5cf88ba611d91475e7536f5ad88eb820a88db6384572e2a60573"><input type="hidden" name="demo" value="1"><button type="submit" class="btn btn-xs btn-warning yf-btn"><i class="fa fa-recycle" aria-hidden="true"></i> Purge</button></form> <form method="post" class="yf-admin-post-form" action="./?object=docs&action=misc&id=admin_ui" data-confirm="Delete this entry?" onsubmit="return confirm(this.getAttribute('data-confirm'))" style="display:inline"><input type="hidden" name="_token" value="67693a617acb5cf88ba611d91475e7536f5ad88eb820a88db6384572e2a60573"><input type="hidden" name="id" value="0"><button type="submit" class="btn btn-xs btn-danger yf-btn yf-btn-icon" title="Delete" aria-label="Delete"><i class="fa fa-trash" aria-hidden="true"></i></button></form>

The rule for admin modules

  • Every admin button is compact: btn() / btn_class() of the kit, post_form() of admin_post (it uses the kit), table2 row and header buttons, html()->button() with 'size' => 'sm', or btn-xs in a template. No btn-lg, no button without a size.
  • Icon only when the icon is unmistakable (delete, edit, move, clone, settings), always with title and aria-label; a short label otherwise.
  • make admin-buttons (part of make hygiene and of the pre-commit hook) flags a non-compact button in admin modules, admin classes and admin templates; a justified exception (the confirm page, the 2FA login steps) is listed with its reason in scripts/zf_tools/admin_buttons.py.
  • Under Bootstrap 5 every btn-sm of the admin gets the compact size too, so table2 rows and older modules match. A site that wants the larger Bootstrap 5 size back sets $PROJECT_CONF['admin_ui']['BS5_COMPACT'] = false (kit buttons stay compact).
  • The admin layouts load the asset in style_css, and the kit's helpers load it once a request too. A site with its own admin style_css.stpl still adds {asset()} yf_admin_ui {/asset}, for the pages with no kit helper (a plain table2 list under Bootstrap 5).

Badges

echo $ui->badge('3 warnings', 'warning');   // label label-warning (Bootstrap 3), badge text-bg-warning (Bootstrap 5)
ok 3 warnings 2 critical off
HTML
<span class="label label-success">ok</span> <span class="label label-warning">3 warnings</span> <span class="label label-danger">2 critical</span> <span class="label label-default">off</span>

Stat cards and sparklines

echo $ui->cards([
    $ui->card(t('Last 24 hours'), (string) $n, $ui->sparkline($per_hour), $n ? 'warning' : 'ok'),
    $ui->card(t('Hit rate'), '99.2 %', t('of 1.2 M lookups'), 'ok'),
    $ui->card(t('Open the doctor'), '', t('the whole card is a link'), 'info', ['href' => 'https://yfix.net/doctor']),
], ['min' => 200]);

card($title, $value, $sub_html, $tone, ['class', 'href']): the title and value are escaped, the line under them is HTML of the caller; the tone (ok, warning, danger, info) colours the left edge. cards() lays them out in a grid (min: the smallest card width in px). sparkline($values, ['titles', 'label', 'width', 'gap', 'height', 'class']) draws the values as inline SVG bars in the text colour, with a tooltip per bar; no JavaScript, no jQuery.

Last 24 hours
92
013285129463710201469148532
Hit rate
99.2 %
of 1.2 M lookups
Errors
2
critical
Open the doctor
the whole card is a link
HTML
<div class="yf-ui-cards"><div class="yf-ui-card yf-ui-tone-warning"><div class="yf-ui-card-title">Last 24 hours</div><div class="yf-ui-card-value">92</div><div class="yf-ui-card-sub small"><svg class="yf-ui-spark" width="96" height="22" viewBox="0 0 96 22" role="img" aria-label="trend"><rect x="0" y="21" width="3" height="1" opacity="0.25"><title>0</title></rect><rect x="4" y="20" width="3" height="2"><title>1</title></rect><rect x="8" y="17" width="3" height="5"><title>3</title></rect><rect x="12" y="19" width="3" height="3"><title>2</title></rect><rect x="16" y="9" width="3" height="13"><title>8</title></rect><rect x="20" y="14" width="3" height="8"><title>5</title></rect><rect x="24" y="3" width="3" height="19"><title>12</title></rect><rect x="28" y="8" width="3" height="14"><title>9</title></rect><rect x="32" y="16" width="3" height="6"><title>4</title></rect><rect x="36" y="13" width="3" height="9"><title>6</title></rect><rect x="40" y="17" width="3" height="5"><title>3</title></rect><rect x="44" y="11" width="3" height="11"><title>7</title></rect><rect x="48" y="6" width="3" height="16"><title>10</title></rect><rect x="52" y="19" width="3" height="3"><title>2</title></rect><rect x="56" y="21" width="3" height="1" opacity="0.25"><title>0</title></rect><rect x="60" y="20" width="3" height="2"><title>1</title></rect><rect x="64" y="16" width="3" height="6"><title>4</title></rect><rect x="68" y="13" width="3" height="9"><title>6</title></rect><rect x="72" y="8" width="3" height="14"><title>9</title></rect><rect x="76" y="0" width="3" height="22"><title>14</title></rect><rect x="80" y="9" width="3" height="13"><title>8</title></rect><rect x="84" y="14" width="3" height="8"><title>5</title></rect><rect x="88" y="17" width="3" height="5"><title>3</title></rect><rect x="92" y="19" width="3" height="3"><title>2</title></rect></svg></div></div><div class="yf-ui-card yf-ui-tone-ok"><div class="yf-ui-card-title">Hit rate</div><div class="yf-ui-card-value">99.2 %</div><div class="yf-ui-card-sub small">of 1.2 M lookups</div></div><div class="yf-ui-card yf-ui-tone-danger"><div class="yf-ui-card-title">Errors</div><div class="yf-ui-card-value">2</div><div class="yf-ui-card-sub small"><span class="label label-danger">critical</span></div></div><a class="yf-ui-card yf-ui-tone-info" href="./?object=doctor"><div class="yf-ui-card-title">Open the doctor</div><div class="yf-ui-card-sub small">the whole card is a link</div></a></div>

Tab bars and tables

echo '<ul class="' . $ui->tabs_class('tabs') . '">...</ul>';   // nav nav-tabs yf-ui-tabs
echo '<table class="' . $ui->table_class() . '">...</table>';   // table table-condensed / table-sm table-hover yf-ui-table
HTML
<ul class="nav nav-tabs yf-ui-tabs"><li class="active nav-item"><a class="nav-link active" href="./?object=docs&action=misc&id=admin_ui">Errors</a></li><li class="nav-item"><a class="nav-link" href="./?object=docs&action=misc&id=admin_ui">Sources</a></li></ul>
NameValue
SITE_NAMEyf demo
DEBUG0
HTML
<table class="table table-condensed table-hover yf-ui-table"><thead><tr><th>Name</th><th>Value</th><th></th></tr></thead><tbody><tr><td>SITE_NAME</td><td>yf demo</td><td><a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-default yf-btn yf-btn-icon" title="Edit" aria-label="Edit"><i class="fa fa-edit" aria-hidden="true"></i></a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-danger yf-btn yf-btn-icon" title="Delete" aria-label="Delete"><i class="fa fa-trash" aria-hidden="true"></i></a></td></tr><tr><td>DEBUG</td><td>0</td><td><a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-default yf-btn yf-btn-icon" title="Edit" aria-label="Edit"><i class="fa fa-edit" aria-hidden="true"></i></a> <a href="./?object=docs&action=misc&id=admin_ui" class="btn btn-xs btn-danger yf-btn yf-btn-icon" title="Delete" aria-label="Delete"><i class="fa fa-trash" aria-hidden="true"></i></a></td></tr></tbody></table>