BuildGallery

BuildGallery automatically generates xml files and creates thumbnails for SimpleViewer.

Creating a SimpleViewer gallery with BuildGallery

Follow the steps below to create a SimpleViewer gallery on your website.

  1. Download SimpleViewer files

    Download the SimpleViewer zip file from the Airtight Interactive web site and unzip the files to a new folder on your local computer. This will be your gallery folder, let’s say it’s called mygallery.

    The zip contains a few sample images in the images folder and a sample gallery.xml file. You can delete these, since you will be uploading your own images and BuildGallery will create a new gallery.xml file for you. BuildGallery will use the existing thumbs folder if it is present or create a new one if it is missing. Do not delete any other files from the gallery folder.

  2. Download BuildGallery

    Download the BuildGallery zip file from Airtight Interactive and unzip buildgallery.php into the same gallery folder that you created in the previous step.

  3. Upload the new gallery to your server

    Using an ftp program, upload the gallery folder to your chosen location on your web server, for instance www.mysite.com/mygallery/

  4. Add image files

    Upload your image files to the images folder inside your gallery on the server. Images should be JPGs and saved as non-progressive.

  5. Set file permissions

    Set file permissions on your gallery folder, the gallery.xml file, thumbs folder and any files inside the thumbs folder to read/write/execute for all levels (777). You can usually do this with your FTP program or there may be a utility program provided by your web host. This step may not be necessary on all servers. You can miss it out and run BuildGallery to see if you get any problems. BuildGallery will produce error messages if it cannot read or write to your files.

    A simpler alternative for new galleries only is to delete the gallery.xml file and the thumbs folder. BuildGallery will create new ones.

  6. Run the BuildGallery Script

    In a web browser, navigate to the URL of your build script – for example http://www.mysite.com/mygallery/buildgallery.php

  7. Set gallery options

    The BuildGallery data entry form shows default options for the appearance of your gallery. You can accept the defaults or change them in the on-screen form. An explanation of all the options is given below in the Reference section or you can just experiment.

    The Update button saves your changes to the gallery.xml file and creates new thumbnails. The Reset button resets any changes since you loaded the web page or pressed the Update button. The Default settings link at the top of the page resets the options to the internal defaults set inside BuildGallery. The Default settings link simply enters the defaults into the data entry form – they will not be saved to the gallery.xml file until you press Update. See the section on Setting Defaults below for more information.

  8. Create the gallery

    Press the Update button at the bottom of the form to create thumbnails and update your gallery xml file.

  9. View your gallery

    Follow the View gallery link at the top of the BuildGallery screen to open your gallery in a new window or tab (depending on your browser settings). In some browsers, you may need to click on the new window or tab to bring it to the front so you can see your gallery.

  10. Editing Captions (optional)

    If you require customised image captions, you can download and edit gallery.xml from your gallery web folder. gallery.xml is a simple text file that can be edited in any text editing software (e.g. NotePad, TextEdit). Insert image captions in the caption tag for each image. Re-upload gallery.xml back to your gallery web folder.

    Captions can include a limited set of HTML formatting including hyperlinks, line breaks, font tags, bold, underline and italics. If you are using any of these tags, you will need to wrap them in CDATA tags like this:
    <caption><![CDATA[<b>my caption</b>]]></caption>

    An easy way to do this is to let BuildGallery create default captions based on the file name and then edit them. BuildGallery will add the CDATA tags for you.

  11. Updating the Gallery

    To update your gallery with new images, upload the new images to your images folder and delete any images that are no longer required, then re-run the build script. BuildGallery will read the gallery.xml file and show the settings in its data entry form. When you press the Update button, thumbnails will be recreated for all images or just for the new images depending on the overwrite thumbnails setting. Deleted images will be removed from the gallery and the corresponding thumbnails will be deleted. Any edits to your captions for the current set of images will be preserved. There is no way to recover a caption from a deleted image – keep a backup!

Trouble-shooting

  1. If you just see a very long string of computer code when you try to run the BuildGallery script then you do not have PHP installed on your server at all. Contact your server admin or helpdesk to see if it can be installed for you.
  2. Check the server requirements.
    • A web server (Unix or Windows), running PHP version 4.3.0 or later. BuildGallery will report the PHP version in the footer at the bottom of the screen.
    • PHP must have access to the GD graphics library, version 2.0 or later. You will see an error message if GD is missing or older than version 2.
    • PHP must have access to the XML parser functions. If not then you will see an error message.
    • PHP Safe Mode should ideally be off. Some server setups with Safe Mode on may be ok, others may be too restrictive to allow BuildGallery to run properly. BuildGallery will report the safe mode setting in the footer at the bottom of the screen.
  3. Check the permissions. Set file permissions on your gallery folder, the gallery.xml file and thumbs folder to read/write/execute for all levels (777). You can usually do this with your FTP program or there may be a utility program provided by your web host.
  4. Post a question on the SimpleViewer Forum. It would be helpful to include the word ‘BuildGallery’ in the forum topic title.

Setting the BuildGallery defaults

If you are creating a large number of galleries and you don’t want to use the standard default settings then you may want to create your own defaults for BuildGallery. There are two ways to do this.

The first way is to create a basic gallery.xml file with your preferred settings and copy this into all new galleries. BuildGallery will read the file and show your settings in its data entry form. This method only works for settings contained in the gallery.xml file.

