Using BuildGallery

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

  1. Download SimpleViewer

    Download SimpleViewer and unzip the files. Copy the simpleviewer/web folder to your desktop. 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 BuildGallery and unzip it. Copy the buildgallery.php file into the same gallery folder that you created in step 1.

  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

  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

    You may need to 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.

  6. Run the BuildGallery Script

    In a web browser, navigate to the URL of your build script – for example

  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. View a description of the options here. SimpleViewer Pro options will remain unchanged.

    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)

    BuildGallery can create captions automatically based on the file name –┬áselect the Add captions option. This will only happen when it finds a new image. Captions for existing images will not be changed.

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

Using with SimpleViewer-Pro

You can use BuildGallery with SimpleViewer-Pro using the same steps as above. Use the web folder in the SimpleViewer-Pro download as your initial gallery folder.

To configure a Pro gallery created with BuildGallery, use FTP to download the gallery folder to your local machine then open it using svBuilder. Once you have configured the gallery and saved the changes, re-upload the gallery.xml file back to the gallery folder on your server.

Setting 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. This is the best approach for SimpleViewer Pro users.

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 and look under the comment //Set default options here. Change the settings as required, for instance:
$bgOptions['addLinks'] = 'false';


  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 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.
  3. If you see an error message saying that this version requires PHP5 and will not run under PHP4, try changing the name of the file from buildgallery.php to buildgallery.php5. If this does not work then contact your server admin or helpdesk and ask them how to set up your account so it defaults to PHP5. This is usually a simple procedure.

Server Requirements

BuildGallery requires the following:

  • A web server (Unix or Windows), running PHP. BuildGallery 2.1 requires PHP 5.0 or later and if you attempt to run it under PHP4 you will see an error message. BuildGallery will report the server's PHP version in the footer at the bottom of the screen. PHP5 was released in July 2004. Most web hosts support it but many accounts still default to PHP4. Try changing the name of the file from buildgallery.php to buildgallery.php5. If this does not work then contact your server admin or helpdesk and ask them how to set up your account so it defaults to PHP5.
  • 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.

Version History

  • Version 2.1.0 - Supports SimpleViewer 2.0. This version will convert older-style SimpleViewer 1.9 XML files to the SimpleViewer 2 format. Requires PHP 5.0 or later.

Upgrade to svManager!

svManager can be purchased for $35 and contains many more features than BuildGallery. Here are some of the additional features:

  • List all your galleries on one screen
  • Import existing galleries
  • Clone an existing gallery and retain your configuration settings
  • Rename or move galleries on the server
  • Create and manage SimpleViewer, TiltViewer, AutoViewer and PostcardViewer Galleries.
  • Drag-and-drop image upload to your server
  • Resize images automatically before upload
  • Color-picker eliminates need for entering hex values
  • Easy editing of image captions
  • Drag-and-drop image sort
  • Easy selection and deletion of images
  • Auto index page for multiple galleries
  • Protected by user name and password