README

Visual Bootstrap 5.3 theme builder for TYPO3 v14. Design Bootstrap themes per site in the backend — start from a Bootswatch preset, fine-tune ~200 variables with a live preview, then publish or export clean SCSS. All compilation runs through EXT:t3sbootstrap.

The backend module is fully localized (English source, German translation) and follows the editor's backend language.

Contents

• Features
• Requirements
• Installation
• Quick start
• Preview, Publish & Export
• How it works
• Editor features
• SCSS export
• Per-site themes
• Localization
• Tips & troubleshooting
• Third-party
• License

Features

• Visual theme editor in the TYPO3 backend — no hand-written SCSS required.
• ~200 Bootstrap 5.3 variables across 24 collapsible groups.
• 26 Bootswatch presets as ready-made starting points.
• Interactive component preview — real Bootstrap components (dropdowns, tabs, modal, carousel …) rendered live from your compiled CSS.
• Live frontend preview — see unpublished changes on your real site, risk-free.
• Separate Preview and Publish — nothing goes live until you say so.
• Standalone SCSS export — clean, portable .scss files, no lock-in.
• Per-site themes and full English / German localization.

Requirements

Installation

Composer (recommended)

composer require t3sbs/t3sbootstrap-builder

Classic (non-Composer)

1. Download and unpack into typo3conf/ext/t3sbootstrap_builder/.
2. Activate the extension in the Extension Manager.
3. Run Analyze Database Structure to create tx_t3sbootstrapbuilder_theme.

After installing (either way)

Flush caches:

php typo3/sysext/core/bin/typo3 cache:flush

The module then appears under Content → T3SB Builder (icon shared with t3sbootstrap).

Quick start

1. Open Content → T3SB Builder and pick the site you want to theme.
2. (Optional) Choose a Bootswatch preset as a starting point and load its values.
3. Adjust colors, typography, spacing and component variables in the grouped editor.
4. Hit Preview to compile and check your changes — safely, without touching the live frontend.
5. Hit Publish to make the theme live, or Export SCSS (.zip) to download it.

Preview, Publish & Export

The builder is the single source of truth for the variables it manages: on every save the variable files are fully overwritten (with a timestamped backup), never merged or appended. Three actions sit at the bottom of the editor:

Both Preview and Publish also refresh the in-backend component preview. Your edits are stored either way (and pre-filled when reopening) — only Publish goes live.

How it works

1. The editor exposes a catalog of Bootstrap 5.3 variables ($primary, $card-border-radius, $enable-rounded, …) in collapsible groups.
2. On save, the builder writes a complete variables SCSS file from all field values (defaults overlaid with your edits).
3. Compilation uses the scssphp engine shipped with EXT:t3sbootstrap (Contrib/scssphp), importing custom-variables → bootstrap → custom. The backend preview is written to typo3temp/assets/t3sbootstrap/css/bb-preview-{id}.css.
4. Publish additionally writes t3sbootstrap's live SCSS files and config record, so the frontend recompiles with the new theme.
5. Preview uses a backend AJAX route (ajax_t3sbootstrap_builder_preview, handled by AjaxController) that compiles the preview track and returns the CSS URL as JSON, so the editor swaps the preview iframe's srcdoc in place instead of reloading the page.

Editor features

~200 variables across 24 collapsible groups: Theme colors, Body, Text colors, Links, Typography, Grid & Spacing, Border radius, Buttons, Forms, Options & Toggles, Cards, Carousel, Navbar, Nav, Dropdowns, Alerts, Badges, List groups, Tables, Modals, Accordion, Progress, Pagination, Tooltips & Popovers.

• Collapsible groups (native <details>) as an exclusive accordion: opening one closes the others, and the component preview scrolls to the matching section.
• Boolean options (the enable-* flags) render as on/off switches.
• Color inputs:
  • Theme colors group — color picker + text field.
  • All other color groups — color picker + text field + a theme-color reference select that writes an SCSS reference ($primary, $success, …) into the field.
  • The text field always stays editable for rgba() or $variable references.
• Bootswatch presets — pick a base preset and load its values into the fields client-side (no reload). Your own edits stay on top.

Two-tab preview:

A spinner is shown while each preview renders.

SCSS export

Export SCSS (.zip) saves the current editor values and downloads a ZIP named {site}-{YYYY-MM-DD-HHMMSS}.zip containing exactly two files:

• scss/_variables.scss — the pre-Bootstrap variables (your builder values).
• scss/_custom.scss — the Bootswatch component overrides, followed by your additional custom SCSS (the Additional custom SCSS (after Bootstrap) field).

Per-site themes

One tx_t3sbootstrapbuilder_theme record per site (keyed by site identifier), stored at root level (pid 0). The TCA sets ignorePageTypeRestriction, so the record never blocks page doktype changes.

Localization

UI strings live in Resources/Private/Language/:

• locallang.xlf / de.locallang.xlf — module UI and flash messages
• locallang_mod.xlf / de.locallang_mod.xlf — backend module label

English is the source language; German is provided as a translation. The backend follows the user's language, falling back to English. Variable group names stay in English (they mirror the Bootstrap SCSS variable names).

Tips & troubleshooting

Tip

$enable-rounded (group Options & Toggles) is a global Bootstrap switch: when off, all border-radius values (including $card-border-radius) are forced to 0. Turn it on for radii to take effect.

Important

The Frontend preview tab embeds the real site in an iframe and swaps in the preview CSS, which requires backend and frontend on the same origin. If the frontend forbids embedding (X-Frame-Options / CSP frame-ancestors) or is cross-origin, use the Open link instead.

Note

Backups of the live variable files are kept as _{timestamp}-custom-variables-{id}.scss next to the originals in EXT:t3sb_package/Resources/Public/T3SB-SCSS/ (old backups are auto-pruned).

Third-party

• Bootstrap bundle JS (Resources/Public/JavaScript/vendor/bootstrap.bundle.min.js, v5.3.3, MIT) — shipped to power the interactive component preview.
• Bootswatch presets — MIT-licensed (https://github.com/thomaspark/bootswatch). The 26 presets are pre-cached in Resources/Public/Presets/ (each as _variables.scss + _bootswatch.scss) and loaded at runtime; no download happens at runtime.

License

GPL-2.0-or-later — see LICENSE.txt.

_{Maintained by T3Solution · t3solution.de · part of the t3sbootstrap ecosystem.}