Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jsocol/django-adminplus

Easily add custom views to the Django admin.
https://github.com/jsocol/django-adminplus

Last synced: about 8 hours ago
JSON representation

Easily add custom views to the Django admin.

Awesome Lists containing this project

README 

        
================

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 `_

and `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 `_ with pip:



.. code-block:: bash



    pip install django-adminplus



Or get AdminPlus from `GitHub `_

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.