Flash Image Scroller

I wrote this script many years ago (2006). It’s now outdated and has some known bugs. Unfortunately I’m no longer able to continue developing this script. If you wish to edit the code or take over the project, just fork it on github.

Overview

The Flash image scroller is a simple, free (GNU-licenced), highly configurable Flash script that you can add to your webpages to provide an intuitive “window” to scroll through a series of thumbnail images. Currently it only allows for horizontal scrolling. It is compatible with any server side language like PHP, ASP, JSP, ColdFusion etc.

The configurable options include:

Any thumbnail size
Glow, shadow and zoom mouseover effects
Auto-scrolling and smooth loading (thumbs fade in sequentially)
Infinite looping
Randomizing the thumbnail order
Captions – including font size, colour and alignment
The URL and target (e.g. frame name) to link to for each thumbnail
XML or query string-based source file
Option to send thumb info to javascript on clicking thumb
The colour of the scroller background, nav links and thumbnail backgrounds

Included in the download package is Geoff Stearns’ SWFObject (formerly FlashObject). This is a Flash detection and embed script, which does all the nitty gritty of determining whether or not a person’s browser is capable of running the script. SWFObject greatly simplifies your job of adding the image scroller to your website in a cross-browser friendly manner. It’s available for download and use under the MIT license. Also, the Flash / JavaScript Integration Kit written by Christian Cantrell and Mike Chambers from Adobe. This script allows us to send information from Flash to JavaScript.

Examples

There are three examples found here, each highlighting different configuration options of the script.

Configuration Options

As the Flash Image scroller matures, there are a more and more configurable options, but don’t let that put you off! All except five fields are optional. When configuring your own scroller, what I’d strongly suggest is adding the required fields first, then tweaking it by adding only those settings you need.

With that in mind, here’s an example of an image scroller definition that contains all supported configuration options. A lot of the options are self-explanatory from the name, but there’s documentation on each configuration option below.

As you can see, the configuration is done in the javascript, embedded in your page. The required settings are marked off in their own section, followed by the optional setting. Each setting is explained in the table below – note, these settings are case sensitive!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

Option

Definition

Required Fields

sourceFile

This is the source file containing the content to display in the image scroller. The content to be displayed can be in either a query string format, or an XML file.

1. Query String formatted file

