Ocyan Admin Theme

ocyan.plugin.admin-theme is an opt-in, reusable presentation layer for Django administration. It themes Django admin templates and static assets; it does not replace Django authentication, permissions, routes, model registration, or Wagtail administration.

Repository structure

This is a first-class Ocyan plugin repository. It follows the current, modernised plugin form: source in src/, PEP 621 metadata in pyproject.toml, namespaced package data, focused Django tests, a changelog, and a source-controlled non-deploying Jenkinsfile. Older Ocyan plugins commonly use a flat setup.py layout; this package deliberately does not copy that legacy structure.

Install and activate

Install the package as an explicit project dependency. In a conventional Django project, add the app before django.contrib.admin so Django’s app-template discovery selects the theme:

INSTALLED_APPS = [
    "ocyan.plugin.admin_theme",
    "django.contrib.admin",
    # remaining applications
]

Leaving the app out intentionally preserves standard Django administration. ocyan.main does not require this package.

In an Ocyan project, include ocyan.plugin.admin-theme in ocyan.json. The package's Ocyan entry point adds its Django app and prepends its packaged template directory to Ocyan's filesystem-first template loader. This is necessary because that loader has its own extension ordering; projects must not duplicate the theme's templates or add a second Django-admin app entry.

Namespace compatibility status

This distribution uses the ocyan.plugin namespace and is intentionally independent of ocyan.main. Its Ocyan entry point is lazy, so ordinary Django projects do not need Ocyan runtime integration merely to import or use the theme through INSTALLED_APPS.

Branding

Projects configure their own identity; this package deliberately ships no project logo or private asset.

OCYAN_ADMIN_THEME = {
    "company_name": "MandelBlog",
    "product_name": "Operations Platform",
    "compact_logo": "M",
    "logo_url": "/static/project/brand/logo.svg",
    "logo_dark_url": "/static/project/brand/logo-dark.svg",
    "compact_logo_url": "/static/project/brand/icon.svg",
    "compact_logo_dark_url": "/static/project/brand/icon-dark.svg",
    "favicon_url": "/static/project/brand/favicon.svg",
    "application_icon_url": "/static/project/brand/icon.svg",
    "login_heading": "Welcome back",
    "login_supporting_text": "Manage your authorised operations from one place.",
    "accent_color": "#1769aa",
}

Branding URLs accept root-relative paths or explicit HTTP(S) URLs only. Prefer project-owned SVG assets for crisp high-DPI rendering. The package has safe text/mark fallbacks if no assets are configured.

Compatibility and accessibility

The initial release line supports Python 3.12 and Django 5.2 through 5.x. It has no Wagtail dependency and can coexist with Wagtail because it only overrides Django-admin templates. It uses native form labels, Django’s CSRF form flow, visible focus treatments, reduced-motion handling, and forced colours fallbacks.

Run the test suite with:

DJANGO_SETTINGS_MODULE=tests.settings python -m django test tests

Build artifacts with:

python -m build

Before an RC, test a built wheel and sdist in clean environments and run a project integration test with the theme both enabled and intentionally absent.

Scope and fallback

The package themes Django administration only. It does not replace Django authentication, routing, permissions, model registration, or Wagtail admin. Projects can opt out by removing the app from INSTALLED_APPS; standard Django admin templates then remain in use.