Simple Picture Gallery Manager

Requirements SPGM set up procedure Gallery creation Integration into websites Layout configuration How can I make my own theme ?

A lightspeed manual is also available for those impatient people (mostly webmasters)

Requirements

A website that is able to run PHP scripts (PHP >= 4)... and a few pictures !

SPGM set up procedure

That is a pretty easy step. Just uncompress the SPGM distribution you have just downloaded and upload the spgm directory to your website, using your favorite FTP client.
Your gallery will then be reachable through the following URL:
http:// your-website-url /spgm-xxx/index.php

SPGM can be run as a standalone webpage (as it is out of the box) or as part of a template (CGI wrappers, CMS like PHPNuke...). If displaying your pictures is just what you're looking for, don't change anything, you've got the URL. You can edit the index.html file though, to change your gallery title, update the HTML headers and so on...
If you want to integrate a picture gallery into your already-existing website instead, refer to section Integration into websites, below.

Important:

• even though the FTP client should do it by default, make sure each file is readable and each directory is readable/executable by SPGM (644 and 755 permissions are often required)
• if the script keeps displaying the listing of the gal directory, whatever you click on, your PHP interpreter may not register the parameters passed in the URL as global variables. You need to edit the spgm.php then, to change the REGISTER_GLOBALS constant's value to false
• some servers used to require a .php3 extension... Renaming the php files is then mandatory

Gallery creation

Galleries are merely directories which contain pictures and/or sub-galleries (sub-directories). They are to be put in the gal directory and may be captioned by inserting among their content a gal-desc.txt text file containing whatever you want (even PHP code). They can also be previewed using icons, pre-defined thumbnails, or even random thumbnails. Refer to the "Gallery icon type" section in spgm.conf (gal/ directory) to see how to proceed.

Pictures are .jpg / .png / .gif files which must be associated to a thumbnail (use your favorite tool for thumbnail edition), and possibly to a caption.
The thumbnail filename is the picture filename prefixed by "_thb_" (e.g. pic01.jpg, _thb_pic01.jpg).
Captions for pictures from the same gallery are stored in a single "pic-desc.txt" file (1 picture caption per line, continue on the next line(s) with '>' as the first character if needed). This file can be used to set captions for both pictures and thumbnails, and looks like this :

  _thb_Tux.jpg | This is a caption for Tux's thumbnail.
  Tux.jpg | This is a caption for Tux's picture.<br /> 
  >Still descripting Tux.jpg, and now : 
  >here is <a href="http://spgm.sourceforge.net">a link</a>.

  ...

To hide a gallery and therefore make it available through direct URLs only, simply put an empty gal-hide.txt file in it.

Moreover, pictures and galleries can be sorted using several options (creation date, filenames, explicit sort using simple text files)...
Refer to spgm.conf for a complete description of those sort options.

Important:

• Do not put picture/thumbnail comments on the first line of the pic-desc.txt file if you use the UTF-8 encoding
• remember that the pictures must be readable by everybody and the galleries must be readable/executable by everybody
• File extensions for pictures/thumbnails are case-insensitive (i.e. .JPG / .PNG / .GIF are allowed, as well as .JpG and so on...)
• a gallery name (i.e. its directory name) must not include quotes/double quotes, nor spaces (use the undescore character instead, which will be rendered as a whitespace; ex: My_first_gallery)
  For gallery names using special characters (accentuated characters, apostrophes, symbols...), put the title on the first line of a "gal-title.txt" text file, located within the gallery.
• the gal directory is only intended to contain galleries. Therefore, don't put pictures directly in there, they won't be displayed anyway

Tips:

• William Denniss has designed Gallery Mage, a very useful tool (Java 1.4 required) that automates thumbnail generation and caption assessment...
  Visit the plug-ins/modules section to get it.
• I use the nconvert program (which comes along with the excellent XnView) and this batch script to generate thumnails under windows
• it is better to maintain the original picture's ratio when generating thumbnails and to make all of them the same fixed height

Integration into websites

If you want to integrate SPGM into you website, follow these instructions.

Let's say your want to call spgm from your main page, index.php and that SPGM is installed in a directory named spgm-xxx (those two reside at the same level). Considering that index.php handles the general layout of your website and puts many categories' content within it, as the following scheme:

URL param | param value | pointed page
--------------------------------------
     id   |   about     | information about the site
     id   |   bio       | your biography
     id   |   gallery   | your picture gallery

...then your URL looks like: http://yourname.free.fr/index.php?id=about

To make SPGM work from within your website, you'll have to edit spgm.php with a text editor and update the following constants (located at the beginning of the file):

• DIR_GAL must be spgm-xxx/gal (relative path to the gal directory from index.php)
• DIR_LANG must be spgm-xxx/lang (relative path to the lang directory from index.php)
• DIR_THEMES must be spgm-xxx/themes (relative path to the themes directory from index.php)

Now, just require("spgm-xxx/spgm.php") wherever you want in your code.

Layout configuration

Each gallery can be applied a specific layout configuration which is defined in a spgm.conf file.
A default configuration file is provided in the SPGM distribution (located in the gal directory). Every properties that have been set for a gallery are inherited in all sub-galleries, which means that the default configuration will be inherited in all your galleries.
Therefore, you can override any property by putting another configuration file in the desired gallery...

