PhotoStack

About PhotoStack
License
Installation Requirements
Installation & Configuration
Organization
Albums
Photos
Thumbnails
- Thumbnail Creation
- Flushing
Templates
Template Tags

About

What?

PhotoStack is an image organization system written in PHP, featuring a template driven layout , smart caching, automatic thumbnail creation, RSS feeds, picture level EXIF date extraction, and picture level descriptions, all without the need for an SQL like database.

Who?

Noel D. Jackson — noel@noeljackson.com

Where?

PhotoStack.org and dev.PhotoStack.org

License

This work is licensed under the Creative Commons Attribution-NoDerivs-NonCommercial License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nd-nc/1.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA

Installation Requirements

PHP
GD Graphics Library: PhotoStack requires GD 2.0 or greater..
FTP Access to your webserver (with appropriate path info).
The PHP FTP module compiled into your installation — without this web based organization will not work.

Installation & Configuration

Configuration and installation is relatively simple. Below is a quick setup guide.

Upload all files from the .zip archive to your installation directory.
Edit config.php in a text editor.
Change the permission on the storage directory to 777.
The fake album is now set up. Go to your installation directory with your web browser.
Edit albums.txt using the format "albumfolder:Album Name", creating a folder for each album you input.
If you have the PHP FTP module installed, go to the "organize" directory in your web browser for easy album management.

Organization

Web based organization is simple. Simply append /organize to your installation to be greeted with the web interface. For example: http://yourhost.com/photos/organize/

Albums

There are just a few steps to getting your albums set up:

Edit albums.txt. Use the format albumfolder:Album's Title. On each line put a different album.
Create a folder for each album, with the name that you specified in albumfolder:Album's Title.
Upload your photos to the albumfolder directory of each different album folder.
Rinse, lather, repeat.

The album descriptions will be placed in a text file in the root of your photostack directory called albums.txt (you can change the name in config.php). The format is albumfolder:Album's Title.

If my album folder was going to be newyork and I wanted the description to be New York 2002 I would simply put newyork:New York2002 in the albums.txt file. Each album entry is on a separate line. A possible albums.txt file could be:

stephanie:Stephanie newyork:NY and PA 2002 nature:Nature babylily:Baby Lily

Edit albums.txt replacing albumfolder:Album's Name with the album folder and album names that you wish to create. Create a folder for each of your album folders.

This listing would look something like this:

To make the album live, create a folder correpsonding to the name that you specified as your album folder and place your photos in this directory.

A directory structure for an installation with one album with the folder of 'newyork' would look something like this:

.
|-- README.txt
|-- album1
|   |-- DSCN0009.jpg
|   |-- DSCN0030.jpg
|   |-- DSCN0035.jpg
|   |-- DSCN0038.jpg
|   |-- DSCN0050.jpg
|   `-- desc.txt
|-- album2
|   |-- DSCN0009.jpg
|   |-- DSCN0030.jpg
|   |-- DSCN0035.jpg
|   |-- DSCN0038.jpg
|   |-- DSCN0050.jpg
|   `-- desc.txt
|-- album3
|   |-- DSCN0009.jpg
|   |-- DSCN0030.jpg
|   |-- DSCN0035.jpg
|   |-- DSCN0038.jpg
|   |-- DSCN0050.jpg
|   `-- desc.txt
|-- albums.txt
|-- config-template.php
|-- config.php
|-- htaccess
|-- index.php
|-- info.php
|-- js-fadein.js
|-- license.txt
|-- loading.gif
|-- manual.html
|-- organize
|   |-- ...
|-- photostack.php
|-- photostack.tmproj
|-- pw.php
|-- rss.tmpl.php
|-- search.php
|-- storage
`-- style.css

Overriding Automatic Dates

The default date for your album is chosen from the date of the first photo in that album. First taking the date from the EXIF metadata (time of exposure) second taking that from the file's last modified time.

If your camera does not support EXIF data (most digital cameras do), or if it gets stripped out somehow (PhotoShop Web Save) you can manually set the album's date.

Simply make that album's line in the format albumid:Album's Title:albumdate. It doesn't matter what format the date is in, as long as it is a standard format. The date will automatically be converted to the proper date format using strtotime() with the format specified at $this->photostack['dateFormat'] in config.php. Possible formats:

