SPGM - Simple Picture Gallery Manager
======================================
Install.txt                       v1.3



        - INSTALLATION GUIDE -



 CONTENTS
=========

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




1 - Requirements
================

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


2 - 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 

Important:

* 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 
  pages 
* some servers used to require a .php3 extension... Renaming the script is 
  then mandatory 


3 - 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).

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:

* 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 
  anyway 


Tips:
* William Denniss wrote a very useful tool (Java JRE 1.4 required) that 
  automates thumbnail generation and caption assessment...
  [http://www.omegadelta.net/tanksoftware/programs.php?&program=GalleryMage]
* I use the nconvert program (which comes along with the excellent XnView
  [www.xnview.com]) 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 
  2002_0206_132922AA.jpg:

  <?php
    $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... 


4 - 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 
role): 

<?php

  $new_status_duration = 30;
  $thumbnails_per_page = 10;
  $thumbnails_per_row = 5;
  $gallery_listing_column_number = 1;
  $subgal_display_level = INFINITE;
  $gallery_sort_type = SORTTYPE_CREATION_DATE;
  $gallery_sort_options = SORT_DESCENDING;
  $picture_sort_type = SORTTYPE_CREATION_DATE;
  $picture_sort_options = SORT_DESCENDING;
  $display_thumbnails_with_pic = false;
  $display_picinfo_with_thumbnails = false;
  $display_captions_with_thumbnails = true;
  $zoom_factors = array(50, 100, 150);
  $gallery_icon = GALICON_RANDOM;
  $gallery_icon_height = 40;
  $gallery_icon_width = ORIGINAL_SIZE;
  $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 = "";

?>


5 - 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): 

<?php

$file_icon_gal_small = "gal.png";
$file_icon_gal_big = "gal_big.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. 


Important:

* don't forget to begin and end the spgm.conf 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.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