Here is the default configuration file which contains an exhaustive list of the properties you can set (check out the file itself for each property's role):

<?php

  $spgm_cfg['conf']['newStatusDuration'] = 40;
  $spgm_cfg['conf']['thumbnailsPerPage'] = 10;
  $spgm_cfg['conf']['thumbnailsPerRow'] = 5;
  $spgm_cfg['conf']['galleryListingCols'] = 1;
  $spgm_cfg['conf']['galleryCaptionPos'] = BOTTOM;
  $spgm_cfg['conf']['subGalleryLevel'] = 0;
  $spgm_cfg['conf']['galleryOrientation'] = ORIENTATION_LEFTRIGHT;
  $spgm_cfg['conf']['gallerySortType'] = SORTTYPE_CREATION_DATE;
  $spgm_cfg['conf']['gallerySortOptions'] = SORT_DESCENDING;
  $spgm_cfg['conf']['pictureSortType'] = SORTTYPE_CREATION_DATE;
  $spgm_cfg['conf']['pictureSortOptions'] = SORT_DESCENDING;
  $spgm_cfg['conf']['pictureInfoedThumbnails'] = true;
  $spgm_cfg['conf']['captionedThumbnails'] = true;
  $spgm_cfg['conf']['pictureCaptionedThumbnails'] = true;
  $spgm_cfg['conf']['filenameWithThumbnails'] = true;
  $spgm_cfg['conf']['filenameWithPictures'] = true;
  $spgm_cfg['conf']['enableSlideshow'] = true;
  $spgm_cfg['conf']['popupPictures'] = true;
  $spgm_cfg['conf']['popupWidth'] = 800;
  $spgm_cfg['conf']['popupHeight'] = 600;
  $spgm_cfg['conf']['popupFitPicture'] = true;
  $spgm_cfg['conf']['filters'] = 't';
  $spgm_cfg['conf']['zoomFactors'] = array(50, 100, 150);
  $spgm_cfg['conf']['galleryIconType'] = GALICON_RANDOM;
  $spgm_cfg['conf']['galleryIconHeight'] = 40;
  $spgm_cfg['conf']['galleryIconWidth'] = ORIGINAL_SIZE;
  $spgm_cfg['conf']['stickySpgm'] = true;
  $spgm_cfg['conf']['language'] = 'fr';
  $spgm_cfg['conf']['theme'] = 'bvk';

?>

SPGM does also make the use of flavors (a.k.a. themes) to make it match your whises. It comes with a flavor which is set by default. To change it, just go to the flavor page (http://spgm.sourceforge.net/?lg=us&id=themes) and download the one you're interested in. Unzip the package and put the resulting directory in the SPGM flavor directory (i.e. spgm-xxx/flavors).
Then :

• edit spgm-xxx/gal/spgm.conf and change $cfg['conf']['theme'] to the new flavor directory name (refer to spgm.conf for more details).
• edit spgm-xxx/index.php, locate the call to the flavor stylesheet (<link rel="Stylesheet" href="flavors/default/spgm_style.css" />) and change it according to the location of the new flavor's stylesheet

Important:

• don't forget to begin and end the spgm.conf file by the <?php and ?> markers

How can I make my own flavor ?

The SPGM distribution includes a flavors directory where you can put your flavors in.
A flavor is basically a directory containing the following resource files: the spgm.thm file (mandatory) which initializes variables to get SPGM to know which resources to use for galleries rendering, icons (optional), and a CSS stylesheet (optional).
The spgm.thm for the "default" flavor - which comes within the distribution - looks like this (check out the file itself for each property's role):

<?php

  $spgm_cfg['theme']['gallerySmallIcon']    = 'folder.jpg';
  $spgm_cfg['theme']['galleryBigIcon']      = 'folder.jpg';
  $spgm_cfg['theme']['newItemIcon']         = 'new.jpg';
  $spgm_cfg['theme']['previousPictureIcon'] = 'page_previous.jpg';
  $spgm_cfg['theme']['nextPictureIcon']     = 'page_next.jpg';
  $spgm_cfg['theme']['previousPageIcon']    = 'page_previous.jpg';
  $spgm_cfg['theme']['previousPageIconNot'] = 'page_previous_not.jpg';
  $spgm_cfg['theme']['nextPageIcon']        = 'page_next.jpg';
  $spgm_cfg['theme']['nextPageIconNot']     = 'page_next_not.jpg';
  $spgm_cfg['theme']['firstPageIcon']       = 'page_first.jpg';
  $spgm_cfg['theme']['firstPageIconNot']    = 'page_first_not.jpg';
  $spgm_cfg['theme']['lastPageIcon']        = 'page_last.jpg';
  $spgm_cfg['theme']['lastPageIconNot']     = 'page_last_not.jpg';

?>

Above is an exhaustive list of the variables you can set.

Note that you are not required to set all of these. Omitting variables identifying icons will only result in a textual representation of what they are supposed to display, whereas omitting the stylesheet only makes your gallery graphically deprived.

Important:

• don't forget to begin and end the spgm.thm file by the <?php and ?> markers
• the resource files the variables refer to must be located in your theme directory (i.e. the same directory where spgm.thm resides)
• the value assigned to the variables (which are filenames) and your theme's directory name must not contain any spaces nor quotes/double quotes