Metadata-Version: 2.1
Name: django-adminplus
Version: 0.6
Summary: Add new pages to the Django admin.
Author-email: James Socol <me@jamessocol.com>
License: Copyright (c) 2023, James Socol
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification,
        are permitted provided that the following conditions are met:
        
            1. Redistributions of source code must retain the above copyright notice,
               this list of conditions and the following disclaimer.
        
            2. Redistributions in binary form must reproduce the above copyright
               notice, this list of conditions and the following disclaimer in the
               documentation and/or other materials provided with the distribution.
        
            3. Neither the name of AdminPlus nor the names of its contributors may
               be used to endorse or promote products derived from this software
               without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        
Project-URL: Homepage, https://github.com/jsocol/django-adminplus
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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: Framework :: Django
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE

================
Django AdminPlus
================

**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.

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.


.. image:: https://github.com/jsocol/django-adminplus/actions/workflows/ci.yml/badge.svg?branch=main
   :target: https://github.com/jsocol/django-adminplus


Installing AdminPlus
====================

Install from `PyPI <https://pypi.python.org/pypi/django-adminplus>`_ with pip:

.. code-block:: bash

    pip install django-adminplus

Or get AdminPlus from `GitHub <https://github.com/jsocol/django-adminplus>`_
with pip:

.. code-block:: bash

    pip install -e git://github.com/jsocol/django-adminplus#egg=django-adminplus

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

.. code-block:: python

    INSTALLED_APPS = (
        'django.contrib.admin.apps.SimpleAdminConfig',
        # ...
        '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()``:

.. code-block:: python

    # urls.py
    from django.contrib import admin
    from adminplus.sites import AdminSitePlus

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

    urlpatterns = [
        # ...
        # Include the admin URL conf as normal.
        (r'^admin', include(admin.site.urls)),
        # ...
    ]

Congratulations! You're now using AdminPlus.


Using AdminPlus
===============

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:

.. code-block:: 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:

.. code-block:: 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:

  .. code-block:: 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.
