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
- The colour of the scroller background, nav links and thumbnail backgrounds
There are three examples found here, each highlighting different configuration options of the script.
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.
var so = new SWFObject("scroller_x.swf", "my_scroller", "100%", "130", "8");
// -- REQUIRED FIELDS --
// -- OPTIONAL FIELDS --
// auto-scrolling fields
// smooth-load fields
// mouseover effects
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
(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
The downloadable zipfile contains a blank XML file with the appropriate nodes.
<?xml version="1.0" encoding="UTF-8"?>
<caption>My Second Caption</caption>
<caption>My Third Caption</caption>
|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.|
|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.|
|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).|
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).|
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:
<div id="scroller1" style="width:600px; height: 66px;">
Your browser is not able to run this Flash script.<br />
Requirements: <br />
- You must have Flash installed<br />
var so3 = new SWFObject("scroller_x.swf", "scroller1", "100%", "66", "8");
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
<?xml version="1.0" encoding="UTF-8"?>
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!
A big thanks to Digital Nemexis for sponsoring this feature.
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.
// handles the information send from the image scroller. Information is sent via a single parameter,
// of type Object.
var index = info.index;
var linkURL = info.linkURL;
var thumbURL = info.thumbURL;
var thumbWidth = info.thumbWidth;
var thumbHeight = info.thumbHeight;
And here’s how you would set it if you’re using XML:
<?xml version="1.0" encoding="UTF-8"?>
<caption>A link to google!</caption>
|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.|
This project has been moved to github. You can download the entire source code, including the .fla from this repository.