SPGM - Simple Picture Gallery Manager ====================================== Install.txt v1.3.4 - 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/index.php SPGM can be run as a standalone application (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.php 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, change the URL_EXTRA_PARAMS constant in spgm.php according to your needs (more explanations in the file itself and at http://sourceforge.net/tracker/index.php?func=detail&aid=768824&group_id=54021&atid=472416). Then, just require("spgm.php") wherever you want in your code. 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 * some servers used to require a .php3 extension... Renaming the php files 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 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. 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. ... 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: * 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). For gallery names using special characters (accentuated characters, symbols...), put the title on the first line of a "gal-title.txt" text file, located within the gallery. * remember that the pictures must be readable by everybody and the galleries must be readable/executable by everybody * 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://tanksoftware.com/gallmage/] * 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 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): 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/style.css and change the first line to make point to the stylesheet provided with the new flavor 5 - 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, image files (optional), and a 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): 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 markers * the resource files the variables refer to must be located in your flavor directory (i.e. the same directory where spgm.conf is located in) * the value assigned to the variables (which are filenames) and your flavor's directory name must not contain any whitespaces nor quotes/double quotes