.. _customisation-admin-label:

####################
Customisation: Admin
####################

The Photologue admin can easily be customised to your project's requirements. The technique described on this page
is not specific to Photologue - it can be applied to any 3rd party library. 

Create a customisation application
----------------------------------
For clarity, it's best to put our customisation code in a new application; let's call it
``photologue_custom``; create the application and add it to your ``INSTALLED_APPS`` setting.


Changing the admin
------------------
In the new ``photologue_custom`` application, create a new empty ``admin.py`` file. In this file we
can replace the admin configuration supplied by Photologue, with a configuration specific to your project.
For example:

.. code-block:: python

    from django import forms
    from django.contrib import admin

    from photologue.admin import GalleryAdmin as GalleryAdminDefault
    from photologue.models import Gallery


    class GalleryAdminForm(forms.ModelForm):
        """Users never need to enter a description on a gallery."""

        class Meta:
            model = Gallery
            exclude = ['description']


    class GalleryAdmin(GalleryAdminDefault):
        form = GalleryAdminForm

    admin.site.unregister(Gallery)
    admin.site.register(Gallery, GalleryAdmin)


This snippet will define a new Gallery admin class based on Photologue's own. The only change we make
is to exclude the ``description`` field from the change form.

We then unregister the default admin for the Gallery model and replace it with our new class.

Possible uses
-------------

The technique outlined above can be used to make many changes to the admin; here are a couple of suggestions.

Custom rich text editors
~~~~~~~~~~~~~~~~~~~~~~~~
The description field on the Gallery model (and the caption field on the Photo model) are plain text fields.
With the above technique, it's easy to use a rich text editor to manage these fields in the admin. For example,
if you have `django-ckeditor <https://github.com/shaunsephton/django-ckeditor>`_ installed:

.. code-block:: python

    from django import forms
    from django.contrib import admin

    from ckeditor.widgets import CKEditorWidget
    from photologue.admin import GalleryAdmin as GalleryAdminDefault
    from photologue.models import Gallery


    class GalleryAdminForm(forms.ModelForm):
        """Replace the default description field, with one that uses a custom widget."""

        description = forms.CharField(widget=CKEditorWidget())

        class Meta:
            model = Gallery
            exclude = ['']


    class GalleryAdmin(GalleryAdminDefault):
        form = GalleryAdminForm

    admin.site.unregister(Gallery)
    admin.site.register(Gallery, GalleryAdmin)