radiant_scroller

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

Property	Default	Description
animateDuration	700	Integer Animation duration for the scrolling. The value is specified in milliseconds.
addPagination	false	Boolean Whether the scroller should have pagination (often displayed as small navigational dots) enabled.
captionsAnimateDuration	400	Integer Animation duration for the captions.
captionsAnimateEasingType	'swing'	Integer Easing type for the captions' animation. You can specify any other type of easing but bear in mind that jQuery has only swing and linear easings included. You will have to include jQueryUI's effects and easings plugin to get more.
cols	2	Integer How many (maximum) columns should the scroller have - basically this means how many elements will be visible at once horizontally (but if the scroller's width changes this value will also change).
delayDuration	500	Integer How long the scroller will wait after the resizing to initiate recalculation (this is done to ensure that the recalculation takes place only after the user has finished resizing the screen).
easingType	"swing"	String Easing type for the scrolling. You can specify any other type of easing but bear in mind that jQuery has only swing and linear easings included. You will have to include jQueryUI's effects and easings plugin to get more.
elementMargin	10	Integer Horizontal (left/right) margin for the scroller's elements. This value should correspond to the value that is provided in the styles.
elementWidth	200	Integer Width for the scroller's elements. This value should correspond to the value that is provided in the styles.
nextButtonText	""	String Text to be shown on the "next" button.
prevButtonText	""	String Text to be shown on the "previous" button.
rows	2	Integer How many rows should the scroller have.
useCaptions	false	Boolean Whether captions should be enabled. Check Captions section for more information.
useMouseWheel	false	Boolean Whether support for the mousewheel scrolling should be enabled. Please note that when this value is set to true, you should hook up MouseWheel plugin.

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:

Callback	Description
loaded	Fires when the scroller has finished loading and is ready. Scroller is being passed as an argument.
beforeMove	Fires before each scroller's moving animation. Scroller is being passed as an argument.
afterMove	Fires before after scroller's moving animation. Scroller is being passed as an argument.
lastPageReached	Fires when the scroller has finished loading and is ready. Scroller is being passed as an argument.
afterHidingCaption	Fires after the caption was hidden. Caption is being passed as an argument.
afterShowingCaption	Fires after the caption was showed. Caption is being passed as an argument.

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