RTLing jCarousel (jQuery Plugin)

jCarousel is a beautiful jQuery plugin. Personally it's one of my favorites! You can set up your caoursel up and running in just one line or two. Even theming it is easy. According to the project's page:

jCarousel is a jQuery plugin for controlling a list of items in horizontal or vertical order. The items, which can be static HTML content or loaded with (or without) AJAX, can be scrolled back and forth (with or without animation).

The only thing missing in this wonderful plugin is the RTL support. And in this tutorial, it won't miss it anymore.

1. Get the files

First of all, download the latest version of the jCarousel plugin: jcarousel.tar.gz or jcarousel.zip. Extract the downloaded folder. What we'll be working on in our RTLing process are the folders lib(where the JS is) and skins(where the CSS is)

2. Update the JavaScript plugin file

Open the lib folder to find the jquery library minified(latest version is 1.4.2 at the time of writing this tutorial), jqarousel library and the jqarousel library minified. We'll ignore the minified files and edit the jquery.jqarousel.js file(we'll minify it when we're done).

I won't bore you with the details of editing this file, but it's dead simple. It's all about spotting the explicitly declared "left" directional properties and make sure it can be dynamically set/configured.

We'll first start by adding an option to the defaults(line #53) called horizontalDirection and we'll set the default value to be 'ltr',

 
var defaults =
{ vertical: false,
 horizontalDirection:'ltr',
 //rest of default options

}

Then run a search for the string 'left' in the file. You'll get 3 results; Replace the first and third occurrences(lines #101 and #812) with the below:

(this.options.horizontalDirection=='rtl'?'right':'left')

}

Line #101 will be:

this.lt = !this.options.vertical ? (this.options.horizontalDirection=='rtl'?'right':'left'): 'top';

}

And line #812 will be:

 'float': (this.options.horizontalDirection=='rtl'?'right':'left'),

}

And in the second occurrence(line #682), replace the {'left':p} with:

(this.options.horizontalDirection=='rtl'?{'right': p}:{'left': p})

}

So it'll be:

 var o = !this.options.vertical ? (this.options.horizontalDirection=='rtl'?{'right': p}:{'left': p})  : {'top': p};

}

As it shows, we're simply checking for the option we added before setting the property explicitly(which was always a left).

To have CSS control on the new feature, we'll add a class to the container when its initialized named: jcarousel-direction-rtl or jcarousel-direction-ltr (depending on the horizontalDirection option). At line #163, add the below to JQ chain as below:

this.container.addClass(this.className('jcarousel-container'))
.addClass(!this.options.vertical?'jcarousel-direction-'+this.options.horizontalDirection:'')
.css({

}

And that's about it. Minify the file or pack it to use it on your live site.

3. RTL the skins

The plugins comes with two themes: tango and ie7. The modifications will be minor since they only target the previous and next buttons. The modifications below apply to both themes or any other theme with any theme_name.

The CSS modifications will be simply appending the below to the skin.css file:

.jcarousel-skin-theme_name .jcarousel-direction-rtl {direction:rtl;}
.jcarousel-skin-theme_name .jcarousel-direction-rtl .jcarousel-item-horizontal{ margin-right:0; margin-left:10px;}

/*horizontal buttons*/
.jcarousel-skin-theme_name .jcarousel-direction-rtl .jcarousel-next-horizontal{
background-image:url(prev-horizontal.png); right:auto; left:5px;
}
.jcarousel-skin-theme_name .jcarousel-direction-rtl .jcarousel-prev-horizontal{
background-image:url(next-horizontal.png); left:auto; right:5px;
}

}

As shown above, we're just overriding the CSS of the theme itself. Values may differ from theme to theme of course but the concept would be the same(Overriding the margin-right to be a margin-left is what matters)

As you've noticed too we're switching the background images of the next and previous buttons. This is to avoid having extra flipped images(we already have them )

...And you're done with the CSS

4. Use it!

Now to activate the RTL support, just use the new option we added:

jQuery(document).ready(function() {
  jQuery('#mycarousel').jcarousel({horizontalDirection:'rtl'});
});

}

5. Enjoy it :)

That's all :) The source code of the RTLed plugin and two themes are available to be downloaded and a demo is also available to see it in action(links below). I've tested this patch under Firefox, Chrome, Safari, IE7 and IE8. Should you face any bugs or trouble with it, please do add a comment with the issue below to be fixed ASAP.

Tags: