jQuery Adventures: Permalinking and Keyboard Navigation for EasyRotator

by Nathan Rohler

Two features that are occasionally requested for EasyRotator are permalinking and keyboard navigation. (In case you're unfamiliar with the term, permalinking in this context means the ability to link directly to a specific slide within a rotator.) Both of these features can easily be implemented by adding some jQuery code to your page, and we'll cover the process in this article.

An Example

Let's first look at the final effect. First of all, you can use the left and right arrow keys to navigate this slider: 

Additionally, try clicking on one of the following links – when the page reloads, the rotator will jump directly to that photo.

Butterfly   Purple   Orange   Insect

The Code: Permalinking

To add permalink support to your page, add the following code snippet just before the closing </body> tag:

<script type="text/javascript">
window['er_$144'] && er_$144(function($){
    setTimeout(function(){
        $.extend({getUrlVars:function(){var a=[],hash;var b=window.location.href.slice(window.location.href.indexOf('?')+1).split('&');for(var i=0;i<b.length;i++){hash=b[i].split('=');a.push(hash[0]);a[hash[0]]=hash[1]}return a},getUrlVar:function(a){return $.getUrlVars()[a]}});
        var er_row = Number($.getUrlVar('er_row') || '0');
        var er_col = Number($.getUrlVar('er_col') || '0');
        if (er_row != 0)
        {
            $('div.dwuserEasyRotator').trigger('er_setRow', {id:er_row});
        }
        if (er_col != 0)
        {
            setTimeout(function(){
                $('div.dwuserEasyRotator').trigger('er_setCol', {id:er_col});
            }, er_row != 0 ? 1000 : 0);
        }
    }, 100);
});
</script>

Then, to link to a specific photo in the rotator, link to that rotator's page using er_col in the querystring. The er_col value should be the zero-base numeric index of the slide. For example, if you want to link to the third slide (index 2) in the rotator in gallery.html, use the following link:

gallery.html?er_col=2

When the gallery.html page loads, the rotator will jump to the third slide.

If your rotator has multiple image categories, you can link to a specific category via the er_row parameter. As with er_col, er_row should be the zero-base index of the category. Building on our previous example, let's suppose you want to link to the third photo in the second category. Here's the link you would use:

gallery.html?er_row=1&er_col=2

The Technical Details

After a short delay to allow the rotator to actually initialize (via the setTimeout function), we define a getUrlVar function to allow for retrieving URL variables. Then, we check to see if er_row and/or er_col have been defined. These variables represent a specific category and slide in that category respectively. We fall back to 0 (the first slide and category) as the default values.

If the requested category isn't the first one, we trigger the er_setRow event, passing the requested numeric ID. If the requested slide isn't the first one, we also trigger the er_setCol event to jump to that slide. If a non-default category was requested, we wait for a second (again with setTimeout) before jumping to the slide in that row. This allows for the category transition to complete before the slide is changed.

If you'd like to learn more about the basics of JavaScript and jQuery as used in this code, see books #4 and 5 in Keith's article, 7 Free eBooks that Should Line Every Web Professional's Digital Bookshelf.

The Code: Keyboard Navigation

To add keyboard navigation via the arrow keys, we will be listening for key presses then triggering the er_prev and er_next events to move back and forward respectively. Key events are easily managed in jQuery by using the keydown and/or keyup event binding methods; we'll use keyup for our handler.

To add this functionality, add the following JavaScript snippet to your page, again just before the closing </body> tag:

<script type="text/javascript">
window['er_$144'] && er_$144(function($){
    $('body').keyup(function(event){
        if (event.which == 37)
            $('div.dwuserEasyRotator').trigger('er_prev', {noLoop:true});
        else if (event.which == 39)
            $('div.dwuserEasyRotator').trigger('er_next', {noLoop:true});
    });
});
</script>

The Technical Details

In the keyup handler, we use the event.which property to check the key that was pressed. Key code 37 corresponds to the left arrow and 39 to the right arrow. When triggering the events, we use true with the optional noLoop configuration parameter to prevent the arrow keys from causing looping at the end or beginning of a given category. You can instead use noLoop:false if you want to allow for going forward from the last to first slide and backward from the first to last slide.

Conclusion

In this article we've looked at two simple snippets built with JavaScript and the jQuery library that add additional functionality to EasyRotator – permalinking and keyboard arrow navigation. I hope that you'll find this code useful for enhancing EasyRotator, and I also hope that I've whetted your appetite to learn more about jQuery techniques. The jQuery Fundamentals eBook I mentioned earlier is a great place to start learning.