Metadata-Version: 2.4
Name: django-sb-adminplus
Version: 0.7.0
Summary: Add new pages to the Django admin.
Keywords: admin,django,dynova,softbutterfly
Author: Dynova Development Team, zodiacfireworks, James Socol
Author-email: Dynova Development Team <dev@dynova.io>, zodiacfireworks <martin.vuelta@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django :: 4
Classifier: Framework :: Django :: 5
Classifier: Framework :: Django :: 6
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: django>=4.2
Maintainer: zodiacfireworks
Maintainer-email: zodiacfireworks <martin.vuelta@gmail.com>
Requires-Python: >=3.11.0, <4.0.0
Project-URL: Bug Tracker, https://gitlab.com/softbutterfly/open-source/django-sb-adminplus/-/issues
Project-URL: Changelog, https://gitlab.com/softbutterfly/open-source/django-sb-adminplus/-/blob/v0.7.0/CHANGELOG.md
Project-URL: Documentation, https://softbutterfly.gitlab.io/open-source/django-sb-adminplus
Project-URL: Download, https://gitlab.com/softbutterfly/open-source/django-sb-adminplus/-/archive/v0.7.0/django-sb-adminplus-v0.7.0.tar.gz
Project-URL: Homepage, https://gitlab.com/softbutterfly/open-source/django-sb-adminplus
Project-URL: Issues, https://gitlab.com/softbutterfly/open-source/django-sb-adminplus/-/issues
Project-URL: Repository, https://gitlab.com/softbutterfly/open-source/wagtail-sb-structblock
Description-Content-Type: text/markdown

# Django Admin Plus

**Custom Wiews for Django Admin made simple.**

![Community-Project][repository:banner]

![PyPI - Supported versions][pypi:badge:python]
![PyPI - Package version][pypi:badge:version]
![PyPI - Downloads][pypi:badge:downloads]
![PyPI - License][pypi:badge:license]
[![Codacy Grade Badge][codacy:grade]][codacy:dashboard]
[![Codacy Coverage Badge][codacy:coverage]][codacy:dashboard]
[![Gitlab Pipeline Status][repository:pipeline]][repository:commits]

**AdminPlus** aims to be the smallest possible extension to the
excellent Django admin component that lets you add admin views that are
not tied to models.

## 📜 About and Motivation

Forked from <https://github.com/jsocol/django-adminplus>

There are packages out there, like
[Nexus](https://github.com/disqus/nexus) and
[django-admin-tools](http://pypi.python.org/pypi/django-admin-tools)
that replace the entire admin. Nexus supports adding completely new
"modules" (the Django model admin is a default module) but there seems
to be a lot of boiler plate code to do it. django-admin-tools does not,
as far as I can tell, support adding custom pages.

All AdminPlus does is allow you to add simple custom views (well, they
can be as complex as you like!) without mucking about with hijacking
URLs, and providing links to them right in the admin index.

## ✨ Features

## 📋 Requirements

- Python 3.11 or higher
- Django 4.2 or higher

## 📦 Installation

### Using pip

```bash
pip install django-sb-adminplus
```

### Using uv

```bash
uv add django-sb-adminplus
```

## 🚀 Usage

And add `django_sb_adminplus` to your installed apps, and replace
`django.contrib.admin` with
`django.contrib.admin.apps.SimpleAdminConfig`:

```python
INSTALLED_APPS = (
    'django.contrib.admin.apps.SimpleAdminConfig',
    # ...
    'django_sb_adminplus',
    # ...
)
```

To use AdminPlus in your Django project, you'll need to replace
`django.contrib.admin.site`, which is an instance of
`django.contrib.admin.sites.AdminSite`. I recommend doing this in
`urls.py` right before calling `admin.autodiscover()`:

```python
# urls.py
from django.contrib import admin
from django.urls import path
from django_sb_adminplus.sites import AdminSitePlus

admin.site = AdminSitePlus()
admin.autodiscover()

urlpatterns = [
    # ...
    # Include the admin URL conf as normal.
    path('admin/', admin.site.urls),
    # ...
]
```

Congratulations! You're now using AdminPlus.

### Create custom views

So now that you've installed AdminPlus, you'll want to use it.
AdminPlus is 100% compatible with the built in admin module, so if
you've been using that, you shouldn't have to change anything.

AdminPlus offers a new function, `admin.site.register_view`, to attach
arbitrary views to the admin:

```python
# someapp/admin.py
# Assuming you've replaced django.contrib.admin.site as above.
from django.contrib import admin

def my_view(request, *args, **kwargs):
    pass

admin.site.register_view('somepath', view=my_view)

# And of course, this still works:
from someapp.models import MyModel
admin.site.register(MyModel)
```

Now `my_view` will be accessible at `admin/somepath` and there will be a
link to it in the *Custom Views* section of the admin index.

You can also use `register_view` as a decorator:

```python
@admin.site.register_view('somepath')
def my_view(request):
    pass
```

`register_view` takes some optional arguments:

- `name`: a friendly name for display in the list of custom views. For
  example:

    ```python
    def my_view(request):
        """Does something fancy!"""
    admin.site.register_view('somepath', 'My Fancy Admin View!', view=my_view)
    ```

- `urlname`: give a name to the urlpattern so it can be called by
  `redirect()`, `reverse()`, etc. The view will be added to the
  `admin` namespace, so a urlname of `foo` would be reversed with
  `reverse("admin:foo")`.

- `visible`: a boolean or a callable returning one, that defines if
  the custom view is visible in the admin dashboard.

All registered views are wrapped in `admin.site.admin_view`.

> **Note**
>
> Views with URLs that match auto-discovered URLs (e.g. those created via ModelAdmins) will override the auto-discovered URL.

[repository:banner]: https://gitlab.com/softbutterfly/open-source/open-source-office/-/raw/master/assets/dynova/dynova-open-source--banner--fork.png

[repository:pipeline]: https://gitlab.com/softbutterfly/open-source/django-sb-adminplus/badges/master/pipeline.svg
[repository:commits]: https://gitlab.com/softbutterfly/open-source/django-sb-adminplus/-/commits/master

[pypi:badge:python]: https://img.shields.io/pypi/pyversions/django-sb-adminplus
[pypi:badge:version]: https://img.shields.io/pypi/v/django-sb-adminplus
[pypi:badge:downloads]: https://img.shields.io/pypi/dm/django-sb-adminplus
[pypi:badge:license]: https://img.shields.io/pypi/l/django-sb-adminplus

[codacy:grade]: https://app.codacy.com/project/badge/Grade/f6c0d2a6605d4ca784b59661351e3820
[codacy:coverage]: https://app.codacy.com/project/badge/Coverage/f6c0d2a6605d4ca784b59661351e3820
[codacy:dashboard]: https://app.codacy.com/gl/softbutterfly/django-sb-adminplus/dashboard
