Metadata-Version: 2.4
Name: django3-dash
Version: 2.0.0
Summary: A modern Django dashboard built with DaisyUI
Author: mazen qazeh
Author-email: mazen7722 <mqazeh@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mazen7722/django3-dash
Project-URL: Source, https://github.com/mazen7722/django3-dash
Project-URL: Tracker, https://github.com/mazen7722/django3-dash/issues
Keywords: django,admin,dashboard,daisyui,tailwindcss
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Dynamic: author
Dynamic: license-file

# django3-dash

A modern Django admin dashboard built with **DaisyUI** and **Tailwind CSS**.

![Django](https://img.shields.io/badge/Django-3.2%20–%205.2-092E20?logo=django)
![Python](https://img.shields.io/badge/Python-3.8+-3776AB?logo=python)
![License](https://img.shields.io/badge/License-MIT-yellow)
![PyPI](https://img.shields.io/pypi/v/django3-dash)

---

## Features

- 🎨 **Modern UI** — DaisyUI components with Tailwind CSS
- 🌓 **Dark Mode** — Built-in theme selector with multiple DaisyUI themes
- 🎯 **Custom Theme Colors** — Admin UI to override every color (primary, secondary, neutral, base, semantic)
- 📊 **Dashboard Widgets** — Charts, stats, recent items (Bar, Line, Pie, Doughnut, etc.)
- 🗂️ **Tabbed Inlines & Fieldsets** — Organize admin forms with navigation tabs
- 🌐 **RTL Support** — Full Arabic, Farsi, and right-to-left language support
- 🔧 **Highly Configurable** — Reorder apps, add icons, hide apps from sidebar
- 📱 **Responsive** — Mobile-friendly sidebar and layout

---

## Quick Start

### Installation

```bash
pip install django3-dash
```

### Settings

Add to `INSTALLED_APPS` in your `settings.py`:

```python
INSTALLED_APPS = [
    "django_dash",
    "django.contrib.admin",
    "django.contrib.humanize",
    "django.contrib.contenttypes",
    # ... your apps
]
```

Run migrations (for DashboardWidget and ThemeConfig models):

```bash
python manage.py migrate django_dash
```

---

## Configuration

All settings are optional. Configure via `DASH_SETTINGS` in `settings.py`:

### Branding

```python
DASH_SETTINGS = {
    "SITE_TITLE": "My Admin",               # Browser tab title
    "SITE_HEADER": "Administration",        # Header in admin
    "INDEX_TITLE": "Welcome back!",         # Dashboard greeting
    "SITE_LOGO": "/static/logo.svg",        # Custom logo URL
}
```

### Theme Selector

```python
DASH_SETTINGS = {
    "DEFAULT_THEME": "corporate",           # Force a single theme
    "DEFAULT_THEME_DARK": "dim",            # Separate theme for dark mode
    "SHOW_THEME_SELECTOR": True,            # Show/hide theme picker dropdown
    "THEME_LIST": [                         # Available themes
        {"name": "Light", "value": "light"},
        {"name": "Dark", "value": "dark"},
        {"name": "Corporate", "value": "corporate"},
    ],
}
```

### App Sidebar

```python
DASH_SETTINGS = {
    "APPS_REORDER": {
        "auth": {
            "icon": "fa-solid fa-lock",
            "name": "Authentication",
            "hide": False,
            "divider_title": "Security",
        },
        "polls": {
            "icon": "fa-solid fa-square-poll-vertical",
            "priority": 10,              # Higher = appears first
        },
    },
}
```

You can also set `icon`, `divider_title`, `priority`, and `hide` directly on your `AppConfig`:

```python
class PollsConfig(AppConfig):
    name = "polls"
    icon = "fa-solid fa-square-poll-vertical"
    divider_title = "Content"
    priority = 5
```

### Extra Assets

```python
DASH_SETTINGS = {
    "EXTRA_STYLES": ["https://example.com/custom.css"],
    "EXTRA_SCRIPTS": ["https://example.com/custom.js"],
    "SIDEBAR_FOOTNOTE": "v2.0.0",
    "DONT_SUPPORT_ME": False,            # Hide GitHub link in sidebar
    "LOAD_FULL_STYLES": False,           # Load full DaisyUI (needed for custom themes)
}
```

### Dashboard

```python
DASH_SETTINGS = {
    "SHOW_SIDEBAR": True,
    "SHOW_KEY_METRICS": True,
    "SHOW_RECENT_ACTIVITY": True,
    "SHOW_WORKSPACE": True,
    "ENABLE_CHART_ANIMATIONS": True,
    "CHART_ANIMATION_DURATION": 800,     # milliseconds
    "LIST_PER_PAGE": 20,
    "SHOW_CHANGELIST_FILTER": False,     # Auto-open filter sidebar
}
```

### Static Theme Override (no admin UI)

If you prefer hardcoding colors without the admin interface:

```python
DASH_SETTINGS = {
    "CUSTOM_THEME_COLORS": {
        "primary": "#4f46e5",
        "primary-focus": "#4338ca",
        "secondary": "#0ea5e9",
        "neutral": "#1e293b",
        "base-100": "#ffffff",
        "base-200": "#f1f5f9",
        "base-300": "#e2e8f0",
        "base-content": "#0f172a",
    },
}
```

Accepted CSS color formats: hex (`#4f46e5`), oklch (`oklch(0.42 0.19 265)`), rgb, hsl.

---

## Custom Theme Colors (Admin UI)

> **New in 0.4.0** — Manage theme colors from the Django admin panel.

After running migrations, a **Theme Colors** entry appears under the Dashboard section in admin.

### How it works

1. Navigate to **Dashboard → Theme Colors** in the admin sidebar
2. Toggle **Enable custom theme** ON
3. Pick colors for any of the 21 DaisyUI color slots:
   - **Brand** — Primary, Secondary, Accent (and their focus/content variants)
   - **Neutral** — Neutral (and focus/content)
   - **Base / Background** — `base-100`, `base-200`, `base-300`, `base-content`
   - **Semantic** — Info, Success, Warning, Error
4. Click **Save**

Colors you leave empty will fall through to the active DaisyUI theme's defaults.

### Reset

Click **Reset to Default** to clear all overrides and disable the custom theme.

### Live Preview

Changes take effect immediately on save — refresh any admin page to see your new colors.

---

## Dashboard Widgets

Create dynamic charts and stats for your admin dashboard home page.

### Available Chart Types

| Type | Description |
|------|-------------|
| `bar` | Vertical bar chart |
| `line` | Line chart |
| `pie` | Pie chart |
| `doughnut` | Doughnut chart |
| `polar` | Polar area chart |
| `radar` | Radar chart |
| `number` | Large stat counter |
| `recent` | Recent items list |

### Usage

1. Go to **Dashboard → Dashboard widgets** in admin
2. Choose a **Model** (any registered model)
3. Pick a **Chart Type**
4. For time-based charts, set a **Date Field** (e.g. `created_at`) and **Group By** (day/week/month/year)
5. For aggregate charts, set **Aggregate** (count/sum/avg/max/min) and optional **Aggregate Field**
6. Static charts: fill **Custom Labels** and **Custom Data** (one per line)

---

## Tabbed Interface

### Tabbed Inlines

```python
from django_dash.mixins import NavTabMixin

class ChoiceInline(admin.TabularInline, NavTabMixin):
    model = Choice
    extra = 1

@admin.register(Poll)
class PollAdmin(admin.ModelAdmin):
    inlines = [ChoiceInline]
```

### Tabbed Fieldsets

```python
@admin.register(User)
class UserAdmin(admin.ModelAdmin):
    fieldsets = (
        (None, {"fields": ("username", "password")}),
        ("Profile", {
            "fields": ("first_name", "last_name", "email"),
            "classes": ("navtab",),   # ← Creates a tab
        }),
        ("Permissions", {
            "fields": ("is_active", "is_staff"),
            "classes": ("navtab",),
        }),
    )
```

---

## Language Switching

```python
# urls.py
urlpatterns = [
    path("i18n/", include("django.conf.urls.i18n")),
    # ...
]

# settings.py
MIDDLEWARE = [
    "django.middleware.locale.LocaleMiddleware",
    # ...
]

LANGUAGES = [
    ("en", "English"),
    ("fa", "فارسی"),
    ("ar", "العربية"),
]
```

---

## License

MIT License. See [LICENSE](LICENSE).

---

## Links

- **PyPI**: https://pypi.org/project/django3-dash/
- **GitHub**: https://github.com/mazen7722/django3-dash
