SlideshowBox is a Flash-based slideshow viewer provided by JumpeyeComponents. SlideshowBox comes in several versions, one of which is free for non-commercial use. To obtain the free version, you will need to register with JumpeyeComponents using a valid E-mail address. Once you have registered, you will be sent a download link.

If you plan to use SlideshowBox for your commercial site, you will need to purchase a commercial license. Purchasing a commercial license will allow you to customize the templates to suit your site design, and provides free updates and tech support. If you are a web designer, an OEM license option is also available.

Installation

After downloading and opening the free/trial version of SlideshowBox, you will see the zip file contains 2 slideshow components. One is for use with Flash Actionscript 3 as a Flash extension for Adobe Flash CS4/CS5. This component is probably not of much use for the normal SiteSpinner user. The 2nd component is HTML-based and you will find this one more useful in SiteSpinner, so extract the entire zipped HTML folder to a folder on your disk. This component is not installed under Windows, but instead is used directly inside your browser, so make note of where you placed the extracted files. It would be a good idea to backup the downloaded SlideshowBox zip file in case to need to extract the files again later.

The extracted HTML file contains several files and two folders. One of the folders (named /images) holds sample photos. The other folder (/templates) holds the 24  templates (SWF files) used to theme the slideshow. The remaining files consist of:

• readme.pdf – An simple instruction manual.
• sample.xml – An XML files used to specify the images for the slideshow.
• sample_slideshow.html – Double-clicking this file will open the browser and run a prebuilt sample slideshow.
• SSB-EmbedCodeGenerator.html – A page to help you generate the code to use on your page and sample the various templates.

Navigate to the extracted HTML folder and double-click the SSB_EmbedCodeGenerator.html file. This will open in your default browser and will allow you to configure the HTML-based component. As the figure below shows, this page has 4 user options.

• The first labeled “XML source” allows you to enter the name of the XML file used to specify the images that will be displayed in the slideshow. The default is sample.xml and is provided with the download (as are the sample images).
• The 2nd and 3rd user options allow you to specify the desired width and height of the slideshow display. The default setting is 550×400 pixels. You should adjust these values so your images are not clipped.
• The last option is a drop-down list to select the type of template to use for your slideshow.

Once you have entered your options, you can click the Apply button. This will do two things: 1) it will begin displaying the slideshow using the selected template, and 2) the code needed to present the slideshow on your page is shown. If you wish, you can select another template and re-click the Apply button. This will update the slideshow display and modify the code to reflect the template change.

Specifying Images

Images for the slideshow are specified using an XML file. If you have never dealt with XML files before, this will be the most challenging  aspect of using the slideshow. A sample XML file is provided in the download that you can open in a plain text editor and modify to suit your own needs. Just remember to save the file under a new file name since the sample XML file is used by the code generator page as the default source XML file. If you modify the default sample file, the code generator page may not work properly. Be sure to use a plain text editor when building your XML file; do not use a word processing program.

The basic structure of the source XML file is:

<SlideshowBox>
  <items>
    <item>
      <thumbnailPath>path/name_of_thumbnail_image</thumbnailPath>
      <largeImagePath>path/name_of_normal_image</largeImagePath>
      <fullScreenImagePath>path/name_of_full-sized_image</fullScreenImagePath>
      <title>title_for_the_image</title>
      <description>caption_for_the_image</description>
    </item>
  </items>
</SlideshowBox>

Images are defined within an <item> node and multiple <item> nodes can exist within the <items> node. Within each <item> node, there can be 5 elements: <thumbnailPath>, <largeImagePath>, <fullscreenImagePath>, <title> and <description>.

• <thumbnailPath> is used to define the location and name of the image to be used in templates that use thumbnails, such as the SimpleFadeThumbnail template.
• <largeImagePath> is used to define the location and name of the normal-sized image used in the slideshow. This element is required.
• <fullscreenImagePath> is used to define the location and name of the image that will be displayed if the slideshow is placed into full-screen mode.

The <largeImagePath> element must always be specified so the slideshow will know where to find the “normal” sized images to be used. These “normal” images do not need to be the same size. You should ensure that the slideshow’s width and height is sufficiently large enough to accommodate the dimensions of the largest image; if not, the image will be cropped in the display window.

If your selected template does not require thumbnails, then you may omit the <thumbnailImagePath> element. If your selected template does require thumbnails and you do not include this element, SlideshowBox will scale the images specified by <largeImagePath> as thumbnails. However, you should keep in mind that the thumbnails used by SlideshowBox are only 24×24 pixels, so scaling the larger images that small may not be suitable. If this is the case with your images, you should consider creating your own thumbnails using an image processing program and uploading them to your site. You can then use the <thumbnailImagePath> so the slideshow can use them.

