ctRotator – A Flexible Item/Image Rotator Script for jQuery
Download Source Code
Demonstration
jQuery Plugin Directory
I was taking part in developing an interesting web application - the Thank You Project. During which I made an item rotator script that swaps a list of messages in and out from the message board. I find the rotator script is very useful, so I decide to share it. To get an overview of what the script can do, you can check the demonstration page first.
Setting Up the Script
Making sure you have all the source files and desired dependencies. Download and unpack them to a folder of your choice.
Required Dependencies:
jQuery 1.2+
Optional Dependencies:
jQuery Tooltip plugin
Include the following files to the header section of your page. Make correction to the paths according to the location of your source files.
<link rel='stylesheet' href='src/jquery.ctrotator.css' type='text/css' media='all' /> <script type='text/javascript' src='lib/jquery-1.2.6.pack.js'></script> <script type='text/javascript' src='src/jquery.ctrotator.js'></script>
Building the Rotator
ctRotator is a very flexible in terms of customization. It offers several ways to build the rotator. For example, you can create the rotator from an manually created data source, a UL/OL list, an RSS feed, or a FlickR JSON feed. You can event create your own data source bridge to meet your special needs. In the following sections, I'll go over each one of them.
Build the Rotator from Manually Created Data Source
Data source is just an array of tuples in the following format:
<script type="text/javascript">
var dataSource = [
{title: 'test', url: 'http://thecodecentral.com', tip: 'Programmer's blog for programmers'},
{title: 'test2', url: 'http://thankyouproject.org', tip: 'Fill the World with Thanks'},
{title: 'test3', url: 'http://google.com', tip: 'Search Engine'},
{title: 'test4', url: 'http://yahoo.com', tip: 'La La La'}
];
</script>
Suppose you have above data source object, you can create the rotator by query and UL element and feed it with the data source:
<ul id="container"></ul>
<script type="text/javascript">
$('#container').ctRotator(dataSource, {
showCount:5,
speed:1000
});
</script>
showCount limits the number of items being showed, and speed control the rotation speed. Pretty self-explanatory.
Build the Rotator from an Exiting UL/OL element
Suppose you already have an UL or OL list, you can easily extra the data from it and feed it to the rotator. The source package contains a LI bridge, which can do this very task.
First, add bridge source to your page:
<link rel='stylesheet' href='src/jquery.ctrotator.css' type='text/css' media='all' /> <script type='text/javascript' src='lib/jquery-1.2.6.pack.js'></script> <script type='text/javascript' src='src/jquery.ctrotator.js'></script> <script type='text/javascript' src='src/jquery.ctrotator.bridge.li.js'></script>
And then parse the list and feed it to the rotator:
<ul id="list">
<li><a href="http://thecodecentral.com">Code Central</a></li>
<li><a href="http://google.com">Google</a></li>
... so on
</ul>
<script type="text/javascript">
var dataSource = new ctRotatorBridgeLi($('#list')).getDataSource();
$('#list').ctRotator(dataSource, {
showCount:5,
speed:1000
});
</script>
ctRotatorBridgeLi takes an jQuery object as parameter. Calling getDataSource() will return a formatted data source which can be consumed by the rotator.
Build the Rotator from a RSS feed
You can create a rotating list from a RSS feed. There a a few things you need to take into consideration for RSS. The first one is one network delay of reading the feed. Because of the delay, we have to make the creation process to be asynchronous (also the reason why we used a callback function here). The second one is security model of the browsers make it impossible to fetch data from another website without using a proxy. Thus I used a proxy in examples (take a look feedproxy.php from the source package).
Include the feed bridge code to your page:
<link rel='stylesheet' href='src/jquery.ctrotator.css' type='text/css' media='all' /> <script type='text/javascript' src='lib/jquery-1.2.6.pack.js'></script> <script type='text/javascript' src='src/jquery.ctrotator.js'></script> <script type='text/javascript' src='src/jquery.ctrotator.bridge.rss20.js'></script>
Create an rotator and put our rotator in a callback function:
var bridge = new ctRotatorBridgeRss20('http://thecodecentral.com/feed', function(dataSource){
$('#container').ctRotator(dataSource, {showCount:10});
});
bridge.getDataSource();
Nothing fancy here. ctRotatorBridgeRss20 takes two parameters: a feed URL and a callback function.
We first create and bridge object, and call getDataSource() on the bridge, and the bridge extract data from RSS feed. Once the extraction is done, the callback function is called, and the extracted data is passed as function parameter (dataSource in this case). We then create the rotator and feed it with the data source.
Build the Rotator from an Flickr JSON Feed
You can also create a rotating list from a Flickr feed. We are facing the similar problem to RSS feed, which is network delay, so asynchronous handling is required. However with JSONP (JSON with Padding), we can skip creating an proxy.
Include the following bridge code to your page:
<link rel='stylesheet' href='src/jquery.ctrotator.css' type='text/css' media='all' /> <script type='text/javascript' src='lib/jquery-1.2.6.pack.js'></script> <script type='text/javascript' src='src/jquery.ctrotator.js'></script> <script type='text/javascript' src='src/jquery.ctrotator.bridge.flickr.js'></script>
var bridge = new ctRotatorBridgeFlickR('http://api.flickr.com/services/feeds/photos_public.gne?format=json&jsoncallback=?', function(dataSource){
$('#container').ctRotator(dataSource, {
showCount:10,
speed: 1000,
itemRenderer:function(item){
return '<li class="ctrotator-item"><a href="' +
item.url+ '"><img src="' + item.image +
'" alt="' + item.title + '"/></a></li>';
}
});
});
bridge.getDataSource();
What we did above were:
1. create an bridge object which can process Flickr feed and make an usable data source for the rotator.
2. Pass the data source to the callback function.
3. Inside the callback function, we create our rotator object and feed it with the data soruce.
Notice that the itemRender parameter in above code. This is my attempt to make the rotator as flexible as possible. itemRender is a callback function, which returns the HTML code that used to render the rotator row. Since Flickr feed contains image, I made some minor modification to the default renderer (have a look the default renderer in the source code). The callback function has an item parameter, which is an tuple in the data source.
As you can see, this is very flexible. For example, if you don't like to use LI to wrap items in the list, you can change LI to DIV in the renderer. You can even define your own data source format, all you have to do is to update the renderer accordingly so the rotator can be rendered properly.
itemRenderer Examples
Render items in the list as DIV element:
$('#container').ctRotator(dataSource, {
itemRenderer: function(item){
return '<div class="rotator-item">' +
'<a href="' + item.url + '">' + item.title + '</a>' + item.image +
'</div>';
}
});
Mix with different options you can create some very interesting rotator. For example, changing showCount to 1, the script becomes an ad rotator. There are also a few more options you can play with. All possible options are documented in the next section.
Integration with jQuery Tooltip Plugin
jQuery Tooltip Plugin provides a very elegant way to display extra information when space is limited.
You can easily integrate jQuery Tooltip with ctRotator. First you need to include all the required files to your page:
<link rel='stylesheet' href='src/jquery.ctrotator.css' type='text/css' media='all' /> <link rel='stylesheet' href='lib/jquery.tooltip.css' type='text/css' media='all' /> <script type='text/javascript' src='lib/jquery-1.2.6.pack.js'></script> <script type='text/javascript' src='src/jquery.ctrotator.js'></script> <script type='text/javascript' src='lib/jquery.tooltip.pack.js'></script> <script type='text/javascript' src='lib/jquery.dimension.js'></script>
After that, set useTooltip option to true:
$('#container').ctRotator(dataSource, {
useTooltip: true,
tooltipOptions: {delay:500}
});
Tooltip uses "tip" field of the data source, so make sure that your data source have the "tip" field before feeding it to the rotator:
{title: 'tooltip test', url: 'http://thecodecentral.com', tip: 'tooltip description'},
Options Reference
Example: $('#container').ctRotator(dataSource, options};
Note: container typically is an UL element.
| Name | Default Value | Description |
|---|---|---|
| showCount | 5 | Number of items to show at any given time |
| speed | 6000 | duration of the swapping in milliseconds |
| fadeInSpeed | 750 | Item fade in speed in milliseconds |
| fadeOutSpeed | 250 | Item fade out speed in milliseconds |
| fadeEffect | true | Set to true will active fade effect |
| shuffle | false | If set to true, items will be displayed randomly |
| useTooltip | false | If set to true, the script will show a tooltip when mouse is hovered an item |
| itemRenderer | Please refer to the source code | Control how list item is rendered |
| tooltipOptions | N/A | You can use basically any options available for jQuery Tooltip: http://jquery.bassistance.de/tooltip/demo/ |
What's Next
More interesting posts ...
Leave a Comment
If you would like to make a comment, please fill out the form below.
If you want to post source code, please wrap it with <pre> and </pre>
Loading ...
This is awesome... thank you very much.
One question, how do I specify the actual url that I want (trying to pull in my own flickr photos only)??
Thanks!
You need to locate the RSS/Atom feed. If you are using Firefox, you'll see a RSS icon on the right side of the address bar.
Go to the Feed URL, change the format to JSON. For example:
http://api.flickr.com/services/feeds/photoset.gne?set=46241&nsid=93566774@N00&lang=en-us&format=rss_200
to
http://api.flickr.com/services/feeds/photoset.gne?set=46241&nsid=93566774@N00&lang=en-us&format=json
Or you can just use the RSS bridge (ctRotatorBridgeRss20 ) to pull the photos directly.
Hi, I suppose in example "Build the Rotator from a RSS feed" you mean instead of ait? :-)
Damn forgot the pre
again:
src='src/jquery.ctrotator.bridge.rss20.js'
instead of
src='src/jquery.ctrotator.bridge.li.js'
OK, cool... go the images coming in from Flickr, but how do I tell it to grab the medium size photos instead of the thumbnails?
Thanks again for all your help!
??????? ??? ????????? ?? DRUGREVENUE ? ???????? ?????? ? 3000 ????????, ???????
heya sweet script! Just wondering if you have an easy way to trigger a pause when mouseover event is fired?
@WebPain
Thank you for pointing this out. I updated the script path.
@Jon
You would have to modify the script. You can create a flag and set it true when mouse is hovered the desired element, and set it to false when mouse is out. In updateRotation function of jquery.ctrotator.js, do something like this:
var mFlag. function updateRotation(rotator, container, options){ if(mFlag){ return; } var item = rotator.gotoNext();Haven't tested it, but hopefully it gives you a pointer.
hi there, thanks for that it appears to pause it fine, but for whatever reason it doesnt continue with the mouse out. I will dig deeper on this one but cheers for the pointer.
Another question if i may the RSS feed works perfectly in FireFox but i cant get it working in IE at all. (using IE 7 here) just wondering if you know of any IE quirks at all?
just thought i would update in case others run into similar troubles:
Pause on mouse over: i needed to add the setTimeout bit..
if(mFlag == true){
setTimeout(function(){updateRotation(rotator, container, options)}, options.speed);
return;
}
as for the RSS not working in IE. it was a drupal issue not returning a valid content type for the feed and as such it was being ignored. updated the content type in the node.module script and it fixed the issue.
Hi there, excellent script!
Further to Todd's last question, what is the correct way of controlling the image size that's pulled from Flickr?
The default seems to obtain the 'Small' size, and I'd like to retrieve something larger (if possible).
Thanks.
Is there an easy way to make the speed random between a certain set of parameters ie. Random speed between 3000 and 10000?
I'm basically adding this to a recent forum posts section and am wanting it to appear like posts are being added as it reveals a new post. I just think it might be more realistic if I had them appearing at random intervals.
This is great. Almost what I was looking for. Just wanted to ask: is there anyway to change the speed to be on page reload instead?
Hi,
really interesting tool.
I would to know if it is possible to apply to a table where the lines are a Col1Col2.
tr td Col1 /td td Col2 /td /tr
@Jon
Could you post the other mods required to make the mouseover pause work 'You can create a flag and set it true when mouse is hovered the desired element, and set it to false when mouse is out'
Ta
[...] cRotator, ancora mai provato (esempi) [...]
Hey there!!!
Thats really awesome work you have done there.
Thanks a lot for that.
I had used your code in one of the webpages that I built. I was referencing the way to add the files and the code into the webpage. But now its not there, the way it was earlier. Can you please put it back so that I can get the exact way and code to put "Build Rotator from Flickr Feed" into a webpage.
I'll be very grateful to you, if you can put it back soon.
Thanks in advance.
hi,
Very cool stuff and i like it, but i have a problem , I am trying to make the same file like
http://api.flickr.com/services/feeds/photos_public.gne?format=json&jsoncallback=?
on my server with .php and it's writing out the result
and when i put it here
new ctRotatorBridgeFlickr('http://www.myurl.com/script.php', function(dataSource){
the script is not working,I have checked all links and they are correct. If someone have any idea how to make it work ?
Please help
Best regards
hey .
how can i make it to start rotating when the mouse is on the image, and to stop rotating when is off the image?
thanks in advance
Hey,
I've written a Twitter bridge for this as well, so you can rotate tweets from an RSS search from search.twitter.com.
I also need it to refresh the data periodically, not just keep rotating the same items. Is there anyway to do this?
Thanks
function ctRotatorBridgeTwitter(url, readyCallback) {
this.url = url;
this.readyCallback = readyCallback;
}
ctRotatorBridgeTwitter.prototype =
{
getDataSource: function()
{
var readyCallback = this.readyCallback;
var dataSource = [];
$.get(this.url, {}, function(data)
{
$(data).find('channel item').each(function()
{
var e = $(this);
dataSource.push(
{
title: e.find('title').text(),
url: e.find('link').text(),
image: e.find('google\\:image_link').eq(0).text()
});
});
readyCallback(dataSource);
}, 'xml');
return dataSource;
}
};
Hello
How can I stop rotating?
I’ll try applying these scripts. Thanks.
You can stop rotating simply by altering the script and looking at about line 50. You're looking for the call to updateRotation. You'll want to put in a simple condition. I basically said if it's 0, don't rotate. Why would we want to rotate in rapid fire anyway? Perhaps this could be included in the next release?
if(options.speed > 0) {
updateRotation(rotator, container, options);
}
Why? Well because it's quite handy to not have it rotate...and then in the callback function where it displays the list of photos, count the length of the json object (feed from datasource)...So say we do:
var totalImages = dataSource.length;
Now in the options object we specify to the rotator we can say:
$('#flickr').ctRotator(dataSource, {
showCount: totalImages,
speed: 0,
...
That will then show all the images in the feed and not rotate them.
With a little creativity we can change the output in the itemRenderer and return some id's in those anchor links. Then take jQuery and handle events for clicking those and instead of going to the image make it bring up a lightbox or appear in another area on the page, etc.
This very quickly turns the rotator plugin here into a very customizable gallery plugin as well.
I like how it's a very minimal script -- many other scripts I've seen for galleries are way too bloated. This is much better. It also leaves things client side. "Mash-up" away for little hit to your server.
My only request (and I haven't looked at the script long enough to figure it out) is that there was an event listener to updateRotation()... So I can have a "next" and ultimately "prev" link to move the list. That would mean the rotation needs to go in reverse too, which would be more alteration...but specified in the options again by perhaps "direction: forward" or "direction: reverse".
That would be really nice. Then it's essentially exactly the same, but completely flexible to serve as originally intended, but also as a much more complex gallery (with some elbow grease).
Thanks for writing this script!
This is a great script and just what I needed for a WordPress template I am working on.
I have another project however wherein I am having an issue using images in an existing . Any suggestions?
[...] HTML UL/OL list, RSS feed, Flickr feed. More data sources can be supported with custom bridges. Web Site Demo Download Share and [...]
When using jQuery 1.2.6, things are fine, but not with JQuery 1.3.2 where the rotator causes screen disturbance or flickering of the footer at the bottom of the page. This happens only when the page is scrolled to the bottom completely, and both the footer and rotator are visible.
I would be thankful for a solution or an update
Hi again,
I tried to use the "itemRenderer" parameter, but I didn't have success.
The item.url, item.title works well, but the item.image is always undefined.
My source code:
$(document).ready(function(){
var dataSource = new ctRotatorBridgeLi($('#areaAuxiliar #listaEmpresasConveniadas ul')).getDataSource();
$('#areaAuxiliar #listaEmpresasConveniadas ul').ctRotator(dataSource, {
showCount: 3,
speed: 1000,
itemRenderer: function(item){
return '' + item.title + ' - ' + item.image + '';
}
});
});
<ul>
<li><a href="/Teste/"><img src="imagens/___empresa1.gif" width="81" height="46" />Empresa 1</a></li>
<li><a href="/Teste/"><img src="imagens/___empresa2.gif" width="81" height="47" />Empresa 2</a></li>
<li><a href="/Teste/"><img src="imagens/___empresa3.gif" width="84" height="44" />Empresa 3</a></li>
</ul>
I need help, please.
Is there a way to use this with sifr? I tried adding a callback function and the rotator is working, but not the font replacement.
I would like to know how can I call php data sources, recordsets in dreamweaver using this script.