Developing Core UI Elements
A practical implementation guide for framework-aware Core UI controllers and Twig templates.
Decide whether a versioned template is necessary
Inspect actual Twig markup. Bootstrap classes, components and data-bs-* attributes
require
an explicit version directory; a template that only renders content or registers assets does not.
Implementation workflow
- Obtain
Core\Uifrom the registry or existing dependency injection. - Normalize the configured
BootstrapVersionto an explicitly supported major/minor template directory. - Keep controller-level version selection centralized.
- Use the resolved directory for the base template and all nested includes.
- Preserve individual templates, existing rendering logic and caching.
- Fail clearly when Bootstrap is unavailable or unsupported.
{% include bootstrap_template_directory ~ '/fields/text.html.twig' %}
Themes and document attributes
Theme identifiers are metadata, not automatic CSS registration. Register theme styles through Core\Css.
Set root HTML attributes and classes through Core\Ui instead of modifying the shared
base
template.
$ui = Registry::get(Ui::class);
$ui->addHtmlClass('dark-mode');
$ui->setHtmlAttribute('dir', 'ltr');
$ui->setHtmlAttribute('data-feature', 'enabled');
Head resources
Register styles with Core\Css, scripts with Core\Js, and supplemental link
resources such as preload and preconnect with Core\Ui::addAsset().
$ui->addAsset('/src/example/hero.webp');
$ui->addAsset('https://static.example.com', [
'rel' => 'preconnect',
'crossorigin' => 'anonymous',
]);
Review checklist
- Bootstrap-dependent markup only is versioned.
- Directories follow
templates/bootstrap/{major.minor}/. - Every supported enum value is explicitly mapped; no fallback.
- Nested includes use the same resolved directory.
- Neutral templates, caching and existing rendering behavior are preserved.
- Theme CSS and head assets use their respective controllers.
- HTML
langcomes fromCore\Languages;globaldoes not automatically produce alangattribute. - Use
addHtmlClass()to append classes without replacing existing classes. - Validate PHP syntax and test affected UI contexts.