# Alliance Auth Zima Theme

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

A 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 Zima brand palette and restyles the public/login pages, delivered as a
standard Python package.

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

## Features

- **Dashboard theme via the AA5 theme selector.** Registers two `ThemeHook`s —
  *Zima Dark* and *Zima Light* — that appear in the user's theme picker. Both
  share one stylesheet and switch through Bootstrap 5.3 colour modes
  (`data-bs-theme`).
- **Self-contained assets.** Each theme serves its own Bootstrap 5 CSS and JS
  bundle from this package's static files; nothing is loaded from a CDN.
- **Restyled public pages.** The login chain 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_ZIMA` settings
  dict — no template forking required (see [Configuration](#configuration)).
- **English and Russian** translation catalogues.

## Requirements

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

## Installation

```shell
pip install aa-theme-zima
```

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

```shell
pip install git+https://gitlab.com/zima-corp/aa-theme-zima.git
```

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

```python
# Zima Theme - https://gitlab.com/zima-corp/aa-theme-zima
INSTALLED_APPS.insert(0, "aa_theme_zima")
```

Then collect the static files:

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

Once installed, each user can pick **Zima Dark** or **Zima Light** from the
theme selector in their Alliance Auth profile.

## Configuration

The theme works without any configuration. To override a few operator-facing
strings without forking the templates, add an optional `AA_THEME_ZIMA` dict to
your `local.py`:

```python
AA_THEME_ZIMA = {
    "OG_TITLE": "My Corp Auth",
    "OG_DESCRIPTION": "Authentication for My Corp.",
}
```

| Key | Default | Description |
| --- | --- | --- |
| `OG_TITLE` | the AA `SITE_NAME` | Open Graph title for social-card previews. |
| `OG_DESCRIPTION` | Alliance Auth's default blurb | Open Graph description for social-card previews. |

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 **Zima Dark** or **Zima Light** 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 a Zima variant
the default for everyone who has not picked one yet, set `DEFAULT_THEME` in your
`local.py`:

```python
# Make Zima Dark the default for users who have not chosen a theme
DEFAULT_THEME = "aa_theme_zima.auth_hooks.ZimaDarkThemeHook"
```

| Value | Theme |
| --- | --- |
| `aa_theme_zima.auth_hooks.ZimaDarkThemeHook` | Zima Dark |
| `aa_theme_zima.auth_hooks.ZimaLightThemeHook` | Zima Light |

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

## Upgrade

```shell
pip install --upgrade aa-theme-zima
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

# Zima Theme - https://gitlab.com/zima-corp/aa-theme-zima
INSTALLED_APPS.insert(0, "aa_theme_zima")
```

## Building from source

The CSS is **not** edited directly — it is compiled from `sass/` with a
gulp + dart-sass + PostCSS toolchain:

```shell
npm install          # one-time: gulp, postcss, bootstrap (SCSS source)
npm run compile      # compiles sass/ -> static CSS and vendors the Bootstrap JS bundle
```

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

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

The package version is single-sourced in `pyproject.toml`; `__version__` is
derived at runtime from the installed distribution metadata.

## 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/zima-corp/aa-theme-zima/-/blob/main/LICENSE)
license.

## Changelog

See [CHANGELOG.md](https://gitlab.com/zima-corp/aa-theme-zima/-/blob/main/CHANGELOG.md).