Likewise, if you omit the <fullscreenImagePath>, SlideshowBox will display the large images on the full-screen display. However, these images will not be scaled to fit the larger screen, so the large image will be show at its normal size in the middle of the screen. If you want to display larger versions of your images, upload them to your site and use the <fullscreenImagePath> element to specify their location and name. Since you will not know the maximum screen resolution of your visitor’s monitor, you should limit the size of the full-screen images to some “standard and common” size, such as 1024×768 or 1200×760.

[Hint: SiteSpinner automatically publishes images to the /image folder of your site. If you specify this folder as the location in the XML file, you can simplify uploading the images to your site, as will be discussed later. Also, if you use thumbnails and/or full-screen images, you should prefix their file names with a "t_" and "f_" (or some other notation) so you can easily recognize the different images.]

The <title> and <description> elements are used to provide a title and caption to your images. These elements are optional. The location of these displayed elements in the slideshow depends upon the template being used.

Selecting a Template

The easiest way to choose a template for your slideshow is to use the SSB_EmbedCodeGenerator.html page. This will allow you to use your source XML file and images and test them in the available templates via the code generator’s drop-down list. I suggest that you copy the code generator HTML page and the template folder into your SiteSpinner preview folder. This will allow you to select a template, and once you have done that and added the code to your SiteSpinner page, the SlideshowBox components are already in place when you preview your SiteSpinner page with the code.

After you have created your source XML file, copy it into the folder where you have placed the SlideshowBox code generator page and the templates. Also copy the images into this location. If you have gathered all you images into a folder, copy the entire folder to this location.

Now double-click the code generator HTML page so it will open in your browser. In the “XML source” field, enter the name of your XML file and set the desired width and height for your slideshow. Then pick a template from the drop-down list and click the “Apply” button. If your images are clipped in the slideshow, adjust the width and height and re-click the “Apply” button. If you want to test another template, just choose a new one from the drop-down lost and re-click the “Apply” button. You can continue to test templates and adjust the slideshow dimensions until you are satisfied with the results.

Using with SiteSpinner

If you feel comfortable using code objects in SiteSpinner, you can simply copy and paste the code presented on the code generator page into a SiteSpinner code object. Make sure the code object’s code placement is set to “in Body”. Size the code object to the dimensions used by the code so you can see how it would fit on your page and position it where you want. Since you are using a code object, you will need to ensure that the template file, source XML and images are uploaded to your site and placed in the appropriate folders.

If you would rather use the normal SiteSpinner tools, then use the Embed File/Media tool and select the Flash format and use the “Filepath” button to load your desired template. You will then need to enter the parameters required for the slideshow. In the Parameters section of the window, enter flashvars in the first “Name” data field and in the corresponding “Value” field, enter source=name-of-xml-file.xml replacing “name-of-xml-file.xml” with the name of your source XML file. In the next “Name” field, enter allowFullScreen and in the corresponding “Value” field, enter true if you want to enable full-screen display of the slideshow or false to disable it (see the sample below). Click OK to save the Flash object.

SiteSpinner Preview and Publishing

To preview SlideshowBox, you will need to make sure that the appropriate files are copied into your preview folder. If you do not know where your preview folder is located, use the main menu Options->Preview Options… item to open the Workspace Options window and look at the Preview tab.

If you included the slideshow on your page using a code object, you will need to make sure that the template you have selected resides in the preview folder inside a sub-folder named templates as this is the default folder name used in the code. Also make sure that the source XML file is in the preview folder and that the images are located where the XML file specifies.

If you embedded the slideshow using a flash object, SiteSpinner will automatically place the template into the /media sub-folder, so you do not need to do anything to copy or move the template. But you will need to make sure the source XML file and images reside in the preview folder.

To publish SlideshowBox, the files will need to be uploaded to your site. If you use an external FTP program to do this, then gather the same files you copied or moved to your preview folder, but this time upload them to your site.

As an alternative to using an external FTP program, it is possible to use SiteSpinner itself. If you embedded the SlideshowBox template as a Flash object, SiteSpinner will publish it to the /media folder. You can have SiteSpinner upload the source XML file by using the Embed File/Media tool again, but this time choose the “Publish File” format and use the “Filepath” button to load your XML file. When published, SiteSpinner will upload the file to the root directory of your site.

To have SiteSpinner upload your images, load all your slideshow images on a separate page and publish only this page. SiteSpinner will automatically publish them to the /image folder of your site. If you took the advice given above and specified this folder in your XML file, then everything will be in the proper location. If your XML file specified a different image folder, you can use the Publisher→Pages→Sub Folders… button to specify the desired folder name by modifying the “Image Files” value. Just remember to reset this value using the “Set Defaults” button after publishing so your project’s other images get published to the standard location. After the slideshow images have been published, you can delete this page from your project (the images only need to be uploaded once).