The following settings are not included in the gallery.xml file: Add links, Add captions, Underline links, Sort order, Overwrite thumbnails. So if you want to change these default settings then you will need to edit the BuildGallery script itself. Open the BuildGallery script in a text editor (not a word processor) and look under the comment //Set default options here. Change the settings as required, for instance:
$bgOptions['addLinks'] = false;

Be careful with quote marks, semi-colons etc.

You can also set the gallery.xml defaults here if you wish but please note that there are some differences in format from what you see in the BuildGallery data entry form. For instance, colors must be in the format 0xFFFFFF. If in doubt, refer to the list of SimpleViewer xml options on the Airtight Interactive web site.

Reference

BuildGallery Options

Option Name Default Value Description
Gallery title SimpleViewer Gallery

Text to display as the gallery Title. Title text can include a limited set of HTML formatting including hyperlinks, line breaks, font tags, bold, underline and italics.

Note for advanced users: there is no need to encode any special characters such as the left and right angle bracket, BuildGallery will take care of this for you.

Text color FFFFFF Color of title and caption text (hexadecimal color value). There is no need to enter any special characters such as 0x or # to indicate the hex value.
Frame color FFFFFF Color of image frame, navigation buttons and thumbnail frame (hexadecimal color value). There is no need to enter any special characters such as 0x or # to indicate the hex value.
Gallery alignment center

Placement of the image and thumbnails within the SWF. For large format galleries this is best set to center. For small format galleries setting this to (say) top left or bottom right can help get the image flush to the edge of the swf.

Note for advanced users: this option in BuildGallery, sets two values in the xml file: valign and halign.

Navigate position left Position of thumbnails relative to image.
Thumbnail rows 3 Number of thumbnail rows. To disable thumbnails completely set this value to 0.
Thumbnail col’s 3 Number of thumbnail columns. To disable thumbnails completely set this value to 0
Sort order newest first Images can be sorted by file name or age. The file name sort is case-sensitive. Images that are uploaded in a single batch may be given the same time-stamp by the server, so in this case you will not be able to sort by age within the batch of images.
Image path  

Relative or absolute path to the images folder. This value is only required if you don’t want to put your images in the images folder.

Relative paths are relative to the HTML document that contains SimpleViewer. It doesn’t matter if you end the path with a trailing slash or not, BuildGallery will not show the trailing slash but will add it in the gallery.xml file.

Thumb path  

Relative or absolute path to the thumbnail images folder. This value is only required if you don’t want to put your thumbnails in the thumbs folder.

Relative paths are relative to the HTML document that contains SimpleViewer. It doesn’t matter if you end the path with a trailing slash or not, BuildGallery will not show the trailing slash but will add it in the gallery.xml file.

Background image  

Relative or absolute path to a JPG or SWF to load as the gallery background.

Relative paths are relative to the HTML document that contains SimpleViewer. For example: images/bkgnd.jpg.

Frame width 20 Width of image frame (pixels).
Stage padding 40 Width of padding around gallery edge (pixels). To have the image flush to the edge of the swf, set this to 0.
Nav padding 40 Distance between image and thumbnails (pixels).
Max image width 480 Width of the widest image in the gallery. Used to determine the best layout for your gallery (pixels).
Max image height 480 Height of tallest image in the gallery. Used to determine the best layout for your gallery (pixels).
Add captions checked Add captions derived from the file name. This applies to newly uploaded images only so if you have already added your own captions they will not be overwritten.
Add caption links checked Add links so that clicking on the caption leads to the image itself. This applies to newly uploaded images only.
Underline links checked Underline the caption links. This applies to newly uploaded images only.
Right click download checked Whether to display an 'Open In new Window...' dialog when right-clicking on an image.
Overwrite thumbnails checked If this box is checked then new thumbnails will be generated every time you press the Update button. If this box is not checked then thumbnails will be generated for new images only which is faster and useful if you have created any custom thumbnails outside BuildGallery.

HTML Options

Modify HTML Options by editing the HTML file that contains SimpleViewer in any text editor. HTML options are set with JavaScript in this format:

fo.addVariable("xmlDataPath", "gallerydata.xml");  

The first parameter is the name of the option. The second parameter is the required value. Both parameters require quotation marks.

Option Name Default Value Description
xmlDataPath "gallery.xml" Relative or absolute URL of the gallery XML file. Relative paths are relative to the HTML page that contains the swf.
firstImageIndex 0 Index of image to display when gallery loads. Images are numbered beginning at zero. You can use this option to display a specific number based on the URL. Check here for details.
langOpenImage "Open Image in New Window" The text displayed for the right-click 'Open Image in New Window' menu option. Can be used to translate SimpleViewer into a non-English language.
langAbout "About" The text displayed for the right-click 'About' menu option. Can be used to translate SimpleViewer into a non-English language.
preloaderColor 0xFFFFFF Preloader color (hexadecimal color value).

Version history

Upgrade to svManager

svManager can be purchased from Airtight Interactive and contains many more features than BuildGallery. Here are some of the additional features:

Support

Please post any comments or questions about BuildGallery.php in the SimpleViewer Forum. It would be helpful to include the word ‘BuildGallery’ in the forum topic title.