10 September 2000
9/10/00
September 10th 2000

Photos

Display Order

By default, photos are displayed in natural order, which is basically, enhanced alphabetical order. However, you can change the display order by editing the appropriate options in config.php.

The desc.txt file can be used to designate an explicit photo order. Just edit config.php accordingly.

Descriptions and Extended Descriptions

A desc.txt file is not needed, and if not supplied, the description will default to the name of the photo such as DSCN0009.jpg if there is no desc.txt entry for that photo.

To add descriptions and extended descriptions to a photo, place a file called desc.txt into your albums folder.

In that folder, each photo's description goes on a separate line, in the following format:
theimage.jpg:My Description:This is the Extended Description

If you don't want to add Extended Descriptions, just leave off the end, resulting in:
theimage.jpg:My Description

Picture descriptions are in the same format as the albums.txt description file, using a ":" to separate the data.

Dates

Dates for pictures are created automatically from the EXIF data of a file if it is present. If it's not present, the date will just be the last modification time.

This script does not use the built in PHP EXIF functions. It uses Exifer, or rather a custom revision of this script.

Templates

Templates are the glue of PhotoStack.

HTML Templates

You can easily change the look of your templates if you posses even the most meager HTML abilities. The default template is index.php and contains a little PHP mixed with PhotoStack template tags.

Syndication Templates

To generate an RSS feed for a particular album just append &format=rss to the album's URL.

You can edit which "format" you provide based on a switch in config.php. This will allow for $format=echo, for example.

For example: http://yourhost.com/photos/?album=newyork would become http://yourhost.com/photos/?album=newyork&format=rss. Or http://yourhost.com/photos/ would become http://yourhost.com/photos/?format=rss. Notice that for the first variable it uses ? instead of &.

Template Tags

General

<$PSSeparator$>

“›” is an example of what this tag might return.

<$PSNameMain$>

“Your Site” is an example of what this tag might return.

<$PSNameAuthor$>

“Your Name” is an example of what this tag might return.

<$PSNamePhotos$>

“Photographs” is an example of what this tag might return.

Navigation

<$PSNavigationMain$>

“http://photosite.com/” is an example of what this tag might return. It is the http_host $_SERVER variable.

<$PSNavigationBase$>

“http://photosite.com/photos/” is an example of what this tag might return. The photo installation URL.

<$PSNavigationListing$>

“http://photosite.com/photos/” is an example of what this tag might return. Synonymous with PSNavigationBase.

<$PSNavigationNext$>

“http://photosite.com/photos/?album=album1&img=3” is an example of what this tag might return. The URL to the next photo.

<$PSNavigationPrev$>

“http://photosite.com/photos/?album=album1&img=1” is an example of what this tag might return. The URL to the prev photo.

<$PSNavigationFirst$>

“http://photosite.com/photos/?album=album1&img=3” is an example of what this tag might return. The URL to the first photo.

<$PSNavigationLast$>

“http://photosite.com/photos/?album=album1&img=3” is an example of what this tag might return. The URL to the last photo.

<$PSNavigationPrevPageURL$>

“http://photosite.com/photos/?album=album1&page=2” is an example of what this tag might return. The URL to the prev page.

Pagination

<$PSNavigationNextPageURL$>

“http://photosite.com/photos/?album=album1&page=2” is an example of what this tag might return. The URL to the next page.

<$PSNavigationNextPage$>

“http://photosite.com/photos/?album=album1&page=2” is an example of what this tag might return. The number to the next page.

<$PSNavigationPrevPage$>

“http://photosite.com/photos/?album=album1&page=2” is an example of what this tag might return. The number to the prev page.

CurrentAlbum

<$PSCurrentAlbumTitle$>

“Fake Album” is an example of what this tag might return.

<$PSCurrentAlbumDescription$>

“A description for this album.” is an example of what this tag might return.

<$PSCurrentAlbumURL$>

“http://code.site/photos/?album=fake ” is an example of what this tag might return.

<$PSCurrentAlbumSyndicationURL$>

“http://code.site/photos/?album=fake&format=rss ” is an example of what this tag might return.

<$PSCurrentAlbumCount$>

“5 ” is an example of what this tag might return.

<$PSCurrentAlbumFolder$>

“fake ” is an example of what this tag might return.

<$PSCurrentAlbumDate$>

