last update March 2009
“When I first needed a picture gallery, my idea was not to develop my own software but to make use of an existing product. I got somewhat disappointed in my research as on the one hand I found probably good products but very heavy (hundreds of files) with a complex installation and update procedure, and on the other hand, I found simplistic ones dificult to integrate in an existing web site. So, I ended developing my own...”
To review the salient features of the application, see: salient features of PJGallery.
This software is free for personal use (although a donation will be much appreciated if you like it) under the following creative commons license 2.0 terms which allows you to copy and distribute this work for commercial or non-commercial purpose with mention of the copyright pjgallery provided no derivative work is distributed.
This program is distributed in the hope that it will be useful, but without any warranty.
To install the application once the package has been downloaded and unzipped, make a directory /pjgallery under the root of the server and copy the whole set of files under this directory so that the pathname to view an album is /pjgallery/viewAlbum.php. You can test that you have access to the sample album by entering the following address in your browser:
Once this works as it should be, you can upload images to the default album:
Notice that if Javascript is disabled on your browser, you can view the pictures but the slide show option won't be available.
The application doesn't necessarily have to be installed in /pjgallery under the root. You can install it anywhere you wish under the public part of your web server. Now, you must update the constant INSTALLDIR in the three files viewAlbum.php, viewPicture.php, and viewDiaporama.php. In the following text replace then /pjgallery by your chosen path.
You can create as many albums as you want. The default album resides in /pjgallery/albums/default ; you can create your albums in /pjgallery/albums but also elsewhere in your public tree if you wish provided they are descendants of root.
Choose a name for the directory of your albums and create two subdirectories images and thumbnails (these names are fixed). The thumbnails directory is not necessary if you don't intend to create thumbnails.
If you intend to create thumbnails, upload them in the thumbnails directory. If you do not know how to generate thumbnails, pjgallery provides a utility makethumbnails.php for that purpose. This program will have to write on your web server and for security reasons it would be wise to attach authentification to the utilities directory (see .htaccess if you are running the Apache server). This program uses the functions of the GD library of php. This program is pretty smart, it handles both the horizontal and vertical format and does the cropping if necessary. You should decide for a thumbnail size (for instance 133pxX100px), the program will then resize the vertical images to 100pxX133px.
Next upload your images to the images directory of your album.
if you wish to attach a caption and/or impose a particular order on the display of your pictures, you should configure a description text file say listImagesCaptions.txt (the name is parameterizable). On each line of this file, you should first key in the base name of the picture, followed by the separator character semi-colon(;) followed by an optional description (see the sample album for an example). A quick way to generate a text file containing a list of the picture names of a directory is to use the command prompt:
You will need edit this in your favourite text editor to add semi colons and descriptions.
(As an exception, the filename of the picture could be a non relative name that is a root name, but this won't work with thumbnails [a text "thumbnail not available" will be displayed instead]). This would allow for the casual possibility of importing in an album a picture belonging to a directory diffferent from the (main) album directory).
Next, you have to choose a theme for your album, pjgallery is shipped with the default and sample themes. Let's assume, at this stage, that we use the default theme. (You may have to modify the thumbnail style dimension properties of the file /pjgallery/themes/default/pjgallery.css for an optimal display.)
Now we are ready to create the album description file: albumDescription.php (the name is parameterizable). This file should reside immediately under your album directory. The various options are defined in /pjgallery/albums/default/albumDescription.inc.php and can be overriden in your explicit album description file. The default options are supposed to be common to all albums, modify the initial settings so that they reflect your common use (for instance the choice of your language). The default options are always loaded by PJGallery but those options that are specific to your album (the title for instance) can be overriden in the specific album description file. See album sample for an example. (Don't forget that the album description file is a Php File and therefore its contents have be surrounded with Php brackets!) If you do not need or do not want to override the default settings, you still have to create an album description file which then would be empty.
Right, we are ready. Entering the following address in your browser:
should bring you to your album. Notice that PathToTheDescriptionFileOfYourAlbum can be either a root-based path or a relative path with respect to viewAlbum.php although root-based path might speed up somewhat.
How to update an album derives naturally from what has been explained above. If you have to add a picture to an album, you'll upload the picture in the appropriate images directory as well as the corresponding thumbnail if you've chosen thumbnails for this album. (If you use the program for making thumbnails delivered with the application, this program will generate the missing thumbnail). If you failed to upload the thumbnail, a "no-thumbnail available message text" will appear at the thumbnail place in the thumbnail page. If you have a description file (listImagesCaptions.txt), you must also update it otherwise the new image will not be reflected at all in the gallery.
The integration of the gallery with a standard page of your site has been made easy. You can edit viewAlbum.php and add the commands needed in the <head> as well as in the <body>. If you have Javascript code, the instructions are detailed in the comment section of viewAlbum.php. Your own commands should not interfere with pjgallery. If you have relative links in your web page, move viewAlbum.php into the adequate directory or alternatively use the <base> tag so that your relative links work. But if you move viewAlbum.php, you have to move viewDiaporama.php and viewPicture.php as well. PjGallery uses root-based links and therefore won't interfere with your code.
PJGallery handles a single album, if you wish to build several albums, proceed as explained above for each of them. In the menu of your web page, you can then add the collection of links pointing to your existent albums (for instance <a href="http://yourDomain/pjgallery/viewAlbum.php?alb=PathToTheDescriptionFileOfYourAlbum-j">album-j</a>)
You can add new themes under /pjgallery/themes if you wish. Create a subdirectory whose name is the new theme. You should provide in this subdirectory the same files that are encountered under the default theme subdirectory. If you want to change the CSS style properties, you can possibly import in your pjgallery.css the default pjgallery.css and redefine the selective properties you want to change (see sample theme for an example). Notice that the themes are supposed to style PJGallery items. When integrating PJGallery in your own web site, it is better practice to keep your own style files separate and integrate them in the <head> of viewAlbum.php. PJGallery style rules are prefixed by #PJGallery and should therefore not interfere with your own styles.
As we said previously, you define the language in the description file of your album. PJGallery comes shipped with the following languages (en, fr, es, eo). This is handy, for instance in a bilingual site, where the same album can be displayed in different languages by just changing the language in their respective description files. You can easily add other languages of your own, you may use the UTF-8 encoding for that purpose.