
= Overview =

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

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

Sorl-thumbnails should be mentioned as an very good optional dependency for generating thumbnails.

= Installation =

$ easy_install django-photo-albums

or
$ pip 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' to your INSTALLED_APPS in settings.py.


= Adding photo albums site to existing model =

1. Create site instance and plug it's urls to urlconf:

from photo_albums.urls import PhotoAlbumSite
accounts_photo_site = PhotoAlbumSite(instance_name = 'user_images', 
                                     queryset = User.objects.all(), 
                                     template_object_name = 'album_user',
                                     has_edit_permission = lambda request, obj: request.user==obj) 
urlpatterns += patterns('', url(r'^accounts/', include(accounts_photo_site.urls)),)

Please note that if you deploy multiple albums (ex. for different models), you must 
provide unique ``instance_name`` for each instance to make url reversing work.

2. Create templates for views you need 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).

Templates are:
* confirm_delete.html
* edit_album.html
* reorder_images.html
* show_album.html
* show_image.html
* upload_images.html
* upload_main_image.html

TODO: explain each template's context and purpose

3. Add links to views in templates using url reversing. Provided views (and example url tags):

{% url user_images:show_album album_user.id %}

{% url user_images:edit_album album_user.id %}
{% url user_images:upload_main_image album_user.id %}
{% url user_images:upload_images album_user.id %}

{% url user_images:show_image album_user.id image.id %}
{% url user_images:edit_image album_user.id image.id %}
{% url user_images:delete_image album_user.id image.id %}
{% url user_images:set_as_main_image album_user.id image.id %}
{% url user_images:clear_main_image album_user.id image.id %}

{% url user_images:reorder_images album_user.id %}
{% url user_images:set_image_order album_user.id %}


== PhotoAlbumSite constructor parameters ==

* instance_name - Required. App instance name for url reversing. Must be unique.

* queryset - Required. Albums will be attached to objects in this queryset.

* app_name - Optional, default value is 'album'. 

* extra_context - Optional. Extra context that will be passed to all views.

* template_object_name  - Optional. The name of template context variable with object 
for which album is attached. Default is 'object'.

* has_edit_permission =- function that accepts request and object and return True if 
user is allowed to edit album for object and false otherwise. Default behaviour is to always return True.


== Testing ==

TODO: describe photo_albums.test_utils.AlbumTest