FF1+ IE5+ Opr7+

PHP Photo Album script v2.11

Author: Dynamic Drive

Description: This is a PHP enhanced Photo Album script that automates the retrieval of all images within a specific directory to show, with pagination links generated to cycle through each page. A PHP script (getalbumpics.php) placed in the desired image directory automatically gets the file names of all images within it and creates a JavaScript array for further processing by the script. As you upload or modify images within the directory, the script automatically adapts! Some attributes of this script are:

  • Uses an external PHP file to auto retrieve all images within a directory to show on the fly.
  • Customize the album's dimensions as desired, such as 3 by 2 images, 4 by 5 images etc.
  • Ability to sort the display order of the images by file or date, in ascending or descending order.
  • Ability to manually add a custom description beneath particular photos, or have the script automatically generate a generic description for every photo based on its position (ie: "Photo 1") or date (ie: "Aug 11, 2009 17:00:05").
  • Each "page" of images are only downloaded when they are viewed.
  • Each photo within the album when clicked on triggers the custom callback function onphotoclick(), which lets you specify the action to take, such as launch a larger version of the image using the built in lightbox viewer, or open a new window containing the enlarged image etc.

This script requires that your server is capable of running PHP (to retrieve the image file names of a specific directory), though the pages themselves that will display the photo album can be any regular HTML page.

Demo #1 (thumbnails when clicked on loads same image, but in native dimension):

Credits: Images for illustrative purposes only, obtained from Jaguar.com

Demo #2 (thumbnails when clicked on loads a different, larger version of the image):

Directions Developer's View

Step 1: Insert the below code inside the <HEAD> section of the page:

Select All

The above code references 4 external files which you should download below (right click, and select "Save As"):

The file "getalbumpics.php" should be moved into the directory containing the images you wish to display as an album, while the later two files should simply reside in the same directory where the page showing the album is located in. More info on this later.

Step 2: Insert the following sample invocation code to the BODY Of your page where you wish the album to appear:

Select All


The first thing you should do after basic installation above is to ensure "getalbumpics.php" is moved into the directory containing your album images. Then edit the top of the code of Step 1 to correctly reference this PHP file on your server (as a URL):

<script type="text/javascript" src="http://www.mysite.com/myimages/getalbumpics.php?id=myvacation"></script>

The above means all images inside the directory "/myimages" will be used as part of this album. Now, notice the "id=myvacation" parameter at the very end- this parameter is required, and is used to uniquely identify this album elsewhere in the script. "myvacation" can be any arbitrary but unique name (alpha numeric keys only).

Moving on, you should now make sure the invocation code (code of Step 2) inside your HTML page has at least one setting set to a specific value:

new phpimagealbum({
 albumvar: myvacation, //ID of photo album to display (based on getpics.php?id=xxx)
 dimensions: [3,2],
 sortby: ["file", "asc"], //["file" or "date", "asc" or "desc"]
 autodesc: "Photo %i", //Auto add a description beneath each picture? (use keyword %i for image position, %d for image date)
 showsourceorder: true, //Show source order of each picture? (helpful during set up stage)
 onphotoclick:function(thumbref, thumbindex, thumbfilename){
  thumbnailviewer.loadimage(thumbfilename, "fit2screen")

The value of "albumvar" should match the ID of the album you wish to show, specifically, the ID of a particular "getalbumpics.php" on the server. Such a set up enables you to have multiple Photo albums on the same page, some displaying the same album set while others different, for example.

As you can see, the invocation code supports additional options. Here's a description of each:

function phpimagealbum() options
Option Description


The ID of the corresponding "getalbumpics.php" on the page (without any quotes!) in which this album should use to draw its images using. All images that's in the directory "getalbumpics.php" is in will be shown as part of the album.
dimensions The dimensions of this Photo Album in the form [columns, rows], such as [5,3].


How images in this album should be sorted when shown. Possible values are ["file", "asc"], ["file", "desc"], ["date", "asc"], and ["date", "desc"].
autodesc Lets you add an auto generated description to every picture in the album. Specify the desired text intermixed with the keywords "%i" or "%d" to show the picture's current order (relative to its peers) or date (date of filename), respectively. Here are some examples:

autodesc="Picture %i"


autodesc="Pic: %i, Date: %d"

Note that even with "autodesc" defined, you can still add a manual, custom description to specific pictures within your album. The later will overwrite the former for those pictures.

To have no auto generated description, just set this option to a blank string ("").

showsourceorder A Boolean option that when set to true triggers the script to display in bold red the source order of each image. The source order is the actual order of the image file names as they appear in the containing directory. The very first image within the directory has a source order of 0 and so on.

This option is handy when setting up manual descriptions for images, in which the image should be referenced by its actual source order. It lets you quickly find the correct index number to use to refer to a specific image:

Screenshot of an album with showsourceorder turned on:

onphotoclick:function(thumbref, thumbindex, thumbfilename){} Custom event handler that fires whenever an image (thumbnail) within the album is clicked on. It is the primary method of assigning behaviour to the album images, such as load a larger version of the image in a new window or lightbox when they are clicked on.

The onphotoclick event handler is automatically fed 3 parameters:

  • thumbref: A DOM reference to the photo clicked on. thumbref.src then would return the image's full URL.
  • thumbindex: The source order of the photo clicked on (see showsourceorder option for more info).
  • thumbfilename: The file name of the photo clicked on, stripped of the domain and directory path info (ie: "ontheboat.jpg"). Contrast that with probing the DOM reference thumbref.src, which would return "http://www.mysite.com/myimages/ontheboat.jpg".

For more info on using the onphotoclick event, see "Utilizing the onphotoclick event handler and built in Lightbox".

Customizing the style of the photo album

The style of your Photo Album, including the pagination links, is defined inside "ddphpalbum.css". This includes the very important dimensions applied to each thumbnail image when they are shown:

.photodiv img{ /*CSS for each image tag*/
border: 0;
width: 200px;
height: 106px;

cursor: hand;
cursor: pointer;

You should modify the properties in red above to the desired dimensions, or remove them if you want the thumbnails to each be shown in their native dimensions.

Adding a manual description to certain pictures

For certain images in your album, you may wish to get a little wild and add a manual description to them. This can be done by populating the array albumid.desc[imagesourceorder] immediately following the corresponding "getalbumpics.php" reference in the HEAD section of your page:

<script type="text/javascript" src="http://www.mysite.com/myimages/getalbumpics.php?id=myvacation"></script>

<script type="text/javascript">

//Optional, manual description for particular pictures inside album
//Syntax: albumid.desc[index]="Picture description here"
//eg: myvacation.desc[2]="This is description for the 3rd picture in the album"
//eg: myvacation.desc[6]="This is description for the 7th picture in the album"


The code in bold above is optional, and is what you'd throw in to add manual description(s) to some of your photos within the album above it. The expected syntax is: albumid.desc[imagesourceorder], where "albumid" is the ID of the "getalbumpics.php" instance that holds the image in question, and "imagesourceorder" is the source order of the image relative to its peers. The source order of an image can easily determined by turning on the "showsourceorder" option in your initialization code.

Utilizing the onphotoclick event handler and built in Lightbox

The onphotoclick event handler is your primary method of assigning behaviour to your album images, such as load a larger version of the image in a new window or lightbox when they are clicked on. See the supplimentary page for more info on using this event handler.

Table Of Contents

This script consists of an index page plus several supplementary pages:

Wordpress Users: Step by Step instructions to add ANY Dynamic Drive script to an entire Wordpress theme or individual Post