==========================================
Stockphoto: a photogallery for django
==========================================

Introduction
------------

Stockphoto is a photogallery application written using the Django_
web application framework.  It is designed to integrate into existing
dynamic websites built with Django, to be easy to install, and to have
few prerequisites, both in terms of third-party modules and in terms
of expectations about site layout.  It attempts to make maximum use of
built-in Django facilities (authentication, admin pages, generic
views) as much as possible in order to provide the simplest possible
photogallery application while providing a reasonably full set of
features. 

There are quite probably better photogallery applications out there,
but the best one I looked at also had a lot of requirements and was
complex to install.  Stockphoto has limited ambitions: it is not
supposed to be a Flickr_ replacement, but just an easy way to add a
photogallery section to a website.

.. _Django: http://www.djangoproject.com/
.. _Flickr: http://www.flickr.com/

Installation
------------

Requirements
~~~~~~~~~~~~~~~~~~~~

This document refers to version 0.2.1 of stockphoto.

+ PIL_ (Python Imaging Library)
+ Django_ 0.96 or later SVN trunk 
+ recommended: Patch your Django installation against `ticket 2070`_

.. _PIL: http://www.pythonware.com/products/pil/
.. _Django: http://www.djangoproject.com/
.. _`ticket 2070`: http://code.djangoproject.com/ticket/2070

The patch listed above is probably necessary if you intend to batch
upload large photographs (in zip archives) to your gallery, rather
than upload them one at a time.


Procedure
~~~~~~~~~~~~~~~~~~~~

This package uses setuptools.  You can install it using ``python
./setup.py install``, for example.  Add ``"stockphoto"`` to your
``INSTALLED_APPS`` variable in ``settings.py``.

Stockphoto makes use of Django's admin and auth applications, so
django.contrib.admin and django.contrib.auth must be in your installed
apps.  You should probably have the admin interface working *before*
trying to install stockphoto.

There are a number of *optional* settings you can add to
``settings.py``, as well.  These are:

+ ``STOCKPHOTO_BASE``: the path under ``MEDIA_ROOT`` where photos will be
  stored; defaults to ``stockphoto``.
+ ``STOCKPHOTO_URL``: the base URL to the stockphoto views on your site;
  defaults to ``/stockphoto``.  This is used primarily by the "view on
  site" feature on the admin pages.
+ ``ADMIN_URL``: the base url to the Django admin app on your site;
  defaults to ``/admin``.  If your admin app is not in the standard
  location, you will need this in order to jump from galleries or
  photos to their admin pages.

You must have ``MEDIA_ROOT`` and ``MEDIA_URL`` set to sensible values for
the gallery to work.  Once your ``settings.py`` is set up, you can run

+ yourproject/manage.py syncdb

Add this line to your urls.py:
``(r'^stockphoto/', include('stockphoto.urls')),``

You will probably want to install your own templates, but the included
ones should get you up and running.  The templates all inherit from
the template stockphoto/base.html, which does nothing but inherit from
site_base.html.  If your site's main template is not called
site_base.html, you will need to change this.  Also, the default
templates expect your site's main template to contain the blocks
"title" and "content" for overriding.

Using
-------

You can install new galleries and single photos through the admin
interface.  The *sample* templates included provide links to the admin
interface for logged in users, and access to the batch upload and
export features.

Features
------------

+ Images are stored with thumbnails, presentation-sized images, and
  full-size source images.
+ Images are served by your webserver, not by the application server,
  and they are only generated when an image is uploaded or otherwise
  changed.
+ Images can be imported from uploaded zipfiles, allowing you to
  upload more than one photo at a time.
+ Galleries can be exported as zipfiles full of images.

Future Features
-----------------

+ Remote import

  Images should be importable from remote zipfiles (by URL), allowing
  you to easily import photos from online film processing sites.

+ Tagging

  Currently, photos are organized only by gallery.  In the future, it
  will be possible to search by tags in order to organize photos in
  other ways.

+ Searching

  Support for searching all text fields associated with photos is
  planned.

+ Manual re-ordering

  It might make sense for there to be a way to manually re-order
  photographs, especially if they were batch-imported.

+ Non-browseable galleries

  You might wish to use stockphoto to manage images for your blog app,
  for example, but not wish to have the images in a browseable
  gallery. 

+ Automatic rotation of images based on EXIF tags

+ Better reverse url resolution
  
Bugs
--------

+ Without the Django patch listed above, the batch import feature is only
  likely to work for very small archives.
+ The included templates are not very good.
+ The views should probably use slugs rather than object ids.

Contributors
--------------------

Special thanks to Guillermo Fernandez Castellanos, William McVey, Amit
Ramon, and Evgeniy Tarassov for contributing patches to stockphoto's
development, and to the many others who submitted bug reports on 0.2,
and to anyone I may have forgotten.

Contact
--------
Contact jmcbray-django@carcosa.net for more information.