To display the gallery you need one page only, this page will change it's self to show thumbnails, individual pictures etc. 1. Directories ============== To set up the data for the gallery you need a set of directories containing the pictures, usually in a directory under your main HTML directory e.g. "Picture Galleries" in the example below which defines n galleries: public_html | +-images | +-php | | | +-gsGallery.class.php | | | +-gsUtilities.php | +-Picture Galleries | | | +-gallery 1 | | | +-gallery 2 : : | +-gallery n | : +-etc You can call the directories what you like and can have as many galleries as you like. Any galleries are listed in alphabetical order. 2. Pictures =========== The pictures should be uploaded to the appropriate directory (gallery1, gallery 2 etc.). The formats handled are gif, jpg, jpeg and png and the pictures can have what ever names they like, however they are displayed in alphabetical order. 3. Thumbnails ============= 3.1 Pictures ------------ Thumbnails for pictures should be loaded to the same directory as the picture they represent and are distinguished with a naming convention. If the picture is called name.ext the thumbnail should be called name__t.ext If a thumbnail is not found when trying to display a gallery an alternative is displayed instead. By default this is simply the text "Thumbnail Missing" but you may change this to be a missing file image or any other piece of HTML you like (see "Options" below). NOTE - it is possible to get the gallery class to automatically create any missing thumbnail files for you by using the setCreateThumbnails configuration call (see "Options" below). 3.2 Galleries ------------- It is also possible to define a thumbnail to represent a whole gallery (if you are using the table navigation method see "Options" below). To do this place an image file in the top level gallery directory and name it with the name of the directory including the thumbnail suffix. i.e. if the directory "All Galleries" contains a subdirectory called "Boat Trip" a thumbnail to represent that gallery should be called "Boat Trip__t.ext" (where ext is the extension appropriate for the image type). These are not required if you are using a list style display (see "Options" below). If a thumbnail cannot be found for the directory the first available thumbnail in the gallery directory it's self will be used instead, if no thumbnails are found there either it outputs the missing thumbnail alternative (as described in 3.1 above). 4. Titles and Descriptions ========================== Titles and descriptions may *optionally* be shown for the whole set of galleries, individual galleries and each picture. The titles and descriptions are read from appropriately named text files placed in the directory structure. The text files may contain just text or, if you wish, HTML code. NOTE it is now possible to view and edit the titles and descriptions via a "administration" web page (see "Administration" below). 4.1 Set of all galleries ------------------------ The title for the gallery should go in a file called title.txt in the top level gallery directory. e.g. "All Galleries/title.txt" If a title is not provided the default is the name of the top level directory. The description for the gallery should go in a file called description.txt in the top level gallery directory. e.g. "All Galleries/description.txt" If a description is not provided the default is the text string "No description has been defined for the gallery". 4.2 Individual Galleries ------------------------ The title for an individual gallery should go in a file called title.txt in the directory that contains the gallery's pictures e.g. "All Galleries/gallery 2/title.txt" If a title is not provided the default is the name of gallery's directory. The description for an individual gallery should go in a file called description.txt in the directory that contains the gallery's pictures e.g. "All Galleries/Boat Trip/description.txt" If a description is not provided the default is the text string "No description has been defined for this sub-gallery". 4.3 Pictures ------------ The title for a picture file should in a file in the same location as the picture file it's self and is named similar to thumbnail files except with a suffix of __x. i.e. the title for image0012.png should go in file image0012__x.png. If a title is not provided the default is the pictures file name with the extension removed. The description for a picture file should in a file in the same location as the picture file it's self and is named similar to thumbnail files except with a suffix of __d. i.e. the description for party.jpg should go in file party_d.jpg. If a description is not provided the default a null string, i.e. nothing will be output. 5. The Web Page =============== The gallery is intended to fit easily into any web page design or template and uses a few simple function calls display the parts of the gallery which you can place anywhere on the page. Two of simple example files (example1.php and example2.php) are provided. To set up a page to use the gallery you need to 'include' the PHP script. To do this copy the provided php gallery to your web site (usually under the HTML directory) and include the following code right at the top of your web page: The require_once line tests the page where to find the gallery class - in the example shown it looks for the class in a sub directory called php below the current directory (represented by the "dot"). If you move the php files you will need to edit this line. You need to change "./Picture Galleries/" to match the path to whatever you have called your top level picture directory and you should include the trailing / on the directory path. Then simply insert these snippets of code at the appropriate pages in your page: title(); ?> Shows the appropriate title for what is being displayed. You can control the dispaly of the main, gallery or picture titles separatly (see "Options" below). description(); ?> Shows the appropriate description for what is being displayed. You can control the dispaly of the main, gallery or picture descriptions separatly (see "Options" below). display(); ?> Shows either the gallery thumbnails as a table or the individual image backLink(); ?> Provides a link back: from pictures to galleries and from galleries to the top level (This is only really required if you as using table mode see "Options" below.) nextLink(); ?> Provides a link to the next picture in a gallery (Only visible when a picture is displayed.) prevLink(); ?> Provides a link to the previous picture in a gallery (Only visible when a picture is displayed.) galleryList(); ?> Provides a clickable list of all available galleries that you can use to navigate you are using list mode - see "Options" below.) navigation(); ?> Provides a full set of links to move between galleries and pictures. Combines nextLink, prevLink and galleryList as described above (Works best if you are using list mode - see "Options" below.) 6. Options ========== Certain of the default behaviours of the gallery can be changed by adding extra lines to the setup code at the top of the page, i.e. after the line $gallery = new gsGallery("./Picture Galleries/"); Each is listed below with a brief explanation $gallery->setGalleryListType(type); This changes the style of the gallery, allowed values for type are "table" and "list" If you choose table mode when the page is first displayed it shows thumbnails for all the available galleries and clicking on a gallery thumbnail will then display thumbnails of the pictures in that gallery. If you choose list mode you must include the navigation(); ?> code on your page which will display a list of the available galleries which can be clicks to display the appropriate thumbnail set. On initial display the first (alphabetically) gallery will be displayed. Default = "table" $gallery->setColumns(n); Change the number of columns used to display the thumbnails, n may be any number. Default = 3 $gallery->setColumnSpacing(n); Change the column spacing in the table of columns used to display the thumbnails, n may be any number. Works exactly as in the tag it's self.. Default = 0 $gallery->setDefaultThumb(string); Sets the HTML displayed when a thumbnail is missing e.g. string could be $gallery->setDefaultThumb(""); Default = "Thumbnail Missing" $gallery->setBackLink(string); Sets the HTML displayed as the "back" link, this could be text or an image or anything you wish. Default = "Back" $gallery->setNextLink(string); Sets the HTML displayed as the "next" link, this could be text or an image or anything you wish. Default = "Next" $gallery->setPreviousLink(string); Sets the HTML displayed as the "previous" link, this could be text or an image or anything you wish. Default = "Previous" $gallery->setNavWrapper(string); Allows you to define how gallery numbers are displayed in the navigation list. You may enter any string containing %number% and that string will be displayed with %number% replaced by the actual gallery number. So for example $gallery->setNavWrapper("-[%number%]-"); would display the links as -[1]-, -[2]-, -[3]- etc Default = "Gallery %number%" $gallery->setMainDescriptionDisplay(flag); $gallery->setMainTitleDisplay(flag); $gallery->setGalleryDescriptionDisplay(flag); $gallery->setGalleryTitleDisplay(flag); $gallery->setPictureDescriptionDisplay(flag); $gallery->setPictureTitleDisplay(flag); These turn off or the display of title and descriptions for the main display, individual galleries or pictures. The values for flag are true or false, true setting display on and false setting it off. By using these lines and the description and title sections described above it is possible to display titles and descriptions for what ever combination of objects you wish. Default = true $gallery->setLabelMainTable(flag) $gallery->setLabelGalleryTable(flag) These turn off or on the display of gallery or picture titles underneath the thumbnail pictures in the main or gallery thumbnail tables. Default = false $gallery->setCreateThumbnails(flag, x, y) Determines if any missing thumbnails should be created automatically (for pictures only - it will not create thumbnails for galleries). If the flag is set to true thumbnails will be created with a maximum wiidth of x pixels and a maximum height of y pixels. NOTE - for this to work you must set the permissions on the gallery subdirectories so that they are writable. Defaults = false, 175, 175 $gallery->setMogrifyPath(path) Controls what software is used to create the thumbnail images, if this is not set the gallery class uses the built in GD libraries. However if your server has mogrify (part of the imagemagick set of utilities) installed and accessible you may use that instead by specifing the path to the mogrify exectable (e.g. $gallery->setMogrifyPath("/usr/bin/mogrify");) Deafault N/A 6. CSS Stylesheets ================== All the items output by the gallery have CSS classes associated with them which can use to change the appearance of your gallery. The available classes are listed in the file gallery.css. 7. Administration ================= An additional administration class is provided which allows you toi view, review and edit the titles and descriptions for your galleries and pictures. An example of the use of this class is provided in the file galleryadmin.php. As it is not intended that this administration page should be viewed by the public is is suggested that you either delete it from your web site when you have used it or place it in a password protected sub-directory so that only you can access it. As with the standard pages there is some configuration required. The file galleryadmin.php contains the lines handleForm(); ?> The require_once line tests the page where to find the gallery admin class - in the example shown it looks for the class in a sub directory called php below the current directory (represented by the "dot"). If you move the php files or put the admin web page in a different directory you will need to edit this line. You need to change "./Picture Galleries/" to match the path to whatever you have called your top level picture directory and you should include the trailing / on the directory path. The handleForm line is required to handle any changes submitted from the edit forms. That is all thye configuration that is required. When editing the titles and descriptions you may include HTML code, for example bold text. If you wish to make this easier you may use the FCK online wysiwyg editor . Youi must download and install the editor separatly from these files and then include the configuration line $gallery->setFCKpath("./php/FCKeditor/"); where "./php/FCKeditor/" (including the trailing slash) is the path to the directory where the FCK files can be found.