“12 Jul 2002” is an example of what this tag might return.

CurrentPhoto

<$PSCurrentPhotoPath$>

“http://code.site/photos/fake/DSCN0009.jpg” is an example of what this tag might return.

<$PSCurrentPhotoOriginalPath$>

“http://code.site/photos/fake/DSCN0009.jpg” is an example of what this tag might return. When using NormalSize thumbs, this provides the true path to your original.

<$PSCurrentPhotoThumbPath$>

“http://code.site/photos/storage/thumb-fake-DSCN0009.jpg.png” is an example of what this tag might return. It is the path web path to the thumbnail version of this photo.

<$PSCurrentPhotoHeight$>

“250 ” is an example of what this tag might return.

<$PSCurrentPhotoWidth$>

“250 ” is an example of what this tag might return.

<$PSCurrentPhotoDescription$>

“My Description” is an example of what this tag might return.

<$PSCurrentPhotoExtDescription$>

“My Extended Description” is an example of what this tag might return.

<$PSCurrentPhotoDate$>

“12 Jul 2002 ” is an example of what this tag might return.

<$PSCurrentPhotoURL$>

“http://code.site/photos/?album=fake&img=1 ” is an example of what this tag might return.

<$PSCurrentPhotoNumber$>

“1 ” is an example of what this tag might return.

PSAlbums

<PSAlbums> </PSAlbums>

These are container tags for the album listing tags below. This tag will loop through all the albums in the listing. If no album is being viewed they will return nothing.

num="" can be used as an attribute to designate how many albums you want displayed.

offset="" can be used to offset the num="" value.

<$PSAlbumTitle$>

“Fake” is an example of what this tag might return.

<$PSAlbumDescription$>

“A description for this album.” is an example of what this tag might return.

<$PSAlbumURL$>

“http://photos.site/photos/?album=album1” is an example of what this tag might return.

<$PSAlbumFolder$>

“fake” is an example of what this tag might return.

<$PSAlbumFirstImagePath$>

“http://leavesrustle.com/photos/storage/thumb-sanfrancisco2003-1CRW_0591.jpg.png” is an example of what this tag might return.

<$PSAlbumDate$>

“12 Jul 2002” is an example of what this tag might return.

<$PSAlbumSelected$>

“ selected="selected"” is an example of what this tag might return.

<$PSAlbumCount$>

“5” is an example of what this tag might return.

PSPhotos

<PSPhotos> </PSPhotos>

These are container tags for the photo listing tags below. This tag will loop through all the pictures in the current albums listing. If no album is being viewed they will return nothing.

num="" can be used as an attribute to designate how many photos you want displayed.

offset="" can be used to offset the num="" value.

<$PSPhotoNumber$>

“1” is an example of what this tag might return.

<$PSPhotoDate$>

“12 Jul 2002” is an example of what this tag might return.

<$PSPhotoDescription$>

“My Photo Description” is an example of what this tag might return.

<$PSPhotoExtDescription$>

“My Extended Description” is an example of what this tag might return.

<$PSPhotoURL$>

“http://code.site/photos/?album=fake&img=1” is an example of what this tag might return.

<$PSPhotoPath$>

“http://code.site/photos/fake/DSCN0009.jpg” is an example of what this tag might return. If using NormalSize thumbs, this will point to that file in the storage directory.

<$PSPhotoOriginalPath$>

“http://code.site/photos/fake/DSCN0009.jpg” is an example of what this tag might return. When using NormalSize thumbs, this provides the true path to your original.

<$PSPhotoThumbPath$>

“http://code.site/photos/storage/thumb-fake-DSCN0009.jpg.png” is an example of what this tag might return. It is the path web path to the thumbnail version of this photo.

<$PSPhotoHeight$>

“250” is an example of what this tag might return.

<$PSPhotoWidth$>

“250” is an example of what this tag might return.

<$PSPhotoFilename$>

“DSCN0009.jpg” is an example of what this tag might return.

<$PSPhotoThumbHeight$>

“50” is an example of what this tag might return.

<$PSPhotoThumbWidth$>

“50” is an example of what this tag might return.

Query Strings

<$PSAlbumQS$>

“?album=” is an example of what this tag might return.

<$PSPhotoQS$>

“&img=” is an example of what this tag might return.