Directory /scripts/photo_gallery

   * Simple Picture Gallery Manager *



Feel free to email me at <spajot(at)> for any help, 
suggestion, bug report... And don't forget to rate SPGM from the website ;)

Enjoy !



1 Introduction
2 Requirements
3 SPGM set up procedure
4 Gallerie creation
5 Layout configuration
6 How can I make my own theme ?


1 - Introduction

  SPGM is a PHP script that displays picture galleries on the web. It is 
intended to provide a very simple way to set up online photo albums: creating 
directories, filling them with pictures and uploading... That is what it's 
all about ! 

It is massively configurable though, and you can tune the layout just as much
as you want to match your exact website's design. Several cool features are 
also included, while keeping in mind that it aims to be as lightweight and 
simple as possible. Don't expect automatic thumbnail generation, advanced 
search functions, nor per-gallery full statistics then. 

SPGM generates HTML 4.01 compliant code and makes extensive use of CSS 
stylesheets to render galleries. It only requires PHP version 3 or higher 
and does not rely on image manipulation libraries (like GD), or any database
system whatsoever. 

A few features: 

* caption for each gallery/picture 
* infinite sub-galleries hierarchies 
* per gallery complete configuration (inheritance supported) 
* new pictures highlighting (filtering available) 
* themes available for use 

SPGM is free for use (distributed under the GPL license), very easy to set up
and manage... It makes you just a few clicks away from getting your photo 
albums on the web. 


2 - Requirements

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


3 - 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/spgm.php 


* Make sure each file is readable to everybody (644 mode) and each directory
  is readable/executable to everybody (755 mode)
* if the script keeps displaying the listing of the gal directory, whatever 
  you try to do, 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  
* you can rename both the directory name or the script name at your 
  convenience as long as the SPGM mention is visible on each of your gallery 
* some servers used to require a .php3 extension... Renaming the script is 
  then mandatory 


4 - 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 its content a gallery.msg text file containing 
whatever you want (even PHP code). 

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's filename is the picture's filename prefixed by "_thb_", 
whereas the caption''s filename is the picture's filename suffixed by ".cmt" 
(e.g. pic01.jpg, _thb_pic01.jpg, pic01.jpg.cmt).


* remember that the pictures must be readable by everybody and the galleries
  must be readable/executable by everybody 
* a gallery name (i.e. its directory name) must not include quotes/double 
  quotes, nor whitespaces (use the undescore character instead, which will 
  be rendered as a whitespace; ex: My_first_gallery) 
* don't put pictures directly in the gal directory, they won't be displayed 

* William Denniss wrote a very useful tool (Java JRE 1.4 required) that 
  automates thumbnail generation and caption assessment...
* I use the nconvert program (which comes along with the excellent XnView
  []) and a batch script ("tools" directory) 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 
* Most of digital cameras generate filenames corresponding to the timestamp 
  the picture was taken at. Using PHP, you can display this timestamp in a 
  picture's caption by parsing the $picture_name variable that is accessible 
  from there...
  For instance, here is a 2002_0206_132922AA.jpg.cmt file associated to 

    $p = $picture_name;
    echo "<b>($p[7]$p[8]-$p[5]$p[6]-$p[0]$p[1]$p[2]$p[3] \ 
      $p[10]$p[11]:$p[12]$p[13])</b> ";
  blah blah blah...

  ... which renders:
  (02-06-2002 13:29) blah blah blah... 


5 - 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 property set for a gallery is inherited in all 
its sub-galleries, which means that the default configuration will be 
inherited in all your galleries.
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 


  $new_status_duration = 10;
  $thumbnails_per_page = 10;
  $thumbnails_per_row = 5;
  $subgal_display_level = INFINITE;
  $sort_gallery_by_name = true;
  $display_captions_with_thumbnails = true;
  $zoom_factors = array(50, 100, 150);
  $lang = "en";
  $theme = "default";
  $file_header = "header.html";
  $file_footer = "footer.html";
  $html_header_title = "My picture gallery";
  $html_header_meta_author = "Myself";
  $html_header_meta_description = "This is my picture gallery";
  $html_header_favicon = "";



6 - How can I make my own theme ?

The SPGM distribution includes a "themes" directory where you can put your 
themes in. 
A theme 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, image files (optional), 
and a stylesheet (optional). 
The spgm.thm for the "default" theme - which comes within the distribution - 
looks like this (check out the file itself for each property's role): 


$file_icon_gal = "gal.png";
$file_icon_pic_new = "new.png";
$file_icon_pic_prev = "previous_pic.png";
$file_icon_pic_next = "next_pic.png";
$file_icon_navi_prev = "previous_page.png";
$file_icon_navi_next = "next_page.png";
$html_header_stylesheet = "spgm_style.css";


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. 


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