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.

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>

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 runner script

• Remove aa3 related parts from testauth

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