MicroAlbum v2.5

By Gaby Vanhegan, 20090712

A photo gallery script written in PHP, with an emphasis on simplicity, ease of installation and usage. It does not have a million features, nor does it have a thousand configurations, skins or plugins. It is intended to be small, simple and fast.

It works on the principle that you create one folder for each photo album, and you put the pictures you want into that folder. The script does the rest.

Features

Just One File™, minimal configuration and installation required
Just create a folder of images for each album, simplicity itself
Automatic building/rebuilding of thumbnails and previews
Sort, rotate your images
Many keyboard shortcuts
Customisable CSS, html header and footer
'Most popular images' smart-album
Rotate individual images, add captions
Sort albums by date, filename or custom order
Password protected administration functions
JSON data interface for developers

MicroAlbum offers some customisation features to let you change the look and feel of the album; you can add your own stylesheet, and customise the headers and footers.

The software is BSD licensed so you can do what you want with it. For information view the LICENSE.txt file.

Changes in V2.5a

Fixed a bug in the JSON album listing

Changes in V2.5

Added some JSON output options
Cleaned up a few misc bugs in the code
Added a "limit" option for JSON album listings

Changes in V2.4

Better config parsing
Better layout
Faster image resizing
Image dimensions now stored in data files
Optional json output format
Fixed some access keys
Numerous bug fixes and tweak

Changes in V2.0

Completely rewritten as a class. Much cleaner, more manageable code.

2008-04-01

Added better error messages for unwritable folders
Added lockfile to stop the serialisation process from squashing data
Image dimensions are now cached to the album data
Fixed multiple lock file issue
All images sizes are now read from the data cache
New option to live-build previews and thumbnails

2008-04-04

Much quicker preview skip on pre-generated images
Much lighter image build process now, doesn't touch config files
Completely re-written as a class instead of a bunch of functions
Automatic upgrade to newer data file format

Demo Site

MicroAlbum Demo

Custom CSS Demo

Custom Headers/Footers Demo

Download

Latest version: microalbum-2.5a.tgz (25497 bytes)

MD5 (microalbum-2.5a.tgz) = c9053b7b36afeddc1e600e1e604b2e8c

README.txt

LICENSE.txt

Old Versions

Latest version: microalbum-2.5.tgz (28362 bytes)

microalbum-2.0.tgz (24555 bytes)

MD5 (microalbum-2.0.tgz) = 06f2b201b8753a497588135abfb08d10

microalbum-2.4.tgz (27555 bytes)

MD5 (microalbum-2.4.tgz) = 653ca620816d98a537019d7ea9020bff

See it in Action

http://www.topatagonia.co.uk/

This site uses custom headers and footers to embed MicroAlbum into the site layout.

Quick Installation

Download and place the script in your web folder.
Open the script and set base_folder, gen_folder and admin_pass.
Create your albums, one per folder, inside base_folder.
Create gen_folder, and ensure that the web server can write to it.
All done!

For more detailed instructions see the full install guide.

Help, Support, Feature Requests, Bug Reports

For help and support you can contact Gaby here. Feature requests and bug reports can also be sent, but bear in mind that this is intended to be a simple and uncomplicated piece of software, so extra features may be kept to a minimum.

Requirements

There are very few requirements for MicroAlbum:

A webserver
PHP 4 or higher
The gd extension for PHP, to create thumbnails and previews of images
The exif extension for PHP, to read the EXIF image data from jpeg images

Most installations of PHP will have these options already, and later versions of PHP come with GD built-in. It does not require a database connection, or any external packages, other than those listed above.

Full Installation Guide

Download the micralbum.php script and save it somewhere in your webspace.
Open up the script in a text editor. At the top of the script you should be able to configure the script to suit. As a bare minimum, you should set:
- base_folder, the full path to the folder that contains your photo albums
- gen_folder, where generated previews and thumbnails go.
  IMPORTANT: THIS FOLDER MUST BE INSIDE base_folder!!!
- admin_pass, required for editing albums and pictures.
Make sure that gen_folder exists in base_folder, and that the user that the web server runs as can write to this folder. For example, if your web server runs as user www, and that user is in group www, then this is advisable:
```
# mkdir generated/
# chgrp www generated/
# chmod g+w generated/
```
This creates the folder 'generated', changes it's group to www, and then allows users in group www to write to it. This will allow the webserver to save your thumbnail, previews and album data in this folder.
That's it. Now go to the page in a web browser and check that it works.

