You've probably noticed the image rotator on our front page. (And if you haven't, go take a look.) I recently updated it with a better coded, easier to use version, and decided to give it away to whomever would like it. It is released under the Creative Commons Attribution Share Alike license (v3), so you're free to use it wherever you'd like - just please give me attribution somewhere on your site or page.
Introducing KSROT
KSROT, while it may not sound particularly exciting or enticing, is the newest version of the image rotator. It is easy to install on your site and it is easy to use. You need four files (two, if you're really stingy) - the javascript code, the CSS code, and two image files (for next/back arrows). If you make your own images or decide you don't want that part, you can forget about the two images.
Using KSROT
Using KSROT is extremely easy. First, include the stylesheet in your page:
<link rel=stylesheet href="/scripts/ksrot/ksrot.css" type="text/css">
And include the script in your page, before any code that utilizes it:
<SCRIPT type="text/javascript" language="javascript" src="/scripts/ksrot_compressed.js"></SCRIPT>
Next, you need a DIV somewhere on your page that the rotator can attach itself to. It doesn't need anything inside it - just an ID that you'll remember later:
<div id="rotator"></div>
Okay - now that you've got that, we're ready to tell the rotator what DIV to attach to, and the settings we want to use:
<SCRIPT type="text/javascript">
var r = new Rotator("rotator", [ { 'width':'642', 'height':'353',
'controlBar':'yes',
'navigation':'yes',
'duration':'7500',
'animationSpeed':'25',
'tryAgainDelay':'500',
'useCaptions':'no',
'autoAdvance':'yes',
'useTitles':'yes' } ]);The first parameter is the ID of the DIV you want to attach to. In our case, our DIV is named "rotator", so that's what we put in the code. The next parameter is an array of configuration options. Most of these you can omit if you want - reasonable defaults will be supplied if you do, but you must specify the width and height options - otherwise you'll end up with a rotator that is pretty much unusable.
Each of the configuration options control how the rotator works. Here's what each mean:
- width: width of the rotator. I.E., "650". Do NOT add "px" to the option.
- height: height of the rotator. I.E., "350". Do NOT add "px" to the option.
- controlBar: An area at the bottom of the rotator that appears when the user hovers over the rotator. If "yes", this bar is enabled. If "no", the bar is disabled. The bar contains direct-access links to specific items in the rotator. The default is "yes".
- navigation: Two areas at the left and right of the rotator that allows the user to navigate to the previous and next images. If "no", these areas are disabled. If "yes", these are enabled. They only appear when the mouse is over the rotator. The default is "yes".
- autoAdvance: Determines if the rotator will auto-advance to the next image after a short delay. If "yes", the advance will occur automatically. If "no", the user must initiate an advance. The default is "yes".
- duration: Determines, in microseconds, the delay between automatic advances. It has no meaning if autoAdvance is "no". The default is "20000".
- animationSpeed: Determines, in microseconds, the delay between transition frames. A transition consists of 20 frames, so set this to a low value. The default is 25ms.
- tryAgainDelay: If a user attempts to navigate to another image while a transition is in progress, the action is queued up so that the current transition can complete uninterrupted. This delay is the amount of time, in milliseconds, until the action will be tried again. The default is 1 second (1000ms).
- useCaptions: If "yes", the caption of the image will be used in the control bar instead of numbers. If "no", the control bar will use numbers (i.e., 1 2 3 4). The default is "no".
- useTitles: If "yes", the title of the image will be displayed within the rotator. If "no", the image will not be displayed. The default is "yes".
- shuffle: not yet supported, but coming.
Once you've done this, you need to add items to the rotator. Here's how:
r.addItem (
new RotatorItem ("/images/rotator/image.jpg")
.setCaption ("My Image")
.setTitle ("My Image: © 2009 Me")
.setHREF ("http://www.example.com")
.setTransition ("fade")
);That's it. Again, like in the previous code, most of this is optional. What you must have is the "new RotatorItem ( url )" part; the caption, title, HREF, and transition are optional.
The Caption is the text that will appear in the image tooltip and in the control bar (if you set useCaptions to "yes"). Keep this short, since long captions will limit the number of links can be displayed in the control bar.
The Title is the text that will appear above the image if you've set useTitles to "yes". Otherwise it has no meaning.
The HREF is the location the image should link to when clicked. If it isn't set, the default HREF is "#", effectively reloading the page. When set to an off-site URL (prefixed with http or https), the link will automatically open a new window (or tab). If it is an on-site URL (not prefixed), the link will replace the current page.
And finally, the transition is the animation that will occur when showing this image. There are five transitions currently supported: "fade", "slideLeft", "slideRight", "slideTop", "slideBottom". Any other value is interpreted as a "fade".
Of course, one item isn't the point of the rotator, so add some more. Go on - I'll wait.
Okay - now that you've got more than one item, you have to tell the rotator to start:
r.start();
</SCRIPT>
And that's it. Your rotator will load its first image, and start cycling through the other images. Cool, eh? And if you've used the compressed javascript, the browser had to load only 5k of javascript, 1k of CSS, and 2.5k of images. Not too bad! (If you can enable gzip, do so - the savings are even better.)
Compatibility
I've tested this on the following browsers:
- Firefox 3.x
- Safari 3
- Google Chrome 1.x, 2.x
- Internet Explorer 7.x, 8.x
It should work in IE 6 if you take care of the transparent PNGs. Don't count on it working in anything less, and don't even think about it working in anything resembling NS 4, etc.
If you have any problems, just holler. I can't guarantee a quick response, but I'll try to assist wherever possible. I hope you enjoy it!
