jQuery RadiantScroller plugin

This is a jQuery plugin that allows to create responsive scrollers (carousels) with grid and simple horizontal layouts. RadiantScroller can be cuztomized with the variety of options. API methods and callbacks are available. Elements may also have animated captions.

The current version is 0.1.1 (05/12/2014).

Documentation and demos can also be found at http://www.radiant-wind.com/plugins/radiant_scroller.

Demos

Images were taken from FreeImages.

• Basic scroller with 3x2 grid with no mousewheel support and no pagination
• Scroller with 3x2 grid with mousewheel support and pagination
• Scroller with one column and two rows
• Basic Radiant Scroller's API (demonstrates that you can scroll by specified number of pages or directly to the page with specified number)
• Radiant Scroller with captions (also demonstrates how to add jQueryUI's easings)
• Radiant Scroller's callback API

Requirements

1. jQuery 1.7.0+
2. MouseWheel plugin (only if you want to provide mousewheel support)

Installation and usage

• Hook up required files

• Hook up jquery.radiant_scroller.min.js and jquery.radiant_scroller.css

• Set up basic layout for the scroller:

<div id="your_scroller_id">
    <div class="scroller-el"><img src="image1.jpg" alt="Image1" /></div>
    <div class="scroller-el"><img src="image2.jpg" alt="Image2" /></div>
    <div class="scroller-el"><img src="image3.jpg" alt="Image3" /></div>
</div>

The scroller-el class is required.

• Set up basic styling. In fact, only specifying margins and dimensions for the elements in the scroller is required. This can be done like:

.radiant_scroller .scroller-el {
    width: 200px;
    height: 200px;
    margin-right: 10px;
    margin-bottom: 10px; /* This is optional but recommended - otherwise your images will have no horizontal spacing */
}

• Initialize the scroller. The values for elementWidth and elementMargin should be the same as your specified in the previous step otherwise the scroller's grid will be built incorrectly. You will probably want to specify scroller's grid dimensions with the cols and rows attributes (the default is 2x2 grid). All available options are listed in the "Options" section.

$(document).ready(function() {
    $('#myScroller').radiantScroller({
        elementWidth: 200,
        elementMargin: 10,
        cols: 3,
        rows: 3
    });
});

• Style your scroller as needed (check Styling section and demos for more information).

Options

Styling

jquery.radiant_scroller.css provides only required styles so you have to write some more styles to make the scroller look nice. When the scroller is initialized the following layout is being built (pagination will not be shown until you set addPagination option to true):

<div class="radiant_scroller">
    <div class="radiant_scroller_wrapper">
        <div id="myScroller">
            <div class="radiant_scroller_row">
                <div class="scroller-el"><img src="image1.jpg" alt="Image1" /></div>
                <div class="scroller-el"><img src="image2.jpg" alt="Image2" /></div>
            </div>
            <div class="radiant_scroller_row">
                <div class="scroller-el"><img src="image3.jpg" alt="Image3" /></div>
                <div class="scroller-el"><img src="image4.jpg" alt="Image4" /></div>
            </div>
        </div>
    </div>
    <div class="radiant-pagination">
        <div class="radiant-page current-page" data-page="1"></div>
        <div class="radiant-page" data-page="2"></div>
    </div>
    <div class="radiant-navigation">
        <div class="radiant-prev"></div>
        <div class="radiant-next"></div>
    </div>
</div>

All elements except for #myScroller and .scroller-el are added dynamically.

• .radiant-pagination contains navigational pages; the active page has the current-page class, so you can style it differently.
• .radiant-navigation contains next and previous buttons. .radiant-prev and .radiant-next are positioned absolutely (and main wrapper .radiant_scroller is positioned relatively) so you can adjust its position as necessary.

See demos to get the basic idea how the scroller can be styled.

Captions

Starting from version 0.1.0 scroller elements may have animated captions. To use them few things have to be done:

• Set useCaptions option to true
• Adjust captionsAnimateDuration and captionsAnimateEasingType if needed
• Add title attribute to your elements like this:

<div id="your_scroller_id">
    <div class="scroller-el"><img src="image1.jpg" alt="Image1" title="This is a caption" /></div>
    <div class="scroller-el"><img src="image2.jpg" alt="Image2" title="Another caption" /></div>
</div>

• Enjoy the captions!

By default captions appear at the bottom of the element with white centered text and black semi-opaque background. If you wish to style it differently, assign your styles to .radiant-caption class.

API

To get access to the RadiantScroller's API you should initialize your scroller like this:

var my_scroller = $('#myScroller').radiantScroller({...});

And then you can manage your scroller by calling radiantScroller on the my_scroller variable and passing it an API action to invoke. Currently there are a few API methods available:

• radiantScroller('next') - scroll one page forward
• radiantScroller('prev') - scroll one page backward
• radiantScroller(<number>) - scroll to a page with the specified number. Page numeration starts from 1. If a non-existent page is provided nothing happens.
• radiantScroller('by', <number>) - scroll by a specified number of pages. For example if you are at the 1st page and call my_scroller.radiantScroller('by', 2) you scroll by 2 pages and end up at the 3rd page.

To see them all in action open this demo. More methods coming soon.

Callbacks

Starting from version 0.1.0 the following callbacks are available:

For Rails developers

jquery-radiantscroller-rails gem provides an easy way to integrate Radiant Scroller into your Rails project.

License

This plugin is licensed under the MIT License.

Copyright (c) 2014 Ilya Bodrov