django-content-gallery 1.0.0b1
 The Django application allows to attach a collection of images to objects of any model of any app
License: BSD-3-Clause
Keywords: django image gallery photo

django-content-gallery
======================

.. image:: https://travis-ci.org/Kemaweyan/django-content-gallery.svg?branch=master
    :target: https://travis-ci.org/Kemaweyan/django-content-gallery
.. image:: https://coveralls.io/repos/github/Kemaweyan/django-content-gallery/badge.svg?branch=master
    :target: https://coveralls.io/github/Kemaweyan/django-content-gallery?branch=master

**django-content-gallery** is a Django application that allows to attach a collection
of images to objects of any models in you Django projects. It also allows you easily
add and remove images, re-attach images to another object (i.e. move an image to another
collection) and change an order of images in the collection as well.

The **django-content-gallery** creates 5 images with different sizes for each uploaded image:

* a large image viewed in the gallery for users with high-resulution displays
* a small image viewed in the gallery for users with low-resulution displays
* a large preview image used in a preview
* a small preview image used in a small preview
* a thumbnail viewed in the list of available images


Requirements
============

* **Python** 3.4+
* **Django** 1.10+
* **Pillow** 3.0.0+
* **python-magic** 0.4.2+
* **awesome-slugify** 1.6+
* **django-admin-jqueryui112** 1.12.1+

.. NOTE::
	Windows users should also copy ``magic1.dll``, ``regex2.dll`` and ``zlib1.dll`` onto
	the PATH. These libraries are required by the **python-magic** package and could be
	downloaded on the `File for Windows <http://gnuwin32.sourceforge.net/packages/file.htm>`_
	official page.


Installation
============

To install the **django-content-gallery** type following command:

.. code-block::

    $ pip install django-content-gallery

Then add the ``content_gallery`` to INSTALLED_APPS in the settings of your project and the
``admin_jqueryui`` to enable sorting images in the admin panel:

.. code-block::

    INSTALLED_APPS = [
        ...
        'content_gallery',
        'admin_jqueryui',
    ]

Add the ``content_gallery.urls`` to the urls.py of your project (you could use any
URL pattern, not only ``^content_gallery\``):

.. code-block::

    urlpatterns = [
        ...
        url(r'^content_gallery/', include('content_gallery.urls')),
    ]

Create tables in the database using the ``migrate`` command:

.. code-block::

    $ python manage.py migrate content_gallery

Now the **django-content-gallery** is ready for use!


Configuration
=============

To change settings of the **django-content-gallery** set the ``CONTENT_GALLERY`` dict
in your ``settings.py`` module. The dict could contain following items:

* **image_width** - the target width of the large image
* **image_height** - the target height of the large image

* **small_image_width** - the target width of the small image
* **small_image_height** - the target height of the small image

* **thumbnail_width** - the target width of the thumbnail
* **thumbnail_height** - the target height of the thumbnail

* **preview_width** - the target width of the large preview
* **preview_height** - the target height of the large preview

* **small_preview_width** - the target width of the small preview
* **small_preview_height** - the target height of the small preview

* **path** - the subdirectory in the ``MEDIA_ROOT`` where image files would be stored

Default values of these settings are

* **image_width** = 752
* **image_height** = 608
* **small_image_width** = 564
* **small_image_height** = 456
* **thumbnail_width** = 94
* **thumbnail_height** = 76
* **preview_width** = 376
* **preview_height** = 304
* **small_preview_width** = 141
* **small_preview_height** =114
* **path** = 'content_gallery'

You could change some of these settings and keep the rest undefined in you ``settings.py``,
in this case the default values would be used instead:

.. code-block::

	CONTENT_GALLERY = {
		"image_width": 1024,
		"image_height": 768,
	}

This code changes size of the large image only, the rest of settings values would be default.

Usage
=====

To make your models able to attach a gallery, use the ``ContentGalleryMixin`` in
models you want to use the content-gallery with:

.. code-block::

    from django.db import models
    from content_gallery.models import ContentGalleryMixin

    class YourModel(ContentGalleryMixin, models.Model):
        ...

Also to be able to edit attached image collection on the admin page of your model,
you need to add the ``ImageAdminInline`` to inlines of your model admin. Add following
code to your admin.py

.. code-block::

    from django.contrib import admin
    from content_gallery.admin import ImageAdminInline
    from . import models

    class YourModelAdmin(admin.ModelAdmin):
        inlines = [
            ImageAdminInline,
        ]

    admin.site.register(models.YourModel, YourModelAdmin)

Now the **django-content-gallery** is available for your models. Then you need to add the
content-gallery to your pages.

First of all add the ``content_gallery/_image_view.html`` template to your templates where you
want the content-gallery to be available:

.. code-block::

    {% include "content_gallery/_image_view.html" %}

The **django-content-gallery** uses jQuery within its scripts, so make sure that jQuery is
available on your pages where the content-gallery is used.

To add the gallery related to your objects onto your pages the **django-content-gallery** provides
two template tags. Those template tags are located in the ``content_gallery`` template tag set, so
before use them you should load this set:

.. code-block::

	{% load content_gallery %}

The first template tag named ``gallery_preview`` adds the large preview. It uses one argument which
is your object. This tag is meant to be used generally in templates of detail views:

.. code-block::

	{% gallery_preview your_object %}

This code adds the preview widget that shows a preview of the first image related to the object.
 
The ``gallery_small_preview`` tag adds a small preview onto the page, it uses such object as an
argument as well, and is meant to be used generally in templates of list views:

.. code-block::

	{% gallery_small_preview your_object %}

This code adds the small preview widget that shows a small preview of the first image related
to the object.

Also the **django-content-gallery** provides a simple template tag named ``gallery_image_data``
that also gets an object as an argument and returns a dict object that contains an object of
the first image and JSON data for constructing a link to the object. You could use this template
tag to construct you own custom widgets.

For more details, see the **content_gallery_testapp** which is an example of
the **django-content-gallery** usage.