Metadata-Version: 2.4
Name: django-admin-forge
Version: 0.1.0
Summary: A modern, extensible, premium Django admin framework.
Author: django-admin-forge contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/django-admin-forge
Project-URL: Documentation, https://github.com/your-org/django-admin-forge/docs
Project-URL: Repository, https://github.com/your-org/django-admin-forge
Project-URL: Issues, https://github.com/your-org/django-admin-forge/issues
Keywords: django,admin,dashboard,saas,internal-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django<6.0,>=4.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-django>=4.8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Provides-Extra: publish
Requires-Dist: build>=1.2; extra == "publish"
Requires-Dist: twine>=6.0; extra == "publish"
Dynamic: license-file

# django-admin-forge

`django-admin-forge` is a modern, customizable Django admin framework for serious SaaS and enterprise apps.

It keeps Django admin's reliability and model integration, while upgrading the UI/UX, theming, and developer customization surface.

## Highlights

- Django-first admin replacement (`AdminSite`-based)
- Branded login and modern dashboard
- Customizable sidebar menus and app/model navigation
- Dark, light, and system themes
- Accent color system
- Improved changelist, filters, bulk actions, and empty states
- Improved add/edit form layout

## Install

From [PyPI](https://pypi.org/project/django-admin-forge/):

```bash
pip install django-admin-forge
```

If you previously tried the `django-forge` distribution name, switch to this package: update `INSTALLED_APPS` and imports to `django_admin_forge`, rename settings `DJANGO_ADMIN_FORGE`, then `pip uninstall django-forge` (if installed) and install as above.

From a wheel or sdist you built locally:

```bash
python -m pip install build
python -m build
pip install dist/django_admin_forge-*.whl
```

Develop this repository (editable install, tests, lint):

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### Publishing to PyPI

1. Configure [PyPI](https://pypi.org/account/) credentials (for example [upload with `twine`](https://twine.readthedocs.io/) or `uv publish`).
2. Bump `version` in `pyproject.toml`.
3. Install build tools: `pip install ".[publish]"` (or `pip install build twine`).
4. Run `python -m build`, then `twine check dist/*` and `twine upload dist/*`.

Use [TestPyPI](https://test.pypi.org/) first if you want a dry run: `twine upload --repository testpypi dist/*`.

## Quick Integration

### 1) Add apps

```python
INSTALLED_APPS = [
    "django_admin_forge",
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # your apps...
]
```

### 2) Use Forge admin URLs

```python
from django.urls import path
from django_admin_forge.site import forge_admin_site

urlpatterns = [
    path("admin/", forge_admin_site.urls),
]
```

### 3) Configure `DJANGO_ADMIN_FORGE` (optional but recommended)

```python
DJANGO_ADMIN_FORGE = {
    "brand_name": "Forge Admin",
    "brand_logo_text": "FORGE",
    "brand_tagline": "Modern Django operations panel",
    "accent_color": "green",
    "default_theme": "system",  # "light" | "dark" | "system"
    "show_sidebar_search": True,
    "enable_command_bar": True,
}
```

## Configuration Reference

Use the `DJANGO_ADMIN_FORGE` setting dictionary.

- `brand_name` (`str`): Header brand name.
- `brand_logo_text` (`str`): Compact sidebar/logo text.
- `brand_tagline` (`str`): Login/subtitle branding.
- `accent_color` (`str`): Accent token used in key actions and highlights.
- `default_theme` (`"light" | "dark" | "system"`): Initial theme mode.
- `show_sidebar_search` (`bool`): Sidebar search input visibility.
- `enable_command_bar` (`bool`): Header search/command input visibility.
- `menu_icons` (`dict[str, str]`): Overrides for app/model icons.
- `menu_tabs` (`list[dict]`): Sidebar menu tabs (top and bottom areas).
- `dashboard_analytics_cards` (`list[dict]`): Override dashboard KPI cards for marketing/business snapshots.

## Accent Colors

Supported `accent_color` values:

`blue`, `green`, `amber`, `violet`, `emerald`, `teal`, `cyan`, `sky`, `indigo`, `purple`, `pink`, `rose`, `red`, `orange`, `yellow`, `lime`, `slate`, `gray`, `zinc`, `neutral`, `stone`

Example:

```python
DJANGO_ADMIN_FORGE = {
    "accent_color": "rose",
}
```

## Sidebar Menus (`menu_tabs`)

By default, only `Dashboard` is shown.

You can fully configure sidebar tabs:

```python
DJANGO_ADMIN_FORGE = {
    "menu_tabs": [
        {"label": "Dashboard", "url_name": "admin:index", "icon": "layout-grid"},
        {"label": "Applications", "url_name": "admin:forge-applications", "icon": "layers"},
        {"label": "Users", "url_name": "admin:auth_user_changelist", "icon": "user"},
        {"label": "Documentation", "url": "/docs/", "icon": "external-link"},
    ]
}
```

Each tab supports:

- `label` (required)
- `url_name` (reverse name) or `url` (direct URL)
- `icon` (optional, defaults to `layout-grid`)

## Menu Icon Overrides (`menu_icons`)

You can override app/model icons by key:

```python
DJANGO_ADMIN_FORGE = {
    "menu_icons": {
        "auth": "shield",                # app-level
        "auth.user": "user",             # model-level
        "auth.group": "users",
        "demo_app.customer": "building",
    }
}
```

Resolution order:
1. `app_label.model_name`
2. `model_name`
3. `app_label`
4. built-in defaults

## Dashboard Analytics Cards

You can supply custom KPI cards for the dashboard hero section using real model data:

```python
DJANGO_ADMIN_FORGE = {
    "dashboard_analytics_cards": [
        {
            "label": "Customers",
            "app_label": "demo_app",
            "model": "Customer",
            "metric": "count",
            "icon": "users",
            "hint": "Total customer records",
        },
        {
            "label": "Active customers",
            "app_label": "demo_app",
            "model": "Customer",
            "metric": "count",
            "queryset_filter": {"is_active": True},
            "icon": "activity",
            "hint": "is_active = true",
        },
    ]
}
```

Each card supports:
- `label` (required)
- `app_label` and `model` for dynamic model-based metrics
- `metric` (currently supports `count`)
- `queryset_filter` (optional exact Django ORM filters)
- `value` (optional fallback/manual value)
- `icon`
- `hint` (or `trend`)

## Demo Project (this repo)

```bash
python demo/manage.py migrate
python demo/manage.py createsuperuser
python demo/manage.py runserver
```

Open: [http://127.0.0.1:8000/admin/](http://127.0.0.1:8000/admin/)

## Status and Roadmap

Current implementation includes custom site templates, dashboard, apps page, collapsible sidebar, filters modal, improved forms/changelists, search helpers, and theme controls.

Planned next:

- Saved views/filters
- Dashboard widget API expansion
- Accessibility and keyboard navigation improvements
- Packaging/build pipeline polish for production release

