AdminThemeBridge – a native web-component admin that keeps your existing modules working (beta)

[theoretic]

Hi everyone,

AdminThemeBridge 0.29.0 is out.

Sorry for not being very active publicly during some days. I was preparing something special for you all: Bridge extensions, a new, hopefully easier way to write Bridge-compatible modules.

What is a Bridge extension?

It is an ordinary ProcessWire module. The difference is that it changes the Bridge admin only through a published surface (the theme's hookable methods, a few public methods and settings, named slots in the admin shell, window.Bridge and DOM events), and it says what it uses in a small manifest. Bridge reads that manifest, loads the extension's JavaScript module and stylesheets, and puts its markup into the slots. Because everything goes through the published surface, your module should keep working when Bridge changes inside.

The manifest is either a getBridgeExtension() method or just a bridge key in your module info, so a simple extension needs no extra code:

public function getBridgeExtension() {

return array(
'contract' => '^0.2', // which extension contract it was written for
'module' => 'BridgeHello.mjs', // an ES module loaded in the admin
'styles' => array('BridgeHello.css'),
'slots' => array('footer' => 'renderFooter'),
'hooks' => array('renderBreadcrumbs'),
);
}

Slots: head, masthead, masthead-right, user-nav, content-head-buttons, footer, drawer and body. The drawer slot even gives your extension its own drawer next to the logo, like the page tree and history drawers. If a slot method throws, Bridge logs it and the page renders without it.

Styles and tokens (new in contract 0.2): an extension's stylesheets are printed after the theme's own, so your rules win ties without !important. 73 CSS custom properties (colours, font size, line height, field spacing...) are now public tokens you can read or set, so a styling extension can restyle the admin without touching theme internals.

The kit (in the theoretic/bridge repo):

• a scaffold that writes a new extension for you (module, manifest, slot methods, JS module, stylesheet, checks, README);
• contract tests that check your manifest and run your extension in a sandbox and in a browser;
• a compatibility checker that tells you, from the files alone, whether your extensions will work with a given Bridge version;
• a dev mode that reloads your edited JS module and stylesheets in an open admin page.

Bridge's own modules are built the same way: Bridge CSP, the demo module, the BridgeSample module (the scaffold's output, a good place to start) and a new one:

Admin access control (BridgeAdminAccessControl, optional): per-role limits on the page tree, any branch in it, and the main admin menus (Pages, Setup, Modules, Access), enforced on the server. It only narrows what ProcessWire already grants, never gives extra access, and superusers are not affected. Rules are set on the module's configuration screen.

Smaller things:

• Content in draggable rows (the template's field list, repeater item headers) is now vertically centred.

All the details are in docs/extensions.md and the CHANGELOG in the theoretic/bridge repo.

Special thanks to @interrobang, @matjazp, @Markus Thomas and all of you for your ideas and advices giving me motivation to move further! I still have some unresolved cases; will try to resolve them later.