Metadata-Version: 2.4
Name: adminita
Version: 0.2.0
Summary: A modern admin interface for Django using Tailwind CSS v4
Author-email: Adminita <hello@todiane.com>
License-Expression: MIT
Project-URL: Homepage, https://adminita.todiane.com
Project-URL: Repository, https://github.com/djangify/adminita
Project-URL: Issues, https://github.com/djangify/adminita/issues
Keywords: django,admin,tailwind,tailwindcss,ui,adminita
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: Django>=4.2
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

![adminita header](https://github.com/djangify/adminita/blob/336735abb0e7679f4e2622615f891d178fd4bab3/adminita-homepage.png)


# Adminita

A modern, beautiful Django admin theme built with Tailwind CSS v4. Transform your Django admin interface into a sleek, responsive dashboard with dark mode support.

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
![Django](https://img.shields.io/badge/django-4.2%20to%206.0-green.svg)
![Tailwind CSS](https://img.shields.io/badge/tailwind-v4-38bdf8.svg)
![PyPI](https://img.shields.io/pypi/v/adminita.svg)

## ✨ Features

- 🎨 **Modern UI** - Clean, professional interface built with Tailwind CSS v4
- 🌓 **Dark Mode** - System preference detection with manual toggle
- 📱 **Responsive Design** - Works seamlessly on desktop. Responsive navigation and touch-friendly controls for phones and tablets
- 🎯 **Easy Integration** - Drop-in replacement for Django's default admin
- 💾 **Form Autosave** - Unsaved edits survive a refresh or closed tab, with a Restore/Discard prompt that never overwrites newer changes
- ⚡ **Fast** - Optimized CSS with no unnecessary bloat
- 🔧 **Customizable** - Easy to customize colors and styling
- 🆓 **Open Source** - MIT licensed, free to use and modify

## 📸 Screenshots

### Light Mode

![adminita light dashboard](https://github.com/djangify/adminita/blob/ac1e111dcf7ffae28dcdca60a78dbf32c848d035/adminita-lightdashboard.png)

### Dark Mode
![Dark Mode Dashboard](https://github.com/djangify/adminita/blob/93e527055807d5e6e05b2fa5724f97835ee53232/adminita-dark-mode.png)

## 🚀 Quick Start

### Installation

1. **Install via pip** (recommended for production):

```bash
pip install adminita
```

2. **Or install from source** (for development):

```bash
git clone https://github.com/djangify/adminita.git
cd adminita
pip install -e .
```

### Configuration

1. **Add to INSTALLED_APPS** in your Django settings (must be before `django.contrib.admin`):

```python
INSTALLED_APPS = [
    "adminita",  # Must be FIRST!
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # ... your other apps
]
```

2. **Configure static files**:

```python
STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
```

3. **Add customization to project urls.py file**:
Adminita uses Django's built-in admin site customization. Add these lines to your `urls.py`:
```python
from django.contrib import admin

admin.site.site_header = "Your Site Name"
admin.site.site_title = "Your Site Title" 
admin.site.index_title = "Welcome to Your Site"
```

4. **Collect static files**:

```bash
python manage.py collectstatic --noinput
```

5. **Run your server**:

```bash
python manage.py runserver
```

6. **Visit the admin** at `http://localhost:8000/admin/`

That's it! Your Django admin should now have the Adminita theme applied.

## 🆕 What's New in 0.2.0

- **Security fix** for the "add related object" popup (XSS via object names)
- **Related-field popups fixed**: many-to-many fields keep existing selections, `filter_horizontal` / `filter_vertical` receive new items, and raw ID lookups work
- **Change list actions fixed**: selection counter, "Select all N across pages" and actions after searching or filtering
- **Safer form autosave** with a Restore / Discard prompt
- **Dark mode** now follows your system setting until you use the toggle
- **Logout and password change** pages now use Adminita's design
- Tested on Django 4.2 to 6.0

### Upgrading from 0.1.x

1. Upgrade the package and re-collect static files:

```bash
pip install --upgrade adminita
python manage.py collectstatic --noinput
```

2. If your settings include `"adminita.context_processors.admin_app_list"` in `TEMPLATES`, remove it. It's no longer needed and now only raises a deprecation warning.

3. `AlwaysVisibleAdmin` and `SingletonAdmin` now follow Django's model permissions. Staff users who aren't superusers need view (and change) permission on those models to see them. Superusers are not affected.

## 🎨 Customization

### Changing Colors

Adminita uses Tailwind CSS v4's new `@theme` syntax. To customize colors:

1. **Edit the source CSS** at `adminita/static/src/input.css`:

```css
@theme {
  /* Change primary colors to match your brand */
  --color-primary-500: #10b981; /* Your brand color */
  --color-primary-600: #059669; /* Darker shade */
  --color-primary-700: #047857; /* Even darker */
}
```

2. **Rebuild the CSS**:

```bash
cd path/to/adminita
npm install  # If you haven't already
npm run build
```

3. **Collect static files** in your project:

```bash
python manage.py collectstatic --noinput
```

### Available Color Variables

```css
--color-primary-50 through --color-primary-950
--color-gray-50 through --color-gray-900
--color-gray-750 (custom for dark mode)
```
## 🔧 Utility Classes

Adminita provides utility classes to help with common admin patterns.

### AlwaysVisibleAdmin

Ensures models always appear in the admin index, even if the changelist redirects or add is disabled. Viewing and editing still follow Django's normal model permissions:
```python
from adminita.utils import AlwaysVisibleAdmin

@admin.register(MyModel)
class MyModelAdmin(AlwaysVisibleAdmin):
    pass
```

### SingletonAdmin

For models that should only have one instance (like Site Settings). The changelist goes straight to the existing instance, adding is blocked once one exists (or if the user lacks add permission), and deleting is disabled:
```python
from adminita.utils import SingletonAdmin

@admin.register(SiteConfiguration)
class SiteConfigurationAdmin(SingletonAdmin):
    list_display = ['site_name']
```

## 🛠️ Development

### Setting Up Development Environment

1. **Clone the repository**:

```bash
git clone https://github.com/djangify/adminita.git
cd adminita
```

2. **Create a virtual environment**:

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. **Install dependencies**:

```bash
pip install -r requirements.txt
pip install -e ".[dev]"   # Adminita itself plus pytest, ruff and black
npm install
```

4. **Build CSS**:

```bash
npm run build    # One-time build
npm run watch    # Auto-rebuild on changes
```

5. **Run the demo project**:

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

### Project Structure

```
adminita/
├── adminita/                  # The Django app package
│   ├── static/
│   │   ├── adminita/
│   │   │   ├── adminita-tailwind.css    # Generated CSS (don't edit)
│   │   │   ├── action-fix.css           # Styles for Django's own widget markup
│   │   │   ├── adminita-tailwind.js     # JavaScript for dark mode & mobile menu
│   │   │   └── adminita-autosave.js     # Keeps unsaved form edits (restore/discard banner)
│   │   └── src/
│   │       └── input.css     # Source CSS with Tailwind v4 syntax
│   ├── templates/
│   │   ├── admin/            # Template overrides
│   │   │   ├── base.html
│   │   │   ├── index.html
│   │   │   ├── login.html
│   │   │   ├── change_list.html
│   │   │   └── change_form.html
│   │   └── registration/     # Points Django's logout/password pages at Adminita's versions
│   ├── templatetags/         # adminita_tags (readonly field rendering)
│   ├── utils.py              # AlwaysVisibleAdmin, SingletonAdmin
│   ├── __init__.py
│   └── apps.py
├── config/                    # Django project settings
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── tests/                     # pytest suite
├── manage.py
├── package.json              # Node.js dependencies for Tailwind
├── pyproject.toml            # Python package configuration
└── README.md
```

## Known Limitations

Adminita is usable on mobile, but not yet optimized for it:

- Complex tables - Very wide tables still require horizontal scrolling
- Inline formsets - Tabular inlines are cramped; consider using stacked inlines for mobile-heavy use cases
- Rich text editors - TinyMCE and similar may have their own mobile issues
- Date/time pickers - Django's default widgets are desktop-focused

## Future Improvements (Community PRs Welcome)

 - Card-based table view option for mobile (instead of horizontal scroll)
 - Bottom navigation bar for common actions
 - Pull-to-refresh on list pages
 - Improved inline formset mobile layout
 - Native date/time inputs on mobile (<input type="date">)

## 📚 Documentation

### Tailwind CSS v4 Notes

Adminita uses Tailwind CSS v4, which has a different syntax than v3:

- Uses `@import "tailwindcss"` instead of `@tailwind` directives
- Theme customization uses `@theme {}` blocks in CSS
- More streamlined, CSS-first approach

### Template Inheritance

When extending Adminita templates in your own project:

```django
{% extends "admin/base.html" %}
```

**Not** `adminita/admin/base.html` - Django finds templates automatically because `adminita` is in `INSTALLED_APPS`.

## 🤝 Contributing

We welcome contributions! Adminita is an open-source project and we'd love your help making it better. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide (setup, coding standards, PR process) and our [Code of Conduct](CODE_OF_CONDUCT.md).

### Priority Issues

We especially need help with:

- 📱 **Mobile Responsiveness** - Testing on various devices
- ♿ **Accessibility** - ARIA labels, keyboard navigation, screen reader support
- 🎨 **Additional Themes** - Creating alternative color schemes
- 🧪 **Test Coverage** - Expanding the test suite
- 📝 **Documentation** - Improving guides and examples

## 📦 Requirements

- Python 3.10+ (3.12+ for Django 6.0)
- Django 4.2, 5.0, 5.1, 5.2 or 6.0
- Node.js (for building CSS during development)
- npm (for managing Tailwind CSS)

## 🧪 Testing

```bash
pytest                   # Run the test suite
ruff check .             # Lint
black --check .          # Formatting
```

Tests run automatically on every pull request via GitHub Actions across supported Python/Django versions. Manual checks worth doing before submitting a PR: multiple browsers (Chrome, Firefox, Safari, Edge), dark mode toggle, and responsive layout on mobile.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.

## 👏 Acknowledgments

- Built with [Django](https://www.djangoproject.com/)
- Styled with [Tailwind CSS v4](https://tailwindcss.com/)
- Inspired by modern admin dashboards

## 🔗 Links

- **GitHub**: https://github.com/djangify/adminita
- **Issues**: https://github.com/djangify/adminita/issues
- **PyPI**: https://pypi.org/project/adminita/ 

- **Website - GitHub**: https://github.com/djangify/adminita_demo

- **Website**: https://adminita.todiane.com (demo user login available)


## 💬 Support

Having trouble? Here are some ways to get help:

- 📖 Check the [documentation](https://adminita.todiane.com/infopages/docs)
- 🐛 [Open an issue](https://github.com/djangify/adminita/issues/new)
- 💡 [Start a discussion](https://github.com/djangify/adminita/discussions)

## 🗺️ Roadmap

- [x] Publish to PyPI
- [x] Fix dark mode toggle functionality
- [x] Django 6.0 support
- [ ] Add more customization options
- [ ] Create additional color themes
- [ ] Improve accessibility (ARIA labels, keyboard navigation)
- [ ] Expand automated test coverage
- [ ] Create video tutorials
- [ ] Add support for Django inline forms
- [ ] Create a documentation website

## ⭐ Star History

If you find Adminita useful, please consider giving it a star on GitHub! It helps others discover the project.

---

Made with ❤️ by a Django enthusiast

**Note**: This is an open-source project. I appreciate your patience and contributions!

**Developer**: https://www.todiane.com 

**Developer LinkedIn**: https://linkedin.com/in/todianedev

**Coffee Always Welcome**: https://ko-fi.com/todianedev ❤️


Maintained by [Diane Corriette](https://github.com/todiane)
