Metadata-Version: 2.4
Name: aa-theme-xix
Version: 0.4.0
Summary: Legion of xXDEATHXx Bootstrap 5 theme for Alliance Auth 5
Project-URL: Repository, https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix
Project-URL: Issues, https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix/-/issues
Project-URL: Changelog, https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix/-/blob/main/CHANGELOG.md
Author-email: Boris Talovikov <boris@talovikov.ru>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Requires-Dist: allianceauth<6,>=5
Description-Content-Type: text/markdown

# Alliance Auth XIX Theme

[![PyPI version](https://img.shields.io/pypi/v/aa-theme-xix)](https://pypi.org/project/aa-theme-xix/)
[![Python versions](https://img.shields.io/pypi/pyversions/aa-theme-xix)](https://pypi.org/project/aa-theme-xix/)
[![License: GPL-3.0-or-later](https://img.shields.io/pypi/l/aa-theme-xix)](https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix/-/blob/main/LICENSE)

The Legion of xXDEATHXx theme for
[Alliance Auth](https://gitlab.com/allianceauth/allianceauth) 5 (Django 5.2
LTS, Bootstrap 5). It ships a self-contained Bootstrap 5 build with the XIX
brand styling and restyles the public/login pages, delivered as a standard
Python package.

> Русская версия: [README.ru.md](https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix/-/blob/main/README.ru.md).

## Features

- **Dashboard theme via the AA5 theme selector.** Registers a `ThemeHook`
  named *xix* that appears in the user's theme picker.
- **Self-contained assets.** The theme serves its own Bootstrap 5 CSS, JS
  bundle and the Lato web font from this package's static files; nothing is
  loaded from a CDN or Google Fonts.
- **Restyled public pages.** The login chain — with an animated starfield
  background — and the django-esi character-pick page are overridden with
  Bootstrap 5 layouts that match the theme.
- **Operator-configurable strings** via an optional `AA_THEME_XIX` settings
  dict — no template forking required (see [Configuration](#configuration)).
- **English and Russian** translation catalogues.

## Requirements

- Alliance Auth `>=5,<6`
- Python `>=3.11,<3.15`

## Installation

```shell
pip install aa-theme-xix
```

To install the latest unreleased changes straight from the repository instead:

```shell
pip install git+https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix.git
```

Open your `local.py` and add the following right below your `INSTALLED_APPS`:

```python
# XIX Theme - https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix
INSTALLED_APPS.insert(0, "aa_theme_xix")
```

This single entry both activates the template overrides (login page, ESI
token selection, icons) and registers the theme with Alliance Auth's theme
selector.

Then collect the static files:

```shell
python manage.py collectstatic
```

Once installed, each user can pick **xix** from the theme selector in their
Alliance Auth profile.

## Configuration

The theme works without any configuration. To override the operator-facing
strings on the public pages without forking the templates, add an optional
`AA_THEME_XIX` dict to your `local.py`:

```python
AA_THEME_XIX = {
    "LOGIN_TITLE": "My Alliance",
    "LOGIN_SUBTITLE": "TICKER",
    "DISCORD_INVITE_URL": "https://discord.gg/example",
    "OPENGRAPH_DESCRIPTION": "My Alliance's auth system.",
}
```

| Key | Default | Description |
| --- | --- | --- |
| `LOGIN_TITLE` | `Legion of xXDEATHXx` | Heading (and logo alt text) in the login box. |
| `LOGIN_SUBTITLE` | `X.I.X` | Ticker line under the heading. |
| `DISCORD_INVITE_URL` | the XIX Discord invite | Target of the Discord link on the login page. |
| `OPENGRAPH_DESCRIPTION` | the Alliance Auth blurb | Site description used in link previews (OpenGraph meta). |

Any key left unset keeps the theme's built-in default, so an out-of-the-box
install renders exactly as shipped.

### Default theme

Each user selects a theme from their profile. Until a user makes a choice,
Alliance Auth renders the theme named by its core `DEFAULT_THEME` setting
(shipped as `allianceauth.theme.flatly.auth_hooks.FlatlyThemeHook`). To make
XIX the default for everyone who has not picked one yet, set `DEFAULT_THEME`
in your `local.py`:

```python
# Make XIX the default for users who have not chosen a theme
DEFAULT_THEME = "aa_theme_xix.auth_hooks.AaXixThemeHook"
```

`DEFAULT_THEME` is an Alliance Auth core setting, not a XIX one — it only sets
the fallback; users can still switch to any installed theme from their
profile. The public login pages are always XIX-styled regardless of this
setting.

## Upgrade

```shell
pip install --upgrade aa-theme-xix
python manage.py collectstatic
```

### Using aa-gdpr

If you are using [aa-gdpr](https://gitlab.com/tactical-supremacy/aa-gdpr),
this theme's entry needs to come **after** the `aa-gdpr` entry:

```python
# GDPR Compliance
INSTALLED_APPS.insert(0, "aagdpr")
AVOID_CDN = True

# XIX Theme - https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix
INSTALLED_APPS.insert(0, "aa_theme_xix")
```

## Building from source

The shipped CSS and JS are **not** edited directly — they are compiled from
`scss/` and `js/` with a gulp + dart-sass + PostCSS + esbuild toolchain:

```shell
npm ci               # reproducible toolchain pinned by package-lock.json
npm run compile      # compiles scss/ and js/ -> aa_theme_xix/static/
```

The Python package is built with [uv](https://docs.astral.sh/uv/) on the
hatchling build backend:

```shell
uv build             # produces a wheel and sdist in dist/
```

The package version is single-sourced in `pyproject.toml` (`version`);
`aa_theme_xix/__init__.py` derives `__version__` from the installed
distribution metadata at runtime, and the test suite enforces the match.

## Limitations

- **Alliance Auth 5 only.** The templates target the AA5 / Bootstrap-5
  theme-hook era; Alliance Auth 4 is not supported.
- **Run `collectstatic` after every install or upgrade** — the theme serves
  its Bootstrap bundle and compiled CSS from this package's static files.
- This is a presentation layer only: it adds no models, views, or URLs.

## License

Distributed under the
[GPL-3.0-or-later](https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix/-/blob/main/LICENSE)
license.

## Changelog

See [CHANGELOG.md](https://gitlab.com/legion-of-xxdeathxx/aa-theme-xix/-/blob/main/CHANGELOG.md).