thumbURLX	the URL (absolute or relative) of the thumbnail (required)
titleX	the thumbnail caption (optional)
linkURL	Where to link to when the thumbnail is clicked (optional)
targetX	the HTML target (e.g. _blank, an iframe/frame name, or “javascript” if you want to send the thumbnail information to your own custom javascript function.

(where X is a number beginning with 1).

Each value must be separated by an ampersand (&) character as in a query string, e.g. &thumbURL1=/path/to/image1.jpg&title1=My Caption&thumbURL2=/path/to/image2.jpg&title2=My Second Caption&

The downloadable zipfile contains a couple of examples of how this file can be built and how it is structured.

2. XML file

Nodes:

thumbURL	the URL (absolute or relative) of the thumbnail (required)
linkURL	Where to link to when the thumbnail is clicked (optional)
caption	the thumbnail caption (optional)
target	the HTML target (e.g. _blank, an iframe/frame name, or “javascript” if you want to send the thumbnail information to your own custom javascript function)

The downloadable zipfile contains a blank XML file with the appropriate nodes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<?xml version="1.0" encoding="UTF-8"?>
<items>
<item>
<thumbURL>http://www.mysite.com/thumbnail1.jpg</thumbURL>
<linkURL>http://www.mysite.com/linkpage.html</linkURL>
<caption>My caption</caption>
<target>myframe</target>
</item>
<item>
<thumbURL>http://www.mysite.com/thumbnail2.jpg</thumbURL>
<linkURL>http://www.mysite.com/fullimage.jpg</linkURL>
<caption>My Second Caption</caption>
<target>_blank</target>
</item>
<item>
<thumbURL>http://www.mysite.com/thumbnail3.jpg</thumbURL>
<linkURL>http://www.mysite.com/fullimage2.jpg</linkURL>
<caption>My Third Caption</caption>
<target>javascript</target>
</item>
</items>

fileType	Either “XML” or “text” to indicate what format the source file is in. This field isn’t strictly required, since it will default to “text”, but it never hurts to include it.
stageWidth	The width of the scroller, in pixels.
stageHeight	The height of the scroller, in pixels.
thumbSize	The maximum size of the thumbnails to be displayed. This should be set to the greatest width or height of the set of thumbnails. Ideally, thumbnails should be of a consistent height / width for best appearance.
Optional Fields
infiniteLoop	If this setting is included and set to “yes”, it will set the contents of the scroller into an infinite loop: when it reaches the end of the thumbnails you included, it will begin again from the first thumbnail. Note: if you didn’t include enough thumbnails to fill the first page, it will automatically pad out the first page with enough items to allow for infinite looping.
randomize	If this setting is included and set to “yes”, it will automatically randomize the contents of the scroller. Note: if you don’t want it to be randomize, omit the option altogether (don’t just set it to “no”).
startAt	Lets you set the first thumbnail in the scroller to be something other than the first item in the list.
maxNumItems	This lets you control the limit the number of items that appear in the scroller. If, for example, your XML feed contains 100 items, but only wanted to display 50, you could set this value to 50: it will then only show the first 50 items. Or, if used in conjunction with the “randomize” option, it will show a random subset of 50 items taken from the total set of 100.
scrollSpeed	An integer value of 1-20, determining the speed of the scroller (1 = slowest). Remember that scrolling speeds will be different depending on the person’s computer speed. The default speed is 10.
bgColor	The background colour of the scroller in hex (e.g. 336699). Be sure to omit the “#” sign and only include the colour code. The default background colour is white (ffffff).
navColor	The background colour of the nav bars in hex (e.g. ffffee). As with the bgColor, be sure to omit the “#” sign and only include the six characters. When there are no more items to scroll in one particular direction, the appropriate nav bar (left or right) will be faded out to 30% of it’s original colour, to indicate to the user that he/she can’t scroll any more. The default background colour is dark grey (7c7c7c).
arrowColor	The colour of the nav bar arrows in hex (e.g. ffffee). As with the other colour settings, be sure to omit the “#” sign and only include the six characters. The default background colour is white (ffffff).
thumbAlign	This determines how the thumbnail is to be aligned within it’s square. The options are “vertical”, “horizontal”, “both” or “none”. The default position is none (i.e. top left).
captionSize	This is the text size of the caption in pt. The default is 10pt.
captionColor	This is the text colour of the caption. The default is black.
captionAlign	This determines the alignment of the caption text. There are three options: “left”, “center” and “right”. The default is center.
thumbPadding	This setting lets you control the amount of padding (in pixels) around a thumbnail. It applies to all four directions: left, right, above and below. This provides you with a means to evenly distribute your thumbnails along the width of the image scroller without having some unsightly leftover space at the end. The default padding is 10 pixels.
thumbPaddingTop	This and the following option provide you with a little more control over the spacing in the image scroller – specifically, the space above the thumbnail. Note: this is in conjunction with thumbPadding – it does not override the thumbPadding setting. So, if you wanted a larger width between thumbnails, but a smaller height, you could set a negative value for thumbPaddingTop. This is defaulted to 0 pixels.
thumbPaddingBottom	Just like thumbPaddingTop, except for the bottom of the thumbnail. Handy for adding a little padding between a thumbnail and its caption. This is defaulted to 0 pixels.
thumbBackgroundColor	The color of the background squares that appear behind each thumbnail. This is handy if your images are not all of a fixed size; it nicely frames your thumbnails. The default colour is grey, #cccccc.
thumbBackgroundOpacity	The opacity of the background coloured squares behind each thumbnail. This allows values of 0-100, where 0 is completely faded out, and 100 is full colour. The default value is 50.
jsClickHandler	This option lets you specify the name of the javascript function that will be called when a user clicks a thumbnail. If this value is not specified, the default function name is image_scroller_clicked. If you are not using the javascript functionality, just ignore this configuration option. You can learn more about how to pass thumbnail information to javascript below.
autoScroll	This option, if set to yes, makes the scroller automatically begin scrolling on page load. By default, auto-scrolling is deactivated. Auto-scrolling will continue until the user rolls their mouse over the scroller or it reaches the end of the list of thumbnails.
autoScrollSpeed	This option lets you determine the speed of the auto-scrolling. The valid values are 1-20, but note that these speed values are 1/4th as fast as the scrollSpeed value, since auto-scrolling would generally be a lot slower than the scroll speed – this allows you to fine tune it a little better. The default value is 4.
autoScrollPause	This lets you determine the wait time after the scroller has loaded and when it begins auto scrolling. This value is in milliseconds (1sec = 1000ms). The default value is 1000.
smoothLoad	This option is purely aesthetic: if set to yes, instead of just loading the first page of thumbnails as soon as they load (in any order), it loads them sequentially from left to right. When used in conjunction with the two following options, initFadeInSpeed and initFadeInItemPause, it can create a very nice effect indeed. See the galaxy thumbnails on the example page for an illustration. This feature is de-activated by default.
initFadeInSpeed	This option lets you control the speed at which the first page thumbnails fade in, when using the smoothLoad option above. The valid options are 1-20 (1 == slowest, 20 == fastest). The default value is 5.
initFadeInItemPause	This lets you determine the pause between each item fading in. If you have a lot of thumbnails appearing per page, you’ll probably want a small value. The default value is 400 milliseconds.
thumbMouseOverEffects	If you wish to add any thumbnail mouseover effects, you will need to include this setting. This was added in 1.7 and can include any of the following values: glow, shadow or zoom. If you wish to include more than one effect, just separate them with colours: zoom,glow,shadow.
zoomSpeed	The speed at which the thumbnail zooms in and out. The valid values are 1-20 (default value of 10).
zoomSize	The number of pixels which the thumbnail will zoom out (default value: 8).
glowType	This option lets you choose whether the glow effect appears outside the thumbnail (outer, which is the default) or inside the thumbnail (inner).
glowSpeed	The speed at which the glow appears and disappears. Valid values are 1-20 (default: 10).
glowColor	The glow color. Note: as with all other colours in the scroller, this value should be in hex without the “#” character (default value: blue, 1970D7).
glowAlpha	This lets you set the percent transparency of the glow effect. Valid values: 0-100. By default, it’s set to 50.
glowBlurX	The number of pixels that the glow should be blurred in the x-direction (horizontal). By default, this is not used.
glowBlurY	The number of pixels that the glow should be blurred in the y-direction (vertical). By default, this is not used.
glowStrength	The strength of the glow effect. Valid values are 1-15, with a default value of 5.
glowQuality	The quality of the glow effect. Valid values 1-3 (default: 2).
shadowDistance	The distance in pixels from the original thumbnail that the shadow should appear (default: 8).
shadowSpeed	The speed at which the shadow appears and disappears. Valid values are 1-20 (default: 10).
shadowColor	The shadow color. Note: as with all other colours in the scroller, this value should be in hex without the “#” character (default value: grey, 333333).
shadowAlpha	This lets you set the percent transparency of the shadow effect. Valid values: 0-100. By default, it’s set to 50.
shadowAngle	The angle at which the shadow appears (in degrees). Valid values: 0-360. By default, it’s set to 45.
shadowBlurX	The number of pixels that the shadow should be blurred in the x-direction (horizontal). By default, this is not used.
shadowBlurY	The number of pixels that the shadow should be blurred in the y-direction (vertical). By default, this is not used.
shadowStrength	The strength of the shadow effect. Valid values are 1-15, with a default value of 5.
shadowQuality	The quality of the shadow effect. Valid values 1-3 (default: 2).

Installation

Getting the image scroller running is generally pretty simple. It shouldn’t pose any problems for web developers but it may be a little daunting for non-technical types. So to help out, here’s some step by by step instructions on how to get it up and running.

Note, you’ll need to first download the zipfile from github.

1. Import swjobject.js and scroller_x.swf

From the downloadable zipfile, extract the swfobject.js and scroller_x.wsf files and upload them to the same folder as the webpage to which you’re adding the image scroller. Note: you can actually place it wherever you want, but the sake of simplicity we’re going to assume it’s in the same folder.

2. Set up your scroller

In between the … tags of your page, import the swfobject library:

1	<script src="swfobject.js"></script>

Next, add the following chunk of HTML and JavaScript into the place in your page where you would like the image scroller to appear.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<div id="scroller1" style="width:600px; height: 66px;">
Your browser is not able to run this Flash script.<br />
<br />
Requirements: <br />
- JavaScript must be enabled<br />
- You must have Flash installed<br />

<script type="text/javascript">
var so3 = new SWFObject("scroller_x.swf", "scroller1", "100%", "66", "8");

so3.addVariable("sourceFile", "my_thumb_info.txt");
so3.addVariable("fileType", "text");
so3.addVariable("scrollSpeed", "10");
so3.addVariable("stageWidth", "600");
so3.addVariable("stageHeight", "66");
so3.addVariable("thumbSize", "60");
so3.addVariable("bgColor", "666666");
so3.addVariable("navColor", "333333");

so3.write("scroller1");
</script>
</div>

Now tweak that code to fit for whatever settings you want: your thumbnail size, the scroller width and height and the background and nav bar colours. It may take a little back-and-forth to get the scroller looking the way you want it. See the section above for the available configuration options.

Here’s how this code works. When the page is loaded, if the SWFObject code determines that the browser can handle it, it replaces the div content marked with id=”scroller1″ with the flash program specified in the first parameter of the SWFObject constructor call. The third parameter is the width (always leave at 100% since you’ve specified the width in the overall div tag); the fourth parameter is the height. This must be included since setting it to 100% may confuse IE. The final parameter is the version of Flash required to run the script: in this case, version 6.

3. Create your thumbnail source file

This will be the trickiest part for non-technical users. Basically, your job is to create a file that contains the information (thumbnails, captions and other) to funnel into the image scroller. This can be created in two different formats, depending on your preference: a query string file, or an XML file.

1. Query string file

&thumbURL1=http://yoursite.com/path/to/th_img1.jpg&title1=My Caption 1&target1=_blank&linkURL1=http://yoursite.com/path/to/img1.jpg&
&thumbURL2=http://yoursite.com/path/to/th_img2.jpg&title2=My Caption 2&target2=_blank&linkURL2=http://yoursite.com/path/to/img2.jpg&
&thumbURL3=http://yoursite.com/path/to/th_img3.jpg&title3=My Caption 3&target3=_blank&linkURL3=http://yoursite.com/path/to/img3.jpg&
&thumbURL4=http://yoursite.com/path/to/th_img4.jpg&title4=My Caption 4&target4=_blank&linkURL4=http://yoursite.com/path/to/img4.jpg&
&thumbURL5=http://yoursite.com/path/to/th_img5.jpg&title5=My Caption 5&target5=_blank&linkURL5=http://yoursite.com/path/to/img5.jpg&

Make sure you end every line with an & character.

2. Your XML file should have the following structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?xml version="1.0" encoding="UTF-8"?>
<items>
<item>
<thumbURL></thumbURL>
<linkURL></linkURL>
<caption></caption>
<target></target>
</item>
<item>
<thumbURL></thumbURL>
<linkURL></linkURL>
<caption></caption>
<target></target>
</item>
</items>

The order of the item nodes are not important, and within the item nodes, only the thumbURL node is required.

When you have created your file, upload it to your folder on your server and call it my_thumb_info.txt or whatever you specified in the code in your page. Now refresh your page in your browser – if all went well you should see your populated image scroller!

Passing thumbnail info to javascript

With version 1.5, you now have the option of passing the information about the thumbnail to javascript when the user clicks the thumbnail. For example, you could use it to keep track of which thumbnails a person clicks, or load the appropriate thumbnail into a page element via javascript code – whatever you need!

A big thanks to Digital Nemexis for sponsoring this feature.

To pass the thumbnail information to javascript, you need to do three steps.

Step #1

Included in the downloadable zipfile is a javascript file called JavaScriptFlashGateway.js. Include this file in the head of your page, like so:

1	<script type="text/javascript" src="JavaScriptFlashGateway.js"></script>

This file is part of the Flash / JavaScript Integration Kit written by Christian Cantrell and Mike Chambers from Adobe. It allows us to send information from Flash to JavaScript.

Step #2

Next, write a separate function that handles the return value from the image scroller. Here’s an example which lists all the object properties available.

1
2
3
4
5
6
7
8
9
10
11
12

// handles the information send from the image scroller. Information is sent via a single parameter,
// of type Object.
function image_scroller_clicked(info)
{
var index = info.index;
var linkURL = info.linkURL;
var thumbURL = info.thumbURL;
var thumbWidth = info.thumbWidth;
var thumbHeight = info.thumbHeight;

alert(thumbURL);
}

The name of this function may be customized to whatever you wish, by setting the jsClickHandler configuration option. If you do not set this option with your own custom javascript function name, it will look for a function named image_scroller_clicked.

Step #3

Lastly, you need to let the image scroller know to send the information via javascript. This is done through by setting the “target” value to “javascript”. For example, here’s how it would work through the query string formatted file:

&thumbURL1=http://yoursite.com/path/to/th_img1.jpg&title1=My Caption 1&target1=javascript&linkURL=http://yoursite.com/path/to/img1.jpg&
&thumbURL2=http://yoursite.com/path/to/th_img2.jpg&title2=My Caption 2&target2=javascript&linkURL=http://yoursite.com/path/to/img2.jpg&

And here’s how you would set it if you’re using XML:

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="UTF-8"?>
<items>
<item>
<thumbURL>http://www.yoursite.com/yourthumb.jpg</thumbURL>
<linkURL>http://www.google.com</linkURL>
<caption>A link to google!</caption>
<target>javascript</target>
</item>
</items>

And you’re done! Now you can do whatever you want with the thumbnail information from with javascript. Just for your reference, here are all the object properties available in your return function.

index	The position of the thumbnail within the image scroller (indexed from 0).
linkURL	The linkURL value specified for the thumbnail.
thumbURL	The thumbnail URL.
thumbWidth	The width of the thumbnail.
thumbHeight	The height of the thumbnail.

Download

This project has been moved to github. You can download the entire source code, including the .fla from this repository.

Overview

Examples

Configuration Options

Option

Definition

1. Query String formatted file

2. XML file

Installation

1. Import swjobject.js and scroller_x.swf

2. Set up your scroller

3. Create your thumbnail source file

Passing thumbnail info to javascript

Step #1

Step #2

Step #3

Download

Categories

Archives

Random photo

Links

Recent Comments

Recent Tweets

Flash Image Scroller

Overview

Examples

Configuration Options

Option

Definition

1. Query String formatted file

2. XML file

Installation

1. Import swjobject.js and scroller_x.swf

2. Set up your scroller

3. Create your thumbnail source file

Passing thumbnail info to javascript

Step #1

Step #2

Step #3

Download

Categories

Archives

Random photo

Popular Posts

Links

Recent Comments

Recent Tweets