Singleshot
==========

Web page
--------

Singleshot's home page is 
   http://www.singleshot.org/
   
There you will find this information as well as the current release.


Overview
--------

Web-based photo album software that requires minimal work after initial
setup. There is no external data and your album hierarchy can be maintained
by updating the files and directories in that tree. The administrator of the
singleshot installation can use Web server permissions to restrict access to
albums.

Singleshot does not require a special process or program for sharing photos.
You post the photos to your albums using the file upload program of your
choice.


Requirements
------------

You will need the following software installed on your web server
to install Singleshot.

   * Apache http://www.apache.org/ with mod_rewrite
   * Python 2.5+ http://www.python.org/
   * ImageMagick http://www.imagemagick.org

Singleshot relies on setting mod_rewrite directives in .htaccess.
This facility needs to be enabled on the web server.

You will also need an appropriate unpacking tool to unpack the
Singleshot archive.

Definitions
-----------

album root
    The directory that will become the root album of your new
Singleshot installation. Apache needs to be configured to serve this
directory.

.htaccess
    File with directives to Apache to set up permissions, rewrite
rules, or other options. Singleshot comes with two of these, one for
the singleshot directory and one for the album root.

Instructions
------------

Instructions

1. Download and unpack Singleshot.

2. If you want Singleshot installed with the other Python libraries in
site-packages, run python setup.py install.  Otherwise, skip this
step.

3. To set up a new album root using Singleshot, use the
singleshotinit.py script.  It's in the scripts/ directory of the
unpacked SIngleshot distribution, or with the other
Python-library-installed scripts if you installed Singleshot into
site-packages.

4. Run singleshotinit.py -h to see a list of the command line options.
Generally, you'll want either the --standalone install.  If you
installed Singleshot in a place not normally on sys.path (e.g. by
using the --home option to setup.py install), you'll need to either
put that on PYTHONPATH before running singleshotinit or tell
singleshot init about it using --path.

For example, suppose I wanted to get Singleshot running in my personal
web directory ~/public_html/photos which will show up on my web server
as /~fox/photos/ and I didn't want to install it in site-packages.

I'd unpack Singleshot's archive, cd into the directory, and run

./scripts/singleshotinit.py --root ~/public_html/photos --url /~fox/photos/ --standalone

Configurable things
-------------------------

Where ALBUMROOT is where you put your album root (--root above):

ALBUMROOT/_singleshot.cfg can also have (and default to the values below):

[imagesizes]
mini=40
thumb=200
view=600
large=1200

The imagesizes section is very important: it limits what sizes of
images can be requested from your album originals.  With the above
configuration, downloads are limited to a max of 40, 200, 600, or 1200
pixels on a side. (That is, any picture downloaded will be scaled down
from the original size to one of the appropriate sizes) In a template,
referring to a size by number means 'show me that size or nothing',
but referring to a size by name means 'show me a permitted size no
larger than the one I asked for'.

_album.cfg in every directory can have:

    [album]
    title=foo                ; sets the title of the album to foo
    highlightimage=file.jpg  ; uses file.jpg (in the current dir) as the 'cover' of the album
                             ; default is to use the first image in the directory
    order=dir,title,-mtime   ; sort order for display.  Valid orders are:
                             ;   title, dir, mtime, exifdate, name, href
                             ;  prepending '-' sorts in descending order instead of ascending 


ALBUMROOT/pages can be a directory with files in it.   foo.html will show up as URLROOT/foo/ and will display the contents of foo.html.

This is to enable you to easily create static pages on the site with the photos.

Writing templates
-----------------

http://www.owlfish.com/software/simpleTAL/tal-guide.html describes the syntax of the templating system used by Singleshot 2.x.

(** document attributes and objects exposed to templates **)