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.deleteis red and icon-only,activegreen,inactiveyellow,edit/view/move/clonedefault and icon-only,add,refresh,back,download,docsdefault with their label,saveblue,settingsan 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 astitleandaria-label;title,class(more classes),btn_class(the whole class),attrs,target,html(the label is HTML); for POST alsoconfirm(a link or plain button withconfirmthrows: an action worth a confirm is a POST),js,form_class,style,form_attrs,extra_html.- A URL must start with
./,/,#,http:orhttps:; 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', orbtn-xsin a template. Nobtn-lg, no button without a size. - Icon only when the icon is unmistakable (delete, edit, move, clone, settings), always with
titleandaria-label; a short label otherwise. make admin-buttons(part ofmake hygieneand 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 inscripts/zf_tools/admin_buttons.py.- Under Bootstrap 5 every
btn-smof 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 adminstyle_css.stplstill 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)
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.
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>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>