Slideviewer Documentation




Before installing you must make sure that you have:

Quick Install Guide

This is for people who are experienced or impatient.


The following definitions are a used to clarify terms used in the documentation.

Full URL

The complete URL for your site, eg:

Relative URL

A file location relative to the site portion of your full URL. For example, for the full URL the relative URL would be /slideviewer/images/house.jpg

Full directory path

When you specify a URL of a file, the web server it is coming from will know the full directory path on the Operating System where to retrieve the file from. For example, if I have a relative URL of /slideviewer/images the real location (full directory path) could be something like /home/ginini/htdocs/slideviewer/images



The source is contained in a gzip tar file or ZIP file.

To unpack the gzip tar file, type:

gzip -dc slideviewer.tar.gz | tar xvf -

To unzip the ZIP file, type:


or use WinZIP.

This will create a slideviewer directory with all the required files and sub directories.

IMPORTANT - When you FTP the files to your web server, make sure that only the graphics and midi files are transfered in binary mode, all other files should be transfered in ASCII mode. If you don't do this, it will most likely cause the script to fail.


Make sure slideviewer.cgi has execute permission set (if on a Unix system), ie: mode 755.


Choose a location for the Slideviewer files. Generally this would be somewhere under your web documents directory, eg: /home/ginini/htdocs/slideviewer

Depending on how your web server is configured, you may have to move the slideviewer.cgi script to your particular CGI directory in order for it to work. Check with your ISP or webmaster if you are not sure.

If you run virtual web sites and want to run one centralised copy of Slideviewer for multiple users, the best way to organise the files is to place the configuration files, Slideviewer images in one location and have the users place their design files, templates and slideshow lists under their own web directory. Then each user can call the script using the following form: /cgi-bin/slideviewer.cgi?config=user1.cfg&list=user1 This concept can also be applied to the same web site and if you are using it for more than one area.

slideviewer.cgi should be moved to your directory where you run all your CGI programs from.

Perl Locations

Edit slideviewer.cgi script and make sure the first line is the correct path for your perl location.

If you are installing on a Win/NT system, it depends which web server you are running as to whether the perl path is recognised. The path would be set to something like C:\perl\bin\perl.exe


Script Configuration

Edit the slideviewer.cgi and set the following parameters:

$ConfigDir - Set this to a directory where the configuration file will exist. The directory can be used to contain multiple configuration files for sites that want to use the one script for different users.

$DefaultCfg - The name of the default configuration file to use if none is specified with the config parameter.

Configuration File

The following items need to be set in default.cfg

Essential Configuration Section

Optional Preferences Section

Other Sections

You would not normally need to change any of the other sections unless you want to change the default names of template files, etc.


The following files exist in the templates directory:

Slideshow Definition Files

You define your slides and their titles in a slideshow definition file in the slideshows directory. The format is: URL|Title|Sub Title|Link URL|Object or :include someotherfile

The URL can be in any format described previously. Note that if you specify an http:// prefix, the script will access the image via the web server (or proxy server if you use it) to determine the image size. This will produce a slight overhead in processing. So if you have local images, it would be best to define them as relative to the server (ie: no http:// prefix).

The minimum fields you require is just the image URL, all the other fields are optional.

The :include file directive is useful if you have multiple slideshows and you want to define a complete collection. Rather than duplicate all the entries in a single file, you can just include each one in a master file, For example:

# Master file for all slide shows
:include show1.slides
:include show2.slides
:include show3.slides

You can use # for comments, and blank lines are ignored.

You should update the index file in the slideshows directory for each new slideshow you create. The index file is used by the slideshow selection form.

Design Files

The layout of the slideshow is controlled by a design file.

A design file consists of HTML code with special variables embedded in it. The special variables are surrounded by percent signs (%) or by means of a special tag prefaced with <SV_ For example:




These variables/tags are expanded to their appropriate value when slideviewer.cgi reads the design file.

The reason that two methods are given is:

  1. Personal preference. You may decide that using special tags is easier to ty pe and read, or visa-versa.
  2. Some HTML editors don't like %VARIABLES% or will change the formatting of them, in w hich case, using the special tags may help.

NOTE - You can mix both types of variables/tags if you desire.

The variables you can use are:

%TITLE% The main title of the image
%SUBTITLE%The subtitle of the image
%IMAGE%The image itself with all its attributes such as height, width and alt tags.
%IURL%The URL of the image
%HEIGHT%The height of the image
%WIDTH%The width of the image
%LURL%The link URL of the image (if specified)
%ALT%The ALT text to go with the link URL (if specified
%SINDEX%Link to the slides index window or dropdown index.
%COUNTER%The slideshow counter.
%BUTTONS%The direction control buttons.
%LINKS%All control links
%DIRECTIONLINKS%Directional control links
%SIZELINKS%Resizing control links
%REFRESHLINKS%Refresh control links
%RANDOMLINK%Random control link
%REVERSELINK%Reverse control link
%CONTROLS%The control panel including %COUNTER%, %BUTTONS% and %LINKS%
%OBJECT1%Can be used for any purpose such as additional URL's, text etc
%OBJECT2%Can be used for any purpose such as additional URL's, text etc
%OBJECT3%Can be used for any purpose such as additional URL's, text etc
%OBJECT4%Can be used for any purpose such as additional URL's, text etc
%OBJECT5%Can be used for any purpose such as additional URL's, text etc
%OBJECT6%Can be used for any purpose such as additional URL's, text etc
%OBJECT7%Can be used for any purpose such as additional URL's, text etc
%OBJECT8%Can be used for any purpose such as additional URL's, text etc
%OBJECT9%Can be used for any purpose such as additional URL's, text etc

This is an example shows my default design, and this is the actual design file.

Other Button Sets

You can choose alternate directional
button sets if you want to change the default look.


If you have a command line access on your web server, you can check that the syntax of the script is correct by typing:

perl -c slideviewer.cgi


perl -c default.cfg

If this was successful, try running it:


If it was successful it will spit out some HTML.

If you get any errors, check the Common Problems section.


There are three ways to invoke the script:

  1. By default calling slideviewer.cgi by itself will display the slideshow selection form.
  2. By calling the script direct with a slideshow list, eg: slideviewer.cgi?list=myslides
  3. By calling the script direct with the name of the directory defined in the dirindex file, eg: slideviewer.cgi?dir=mydir
  4. By calling the script direct with mutiple parameters, eg: slideshow.cgi?list=myslides&config=peter.cfg&design=fancy&scale=2&refresh=10

Parameters to the Script

There are a number of parameters you can parse to the script.

The list of parameters and their values that you can set are:

Common Problems

The most common problems reported are:

  1. The main problem seems to be confusion between a pathname and a URL. The pathname is the real location of the file on the web server, ie: a directory, and the URL is what you specify in your browser to view that particular file. Please re-read the definitions if you are unsure.
  2. If you can not resize your images, or the height and width tags are set to zero, it means that you have not defined the paths correctly.
  3. Not setting the perl path correctly at the top of the script.
  4. Not having the script in the proper CGI directory.
  5. Not having permission to run CGI programs. Some ISP's don't allow users to run CGI scripts.
  6. Not FTPing the files in the correct mode. Make sure that all non binary files are transfered in ASCII mode.
  7. Getting the Web document root or URL Mappings wrong.

Return to Slideviewer main page