Checklist: AA app migration to BS5 templates

migrate-to-bs5.md

Checklist: AA app migration to BS5 templates

Checklist for migrating an AA app to BS5 / AA4 style.

Update CI pipeline

Tip

I would recommend to start by updating the CI pipeline and making sure it works before making any other changes. The pipeline can sometimes breaks due to changes in dependencies e.g. AA core.

Update pyproject.toml

• Set AA4 as minimum dependency: "allianceauth>=4,<5"
• Remove Django 3.x support
• Add Python 3.12 support

Update testauth / tox

• Remove aa3 settings
• Remove django 4.0 / aa3 tests from tox
• Replace django 4.0 tests with django 4.2 test in runner script
• Add Python 3.12 tests

Update GitLab runner script

• Remove aa3 related parts from testauth
• Make sure to use at least "bookworm" docker image

Migrate templates

Base template (base.py)

Switch to new AA base by replacing {% extends 'allianceauth/base.html' %} with

{% extends 'allianceauth/base-bs5.html' %}

Configure nav bar

Set the current app name in the AA navbar:

{% block header_nav_brand %}{% translate "Structures" %}{% endblock %}

An add button can be added on the right side with this block:

{% block header_nav_collapse_right %}
   ...
{% endblock header_nav_collapse_right %}

Disable dashboard defaults:

{% block header_nav_user_character_control %}
    {% comment %}
        This block is left empty intentionally to disable defaults.
    {% endcomment %}
{% endblock %}

Replace old menu (if applicable)

The old style menu looks something like this: {% include 'structures/partials/menu.html' %}

And should be replaced with a menu definition directly in the base template using the new AA4 style blocks:

{% block header_nav_collapse_left %}
    ...
{% endblock header_nav_collapse_left %}

The menu items have also changed in syntax. Note the new nav classes and the different placement of the navactive class.

Old:

<li class="{% navactive request 'structures:structure_list' %}">
    <a href="{% url 'structures:structure_list' %}">
        {% translate 'Structure List' %}
    </a>
</li>

New:

<li class="nav-item">
    <a class="nav-link {% navactive request 'structures:structure_list' %}" href="{% url 'structures:structure_list' %}">
        {% translate 'Structure List' %}
    </a>
</li>

Buttons

Text Replacement: btn-default -> btn-secondary

Labels

The Label component has been replaces by Badge. The new syntax is:

Old:

<span class="label label-primary">Default</span>

New:

<span class="badge text-bg-primary">Primary</span>

Datatables

Replace old bundle includes:

• Replace {% include 'bundles/datatables-js.html' %} with {% include "bundles/datatables-js-bs5.html" %}
• Replace {% include 'bundles/datatables-css.html' %}with {% include 'bundles/datatables-css-bs5.html' %}

Also replace local copies of datatables with the new bundle include.

FilterDropDown

Replace local copies of filterDropDown with thew AA bundle include: {% include "bundles/filterdropdown-js.html" %}

Configure filterDropDown for BS5 style:

filterDropDown: {
    // ...
    bootstrap: true,
    bootstrap_version: 5,
},

Panels

• Remove panel-default class

• Change panel-heading -> card-header and remove ander header tags in the header, e.g. <h3>

• Text Replacement: panel -> card

Tabs

The syntax for nav tabs has changed.

Old:

<li role="presentation">
    <a href="#structures" aria-controls="structures" role="tab" data-toggle="tab">
        Upwell Structures
    </a>
</li>

New:

<li class="nav-item" role="presentation">
    <button class="nav-link" aria-controls="structures" role="tab" data-bs-toggle="tab" data-bs-target="#structures">
        Upwell Structures"
    </button>
</li>

The active nav-link should also have the class active.

The active tab-pane should also have the class show active.

Note that some apps may also active tabs via JavaScript.

Text replacements:

• <li role="presentation"> -> <li class="nav-item" role="presentation">
• <li role="presentation" class="active"> -> <li class="nav-item" role="presentation"> (and add active class to corresponding nav-item)
• data-toggle -> data-bs-toggle

Modals

Text replacements:

• data-toggle -> data-bs-toggle
• data-target -> data-bs-target
• data-dismiss - > data-bs-dismiss
• class="close"-> class="btn-close"

Delete: <span aria-hidden="true">&times;</span>

Modal title is now <h5>.

The button definiton must now come after the title. Example:

<div class="modal-header">
    <h5 class="modal-title">{% translate "Tags Filter" %}</h5>
    <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>

Version bump & update documentation

• Set version to next major
• Update screenshots in README
• Update CHANGELOG

CHANGELOG example:

## [2.0.0] - 2025-04-14

### Update notes

This release requires Alliance Auth 4.0 or greater.

### Changed

- BREAKING CHANGE: Support dropped for AA3
- Templates migrated to AA4 / Bootstrap 5

Resources

• Bootstrap 5 Documentation
• FilterDropDown Config
• Bootstrap 3 to 4 Migration Guide
• Bootstrap 4 to 5 Migration guide