Slideviewer Documentation

---

Prerequisites

• Perl 5.x installed on your system.
• Ability to run CGI scripts on your web server

Quick Install Guide

• Place the slideviewer.cgi in your cgi directory and make sure the perl path is correct and set the location of the configuration directory.
• Edit default.cfg to suit your site.
• Create a slideviewer slide definition file. Examples are in the slideshows directory. Make sure you update the index file in the same directory.
• If you just want to create a slideshow based on images in a directory, edit the dirindex to set the appropriate directory and URL.
• Edit the default file in the designs directory to change the layout of the slideshow. Make sure you update the index file in the same directory.
• Edit the files in the templates directory to suit your site.
• Call the script with slideviewer.cgi?list=slidelist if you are using a slidelist.
• If you are using a directory list, use: slideviewer.cgi?dir=mydir
• If you are using multiple configurations, call the script with slideviewer.cgi?list=slidelist&config=myconfig
• To bring up the slideshow selection form, use: slideviewer.cgi?form=yes

Definitions

Full URL

Relative URL

Full directory path

Installing

Extracting

To unpack the gzip tar file, type:

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

To unzip the ZIP file, type:

unzip slideviewer.zip

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.

Permissions

Location

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

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

Configuration

Script Configuration

$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

Essential Configuration Section

• $Slideviewer - Set this to the full directory path where the Slideviewer templates, design files and slideshow lists exist.
• $WebDocs - You define this to be the full directory path to the top level directory where your web documents exist. If you use directory aliases then you need to define %URLMappings instead.

  For example, if the full directory path to your web document root is:
  /home/peters/public_html.
  Then only use this variable if the URL of your images in the slide definition file can be appended to it to create the correct pathname to the image. For example:

  If the URL /images/foo.gif has the pathname /home/peters/images/foo.gif, then you can set $WebDocs="/home/peters"

  However, if the URL ~peters/images/foo.gif has the pathname /home/peters/images/foo.gif, using the same setting above, the script woudl try to find the image in /home/peters/~peters/images/foo.gif In this instance, you must use %URLMappings below.

• %URLMappings - This is required only if your web pages use a server alias or mapping. The most common example is users home directories. A URL like http://www.foo.com/~username will point to a home directory on the server. The script needs to know this mapping so it can work out the actual location of the images. Other examples may be a specific mapping to an area outside your web root. For example: http://www.foo.com/sales/ may point to a directory like /home/sales/www.
• $Proxy - You only need to set this variable if you specify images external to your site in the slide definitions file and only if your server accesses the outside world via a proxy server. Examples are:
  
  • http://www.ginini.com.au:8080
    
  • http://proxy.someisp.net:8000
    
• $Images - The URL to the directory where the arrow buttons images exist.
• $End - The URL for the page to display at the end of the slideshow.

Optional Preferences Section

• $DefRefresh - Default number of seconds for the refresh rate between loading each slide. Note that this behaviour is browser dependant. Some browsers wait the specified number of seconds after the page has loaded and some count the specified number of seconds from the start of when the page is loaded.
• $Adjust - The number of seconds to increase or decrease the refresh rate when the faster or slower links are selected.
• $ScaleFactor - The scaling factor to reduce or enlarge an image.
• $IndexPopup - The slide index list can either appear as a popup window or as a dropdown selection list on the main slideshow page. Setting this variable to 1 creates a popup window and setting it to 0 creates a dropdown list.
• $IndexWidth and $IndexHeight - are used only if the index popup window is selected.
• $DirOrder - If you are reading the images from a directory, you can choose the order of how they appear. Set to time for the images to be selected by date/time order, or set it to name for the images to be selected alphabetically.
• $DirReverse - If you want to reverse the order in which the files are selected in a directory, set this to 1. If you have time order selected, this will caused the oldest files to be listed first, if you have 'name' selected, the images will be selected in reverse alphabetical order.

Other Sections

Templates

• error.html - This template controls how you want the slideviewer error messages to be displayed.
• form.html - This template controls how the slideshow selection form looks.
• slideindex.html - This template controls how the slide index popup window looks.

Slideshow Definition Files

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

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:

%TITLE

or

<SV_TITLE>

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

Other Button Sets

Testing

perl -c slideviewer.cgi

and

perl -c default.cfg

If this was successful, try running it:

./slideviewer.cgi

If it was successful it will spit out some HTML.

Operation

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

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

list - Name of slideshow list. Example: list=holidays

config - Specifies what configuration file to use. This is particularly useful for sites with multiple users running the same script with their own setup. If you don't specify one, the default will be used. Example: config=mysite.cfg

cycle - Specifies whether to restart the slideshow when it gets to the end. This can be used for continious shows. Values are yes and no. Example cycle=yes

direction - Specifies what direction to view the slideshow, ie: from beginning to end or end to beginning (OK, I know it's a bit useless, but it's there). Values are forward and backward. Example: direction=backward

slide - Specifies a specific slide number. This can be useful if you want to jump to a slide in the middle of the show. Example: slide=30

filename - Start the slideshow at the specified filename in the list. Example: list=myphotos&filename=family.jpg

scale - Specifies the relative scale of the image. This can be used to set an appropriate scale based on screen resolution. A value of 0 is normal size, negative numbers reduce the image size and positive numbers increase the image size. Example: scale=-2

size - Specifies whether to enlarge or reduce the current image. Values are enlarge and reduce. Example: size=enlarge

design - Specifies what slideshow design to use. If you don't specify one, the default design file will be used.

Common Problems