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.
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
- jQuery 1.7.0+
- MouseWheel plugin (only if you want to provide mousewheel support)
Installation and usage
-
Hook up required files
-
Hook up
jquery.radiant_scroller.min.js
andjquery.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
andelementMargin
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 thecols
androws
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 thecurrent-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 totrue
- Adjust
captionsAnimateDuration
andcaptionsAnimateEasingType
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 forwardradiantScroller('prev')
- scroll one page backwardradiantScroller(<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 callmy_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) 2016 Ilya Bodrov