1. Mikhail Korobov
  2. django-photo-albums

Commits

Mikhail Korobov  committed d70fdcf

Better documentation

  • Participants
  • Parent commits a8d2511
  • Branches default

Comments (0)

Files changed (2)

File README

View file
 
-= Overview =
+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.
+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 a very good optional dependency for generating thumbnails.
+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.
 
-= Installation =
+Each image gallery provide functionality for image viewing, editing, 
+uploading, reordering, marking/unmarking as main and deleting.
+
+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
-$ 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.
+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).
 
 
-= Adding photo albums site to existing model =
+Basic use
+=========
 
-1. Create site instance and plug it's urls to urlconf:
+To add image gallery for model you should complete following steps:
 
-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)),)
+1. Create album site instance and plug it's urls to urlconf:
 
-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.
+		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)),)
 
-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).
+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.
 
-Templates are:
-* confirm_delete.html
-* edit_album.html
-* reorder_images.html
-* show_album.html
-* show_image.html
-* upload_images.html
-* upload_main_image.html
+Included urls looks like "<object_id>/<app_name>/<action>" or 
+"<object_id>/<app_name>/<image_id>/<action>",
+where object_id is the id of object which is gallery attached to, 
+app_name is "albums" by default, image_id is image id :) and action 
+is performed action (view, edit, etc).
 
-TODO: explain each template's context and purpose
+2. Create the necessary templates (see the section on templates below
+   for details). 
+   
+3. Link people to image gallery using {% url .. %} template tag.
 
-3. That's all! You can now add links to album views in templates using url reversing. Provided views (and example url tags):
+You can use theese urls (assuming that `user_images` in an instance name,
+`album_user` is object for which gallery is attached to, `image` is image 
+in gallery):
 
-{% url user_images:show_album album_user.id %}
+		{% 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 %}
 
-{% 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 %}
+Templates used by django-photo-albums
+=====================================
 
-{% url user_images:reorder_images album_user.id %}
-{% url user_images:set_image_order album_user.id %}
+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
+	'current_app': app name, 'albums' by default
 
-== PhotoAlbumSite constructor parameters ==
+The views included in django-photo-albums make use of 7 templates:
 
-* instance_name - Required. App instance name for url reversing. Must be unique.
+* ``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. 
 
-* queryset - Required. Albums will be attached to objects in this queryset.
+* ``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.
 
-* app_name - Optional, default value is 'album'. 
+* ``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. 
 
-* extra_context - Optional. Extra context that will be passed to all views.
+* ``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.
 
-* template_object_name  - Optional. The name of template context variable with object 
-for which album is attached. Default is 'object'.
+* ``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.
 
-* 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.
 
+PhotoAlbumSite constructor parameters
+=====================================
 
-== Testing ==
+* ``instance_name`` - Required. App instance name for url reversing. 
+Must be unique.
 
-TODO: describe photo_albums.test_utils.AlbumTest
+* ``queryset`` - Required. Albums will be attached to objects in this queryset.
+
+* ``app_name`` - Optional, default value is 'album'. Used by url namespaces stuff.
+
+* ``extra_context`` - Optional. Extra context that will be passed to each view.
+
+* ``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 
+returns True if user is allowed to edit album for object and false otherwise. 
+Default behaviour is to always return True.
+
+* ``context_processors`` - list of callables that will be used as 
+additional context_processors in each view
+
+
+Provided views
+==============
+
+* ``show_album`` - show album for object using show_album.html template
+* ``edit_album`` - same as ``show_album`` view but with login_required decorator
+* ``upload_main_image`` - upload 1 image and make it main image in gallery
+* ``upload_images`` - upload several images at once
+* ``show_image`` - show one image
+* ``edit_image`` - same as `show_image` but with login_required decorator
+* ``delete_image`` - delete image if request method is POST, displays 
+`confirm_delete.html` template otherwise
+* ``set_as_main_image`` - mark image as main and redirect back
+* ``clear_main_image`` - mark image as not main and redirect back
+* ``reorder_images`` - same as `edit_album` but using `reorder_images.html` template
+* ``set_image_order`` - ajax view that can be used to implement image reorder
+functionality. Accepts json data in form 
+
+		{'items': '[
+						{"id":"<id1>", "order":"<order1>"},
+						{"id":"<id2>", "order":"<order2>"}, 
+						...
+				    ]'
+	    }
+	    
+and assigns passed order to images with passed id's, with permission checks. 
+
+
+Integration testing
+===================
+
+django-phto-albums provides base class (photo_albums.test_utils.AlbumTest) for 
+writing integration tests for app instances. 
+
+The example usage:
+
+		from accounts.urls import accounts_photo_site
+		from photo_albums import test_utils
+		
+		class UserAlbumTest(test_utils.AlbumTest):
+			# existing user's data
+		    username = 'obiwanus' 
+		    password = 'vasia'
+		    
+		    # fixtures with  to be loaded (at least with users, images and 
+		    # objects with galleries)
+		    fixtures = ['my_fixtures']
+		    
+		    # app instance which is to be tested
+		    album_site = accounts_photo_site
+			
+			# we don't need edit_image view and don't create template for it
+			# so it should be excluded from testing
+		    excluded_views = ['edit_image']
+		    
+		    # id of object for which album is attached
+		    album_for_id = 4
+		    
+		    # id's of various images: 2 images in album (second is nedded if tou want 
+		    # to test reordering) and one image in other album to test permission checks
+		    image_in_album_id = 48
+		    image2_in_album_id = 66
+		    image_in_other_album_id = 42    
+		        
+If you don't use fixtures you can override setUp method and create necessery 
+objects there. 

File setup.py

View file
 
 setup(
       name='django-photo-albums',
-      version='0.11',
+      version='0.12',
       author='Mikhail Korobov',
       author_email='kmike84@gmail.com',
       url='http://bitbucket.org/kmike/django-photo-albums/',