APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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

  1. Add the enum and matching CSS/JS assets.
  2. Create new template directories for affected Core Apps and Core UI Elements.
  3. Extend the controller’s explicit enum-to-template mapping.
  4. Adapt Bootstrap-dependent markup and nested includes.
  5. Test each affected context; do not assume automatic backwards compatibility.

See Developing Core UI Elements for the implementation checklist.

Next Steps

Previous

Core UI

Explore Core UI

Next

Developing Core UI Elements

Explore Developing Core UI Elements