.. django-photo-albums documentation master file, created by
   sphinx-quickstart on Fri Sep 18 05:13:19 2009.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.
   
.. toctree::
   :maxdepth: 2
   
==============================================
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, reordering, marking/unmarking as main and deleting.

django-photo-albums requires Django >= 1.1 (or svn version with 
url namespaces), setuptools for installation, django-generic-images 
for image management and django-annoying. 

Sorl-thumbnails should be mentioned as a very good optional dependency for 
generating thumbnails, but you can use any other library if you want.

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.

************
Installation
************
::

	$ pip install django-photo-albums

or::

	$ easy_install django-photo-albums

or::

	$ hg clone http://bitbucket.org/kmike/django-photo-albums/ 
	$ cd django-photo-albums
	$ python setup.py install

Then add 'photo_albums' and 'generic_images' to your ``INSTALLED_APPS`` in 
settings.py and run ``./manage.py syncdb`` (syncdb is not needed if 
django-generic-images was already installed).
   
*********
Basic use
*********

PhotoAlbumSite
==============

.. automodule:: photo_albums.urls
	
.. autoclass:: photo_albums.urls.PhotoAlbumSite
	:members: __init__


Templates used by django-photo-albums
=====================================

Templates 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).

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, default is ``object``)	
	
* ``current_app``: app name, 'albums' by default

The views included in django-photo-albums make use of 7 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. 
	Theese 3 templates have ``images`` variable in context with iterable of all 
	images in gallery. 

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

* ``upload_images.html`` - displays the formset for bulk image upload. 
	Formset is of PhotoFormSet type (defined in photo_albums.forms module) and is 
	available as `formset` context variable. 

* ``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 
	AttachedImageForm defined in generic_images.forms module.

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

	
	
Views
=====

.. automodule:: photo_albums.views
	:members:
	:undoc-members:

*******
Testing
*******

Integration testing
===================
	
.. automodule:: photo_albums.test_utils
	:show-inheritance:
	:members:
	:undoc-members: