Download the PHP package thelia/backoffice-default-twig-template without Composer

Thelia back-office Twig template (default-twig)

A Bootstrap 5 / Twig / Stimulus port of the legacy Smarty back-office. It runs alongside templates/backOffice/default/ during the transition.

Activation

Architecture

Stack

• Bootstrap 5.3 with overrides aligned on the thelia.net public palette (orange #f26041, soft slate text).
• Bootstrap Icons (1.13).
• Symfony UX (Stimulus, TwigComponent).
• HTMX 2 for progressive enhancement.
• Symfony forms with the custom bo_form_theme.html.twig theme.
• AssetMapper + symfonycasts/sass-bundle for the assets — no Node.js, no bundler, no committed build.

Working on the back-office

Assets (AssetMapper, no Node.js)

The assets are served by Symfony AssetMapper: JavaScript and images are picked up as they are from assets/, and the stylesheet is compiled by symfonycasts/sass-bundle, which downloads a standalone dart-sass binary on first use. There is no package.json, no bundler and no committed build output.

The bundle registers everything itself (asset paths under the backoffice namespace, the Sass root file, the Bootstrap load path), so the only command to know is the one that (re)builds the stylesheet:

bin/install runs it for you on a fresh install. JavaScript and images need no build at all: edit the file, reload the page.

The Bootstrap Sass sources and its bootstrap.esm.min.js come from the twbs/bootstrap Composer package (so the CSS and the JS can never drift apart), and the icon font from twbs/bootstrap-icons. The remaining browser libraries are pinned ES module builds committed under assets/vendor/ and mapped to their bare import names by the importmap the theme renders on its pages (bo_importmap(), see src/Twig/ImportMapExtension.php):

To bump one of them, replace the file with the same artifact from the newer release (drop the trailing //# sourceMappingURL= line) and update this table.

Adding a Stimulus controller: drop the file in assets/controllers/ and register it in assets/bootstrap.js — AssetMapper has no build step, so there is no automatic controller discovery.

Adding a new admin domain

The recipe used for each domain so far (Folder → Content → CustomerTitle → Country → State → Newsletter → Message):

1. Form: src/Form/<Group>/<Name>Type.php, a final class extends AbstractType with options include_id / include_description.
2. Controller: src/Controller/<Group>/<Name>Controller.php with #[Route('/admin/...', name: 'admin.X.')]. Inject AdminFormAction, AdminAccessChecker, Environment, FormFactoryInterface, UrlGeneratorInterface, TokenProvider, TranslatorInterface.
3. Methods: list() (GET), create() (POST), updateView({id}) (GET), processUpdate() (POST), delete() (POST/GET), updatePosition() (POST/GET).
4. Events: $this->action->submit(form: ..., eventFactory: ..., eventName: TheliaEvents::X_CREATE) for forms; $this->action->tokenAction(event: ..., eventName: ...) for single-shot actions.
5. Templates: list.html.twig (DataTable + create modal), edit.html.twig (form_start + form_end).

Responsive (phone and tablet)

The admin is usable from 375px up. Four rules hold the layout together:

• Navigation: the sidebar is offcanvas-lg, so it docks from lg (992px) and is a burger-driven drawer below that — a 768px tablet in portrait gets the full width for its content. The top bar uses navbar-expand (no breakpoint) so its items stay on one row at every width.

• Lists: every BoDataTable scrolls horizontally inside .table-responsive, with the actions column pinned right. Secondary columns are dropped below a breakpoint instead of being pushed out of view, via hideBelow on the column factories:

  Convention: md for identifiers and thumbnails, lg for dates, positions and counts, xl for columns whose value is already readable elsewhere on the row or on the record's own page. The column that names the record is never hidden.

• Key/value tables (plain <table>, not BoDataTable) carry .bo-table-wrap: their cells wrap rather than being clipped, because they have nothing to scroll to.
• Header rows (d-flex justify-content-between) always carry flex-wrap gap-2 so a title plus its action buttons reflow instead of overflowing. Control strips wider than the viewport go inside .bo-scroll-x.

Touch targets are enlarged below lg (row toggles, checkboxes, sortable headers, tree controls). Keep new controls at 24px minimum in both dimensions.

ACL

Resources live in core/lib/Thelia/Core/Security/Resource/AdminResources.php. Check with is_granted('VIEW', 'admin.foo') or $this->access->check(self::RESOURCE, [], AccessManager::VIEW).

Hooks (back-office)

Twig functions exposed by BackOfficeDefaultTwigBundle\Twig\HookExtension:

Most hook names are kept iso with the legacy Smarty template. The few that were renamed are bridged to their legacy name (see Cohabitation & breaking changes), so third-party modules keep working unchanged.

Hook contract for third-party modules

The back-office emits ~200 native hooks. The conventional extension points a module can rely on are emitted systematically:

Hooks consumed by bundled modules (CustomerFamily, SEOne, HookAdminHome, VirtualProductControl, TheliaBlocks) are all wired. A hook code that is not emitted is considered deprecated for the Twig back-office. Open an issue if your module needs one that is missing. The <screen>.js / <entity>.edit-js script hooks are emitted on a per-screen basis as screens are migrated.

Tests

• PHPStan: ddev exec composer phpstan (baseline 60 errors).
• Coding style: ddev exec composer cs / ddev exec composer cs-diff.
• PHPUnit: ddev exec composer test.
• Playwright (BO Twig):

Cohabitation & breaking changes

This template runs side by side with the legacy Smarty back-office. A few names diverge from the legacy ones; here is how third-party modules are affected.

Hooks: bridged, no change required

Renamed hooks are replayed under their legacy Smarty name by Service\Hook\LegacyHookAliases (wired into HookExtension), so a module listening on the old name keeps contributing. Render arguments follow the new (Twig) convention, so adapt listeners that read a renamed argument.

The wysiwyg.js hook on the hook-edit screen keeps its legacy wysiwyg-hook-edit-js location.

ACL: bridged

The advanced-configuration screen accepts both the new admin.configuration.advanced resource and the legacy admin.cache one, so existing profiles keep access without a data migration.

Routes: update your module

Renamed route names are not aliased. A module referencing an old name through path() / url() must update it:

The ACL resource for the mailing system stays admin.configuration.mailing-system.

License

LGPL-3.0+, same as Thelia core.