Creating new albums

MicroAlbum expects each folder in base_folder to be a photo album, and for it to contain the photos you want in that album. To create a new album, just create a new folder in base_folder, the name of the folder being the name that you want the album to have.

For example, to create an album called 'My Holiday Album', just create a folder with the name 'My Holiday Album', and put your holiday snaps into it. MicroAlbum will do the rest for you.

Basic Configuration

The basic nuts and bolts that you have to set before you can use the software safely.

base_folder, the folder that contains the albums you wish to display. This folder must be readable by the script.
gen_folder, where the generated thumbnails and previews are stored, as well as the data files for the individual albums.
IMPORTANT: THIS FOLDER MUST BE INSIDE base_folder!!!
The script must be able to write to this folder or you will not be able to generate any thumbnails or previews.
admin_pass, the password required to edit album data, or use any of the admin functions.

JSON Output

You can access your albums through a new JSON interface which allows you to access your MicroAlbum data, thumbnails, previews and images however you like. If you have an application that can read and parse a JSON file then you are set.

Using the JSON interface

MicroAlbum can provide JSON data files for 2 areas, the list of albums that you have and any given album. To access the JSON data listing in either case, simply add the format=json to the URL. For example, if your MicroAlbum installation is accessed here:

http://my.com/album/index.php

To access the JSON version of this page you would go here:

http://my.com/album/index.php?format=json

This will give you a complete listing of all your albums, their last modification date and a randomly selected thumbnail from that information. Details are provided about each thumbnail too, from it's dimensions, path and URL.

If you were viewing a single album:

http://my.com/album/index.php?album=Holiday2009

To access the JSON version of this page you would go here:

http://my.com/album/index.php?album=Holiday2009&format=json

Tips

There are a number of access keys built in that enable you to navigate around albums using the keyboard. On a Mac, you press the control key and the access key (ctrl-n for example), and on Windows you press the alt key and the access key (alt-n).

When viewing an album in preview mode

Access Key	Action
a	Toggle between viewing all photos in the album or just one page at a time.
s	Start viewing the album as a slideshow.
n	Go to the next page of photos.
p	Go to the previous page of photos.
f	Skip to the first page of photos.
l	Skip to the last page of photos.
b	Go back to the list of albums.
e	Go to the edit screen for the album.

When viewing a picture

Access Key	Action
n	Go to the next picture in the album.
p	Skip to the previous picture in the album.
f	Skip to the first picture in the album.
l	Skip to the last picture in the album.
b	Go back to the whole album view.
s	Start or stop the slideshow.
v	View the current picture at full size (in a new window).

When editing an album

Access Key	Action
s	Go to the album sorting screen.
c	Go to the caption editing screen.
r	Go to the picture rotation screen.
b	Go back to viewing the album.

When editing the album list

Access Key	Action
b	Go back to the list of albums.

Customisation

There are a number of ways to customise the album to make it fit in with your site design, from changing the title of the album to adding custom CSS, headers and footers.

custom_css, the relative path to a CSS file, which will be included in the HTML headers of the script. Set to false for no custom css (default)
custom_header, a block of HTML that is inserted before any of the page HTML is output, but just before the HTML for the album begins, but after the opening <body> tag. Set to false for no header (default)
custom_footer, a block of HTML that is inserted after all the album HTML is output, but inside the closing </body> tag. Set to false for no footer (default)
page_title, the title shown at the top of the page, before the name of the album.
home_link, optional text for a link back to another site, displayed before the title. Set to false for no home link (default)
home_url, URL for the optional link back to another site.
thumb_per_row, number of thumbnail images to display per row. (default 4)
thumb_per_page, number of thumbnail images to display per page. (default 12)
slide_time, number of seconds to display each slide for in slideshow mode (default 4 seconds)
most_popular, number of images to display in the "most viewed" album (default 50)

Advanced Customisation

There are some advanced configuration options, but most of the time you won't want to set these as the defaults are sensible.

thumb_x, max width of thumbnail images in pixels (default 160)
thumb_y, max height of thumbnail images in pixels (default 120)
preview_x, max width of preview images in pixels (default 640)
preview_y, max height of preview images in pixels (default 480)
valid_types, an array of file extensions that are detected as images. All other files types are ignored by MicroAlbum.
valid_orders, what types of sorting are available for lists of albums and images. Don't change this unless you're ready to start hacking the code.