django-photo-albums / docs / index.rst

Full commit

django-photo-albums's documentation

django-photo-albums is a pluggable django image gallery app.

Image galleries can be attached to any Django model. And thanks to django 1.1 url namespaces it is possible to have multiple 'albums' app instances (for example, for different models) that use different sets of templates, different permission rules, have dedicated integration test suites and are available from different urls.

Each image gallery provide functionality for image viewing, editing, uploading, uploading entire albums in one zip file, reordering, marking/unmarking as main and deleting.

django-photo-albums is an application based on django-generic-images . django-photo-albums requires Django >= 1.1 (or svn version with url namespaces), setuptools for installation, django-annoying for some utils and django-generic-images for image management and advanced admin image uploader. django-generic-images and django-annoying will be installed automatically if you install django-photo-albums via easy_install or pip.

django-photo-albums does not provide any thumbnail creation solution because there are external django apps (such as sorl-thumbnail) that would do this better.

Testing if app instance is integrated correctly (at least that templates don't raise exceptions) is easy because base class for integration testcases is provided.


$ pip install django-photo-albums


$ easy_install django-photo-albums


$ hg clone
$ cd django-photo-albums
$ python install

Then add 'photo_albums' and 'generic_images' to your INSTALLED_APPS in and run ./ syncdb (syncdb is not needed if django-generic-images was already installed).

Note: django-generic-images app provides admin image uploader (see more in django-generic-images docs ). For this admin uploader to work generic_images folder from generic_images/media/ should be copied to project's MEDIA_ROOT.

Basic use


Templates used by django-photo-albums

Templates usually should be placed in templates/albums/<app_name>/ folder. App_name should be the name of queryset model's app as it appears in contenttypes table (e.g. 'auth' for User). It is possible to override templates per-model (by placing them in templates/albums/<app_name>/<model_name>/ folder) or to have a kind of default fallback templates for several apps (by placing them in templates/albums/ folder).

Common context

Each view have at least 2 variables in context:

  • <template_object_name>: object for which gallery is attached to (the name

    of variable is set in PhotoAlbumsSite constructor (:ref:`here<template_object_name>`), default is 'object')

  • current_app: app name, 'albums' by default


The views included in django-photo-albums make use of these 9 templates:

  • show_album.html displays entire album

  • edit_album.html displays entire album. Used by edit_album view.

  • reorder_images.html displays entire album. Used by reorder_images view.

    These 3 templates have images variable in context with iterable of all images in gallery.


{% for image in images %}
    <img src='{{ image.image }}' alt='{{image.caption}}'>
{% endfor %}

With sorl-thumbnail:

{% for image in images %}
    <img src='{% thumbnail image.image 100x50 %}' alt='{{ image.caption }}'>
{% endfor %}
  • show_image.html - displays one image. Has image, prev and next

    variables in context. prev and next are id's of previous and next (by image.order field) images in gallery.

  • edit_image.html - displays one image for editing purposes. Has form,

    image, prev and next variables in context. prev and next are id's of previous and next (by image.order field) images in gallery. form is a form of :ref:`edit_form_class<edit_form_class>` class.


<img src='{{ image.image }}' alt='{{image.caption}}'>

<a href='{% url user_images:edit_image prev %}'>previous image</a>
<a href='{% url user_images:edit_image next %}'>next image</a>

<form action='' method='POST'>
    {{ form }}
    <input type='submit' value='Save'>


<form action="" method="POST" enctype="multipart/form-data">
    {{ formset }}
    <input type="submit" value="Upload images">
  • upload_main_image.html - displays form for uploading one image. Uploaded

    image becomes main in gallery. Has form in context, it's a form of type :ref:`upload_form_class<upload_form_class>`.

  • upload_zip.html - displays form for uploading zip archive with images.

    Has form in context, it's a form of type :ref:`upload_zip_form_class<upload_zip_form_class>`

  • confirm_delete.html - displays confirmation dialog for deleting image.

    Has image in context. Should have a form that do POST request to delete view on submit.




Integration testing


Issue tracker is here:

Bug reports, feature requests, enhancement suggestions are always welcome.