Bootstrap Template Versioning
Keep Bootstrap-specific markup compatible without coupling shared rendering templates to a framework release.
Core principle
Version a Twig template only when its markup actually depends on Bootstrap classes, components or
data-bs-*
attributes. Registering CSS or JavaScript does not by itself require template versioning. Shared
base,
content and Bootstrap-neutral frameset templates remain independent.
Framework resources and versions
Core\Ui selects Bootstrap and Bootstrap Icons independently. A null version
disables automatic registration of the respective resource. The documented default Bootstrap enum is
BootstrapVersion::V5_3_8.
| Resource | Priority | Example |
|---|---|---|
| Bootstrap CSS | -100 |
/src/appnetos/shared/css/bootstrap/5.3.8/bootstrap.min.css |
| Bootstrap JS bundle | -100 |
/src/appnetos/shared/js/bootstrap/5.3.8/bootstrap.bundle.min.js |
| Bootstrap Icons CSS | -90 |
/src/appnetos/shared/css/bootstrap-icons/{version}/bootstrap-icons.min.css
|
Template directory layout
Asset paths use a full patch version such as 5.3.8. Templates use the compatible
major/minor
directory, here 5.3.
appnetos/shared/ui/navigation/sidebar/
└── templates/
└── bootstrap/
└── 5.3/
└── sidebar.html.twig
Explicit controller resolution
Resolve the UI controller through the registry, map supported enum values explicitly and return the matching template directory. This example is a pattern, not a complete controller.
use Core\Registry;
use Core\Ui;
use Core\Ui\Enum\BootstrapVersion;
$this->_ui = Registry::get(Ui::class);
protected function normalizeBootstrapTemplateVersion(BootstrapVersion|null $version): string
{
return match ($version) {
BootstrapVersion::V5_3_8 => '5.3',
null => throw new \RuntimeException('Bootstrap is required by this Core UI element.'),
};
}
protected function getBootstrapTemplateDirectory(): string
{
$version = $this->normalizeBootstrapTemplateVersion($this->_ui->getBootstrapVersion());
return 'appnetos/shared/ui/navigation/sidebar/templates/bootstrap/' . $version;
}
No silent fallback
An unsupported or disabled Bootstrap version must not silently render a different version’s template. Do not automatically scan directories or fall back to an unversioned file. A missing mapping should be visible and handled explicitly.
Nested includes
When a parent template includes field-specific templates, the controller supplies the selected directory once; nested templates reuse that value.
{% include bootstrap_template_directory ~ '/fields/text.html.twig' %}
Bootstrap-neutral rendering
base.html.twig, default.html.twig and Bootstrap-neutral framesets such as
top-content and top-sidebar do not need a Bootstrap version directory.
Rendering previously prepared content does not make a neutral wrapper Bootstrap-dependent.
{% extends 'appnetos/shared/templates/base.html.twig' %}
{% block body %}
{% for view in content %}
{{ view|raw }}
{% endfor %}
{% endblock %}
Adding a new Bootstrap version
- Add the enum and matching CSS/JS assets.
- Create new template directories for affected Core Apps and Core UI Elements.
- Extend the controller’s explicit enum-to-template mapping.
- Adapt Bootstrap-dependent markup and nested includes.
- Test each affected context; do not assume automatic backwards compatibility.
See Developing Core UI Elements for the implementation checklist.