Tutorial: add an admin module stylesheet #

This tutorial is for designers and developers who build an administration page for an extension (myext) and need some CSS of their own. You will first use the shared components, then add one small stylesheet in the right place. Allow one hour.

Contents #

1. Step 1: start with components
2. Step 2: what is left
3. Step 3: the stylesheet
4. Step 4: register it
5. Step 5: deploy and check

Step 1: start with components #

Build the page from .a4-* classes: .a4-page, .a4-pagehead, .a4-card, .a4-table, .a4-btn, .a4-notice, .a4-empty (admin4 components). Look at the page in light and dark: most pages need no CSS of their own.

Step 2: what is left #

Suppose the page shows a timeline of import runs with a colored bar per run, which no component draws. That is the part for your stylesheet. Write down what the rules must do before writing them.

Step 3: the stylesheet #

extension/myext/design/admin4/stylesheets/myext-admin.css:

/* myext admin pages. Tokens only (doc/eng-us/bc/6.0/admin4-styling.md); light and dark from the tokens. */
.myext-runs { display: grid; gap: var(--a4-space-2); }
.myext-run {
  display: grid;
  grid-template-columns: 10rem minmax(0, 1fr);
  gap: var(--a4-space-3);
  padding-block: var(--a4-space-2);
  border-block-end: 1px solid var(--a4-line);
}
.myext-run-bar {
  block-size: var(--a4-space-2);
  border-radius: var(--a4-radius-s);
  background: var(--a4-accent-soft);
}
.myext-run.is-bad .myext-run-bar { background: var(--a4-bad-bg); }

• Your own prefix (myext-), one component class plus at most one state.
• Only tokens: no #fff, no 12px; the bar's width comes from .a4-pct-* classes on it, not style="".
• Logical properties (border-block-end, padding-block).

Step 4: register it #

extension/myext/settings/design.ini.append.php:

<?php /* #?ini charset="utf-8"?
[ExtensionSettings]
DesignExtensions[]=myext

[StylesheetSettings]
BackendCSSFileList[]=myext-admin.css
*/ ?>

admin4's head loads BackendCSSFileList after the components and module stylesheets, so your rules can refine them.

Step 5: deploy and check #

./console exp:velocity deploy --packer --allow-root-user

(on installations without Velocity: clear the INI, template-block and content caches). Then:

• To do: light and dark, at 1440 px and at 960 px with scale 2;
• To do: no horizontal overflow, contrast at least 4.5:1;
• To do: no <style> and no style="" in the page's templates;
• To do: a right-to-left interface language: the page mirrors.

Related pages #

• admin4 module stylesheets
• admin4 tokens
• The admin styling rules test
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.