QScroller is a Mootools class (available both for version 1.11 and 1.2 of the framework) you can use in your scripts to add scrolling text, scrolling images or a combination of both, to your website. Both horizontal and vertical scrolling are supported and all effects and transitions offered by Mootools are available.
QScroller is an ideal solution to create simple slideshows, product showcases, publish latest news or other important messages that must attract your visitors attention.
The quickest way to learn how to use the class is with some practical examples.
Complete sources of all these examples are included in the package. Only the most relevant parts will be commented here.
Simple horizontal scroller
Simple slides made by a single line of text are horizontally scrolled inside a fixed width box.
HTML (head)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Test Mootools QScroller</title>
<link href="/qscroller.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="/mootools.js"></script>
<script type="text/javascript" src="/qscroller.js"></script>
</head>
A valid XHTML DocType is required.
- mootools.js contains the complete Mootools library.
- qscroller.js contains the QScroller class.
- qscroller.css contains css rules to control the appearance of slides and container.
HTML (body)
<div id="qscroller1"></div>
<div class="hide">
<div class="qslide">
Simple text scroller. Put anything you want here
</div>
<div class="qslide">
use <strong>Html</strong> <em>tags</em> to
<u>format</u> text
</div>
<div class="qslide">
even <a href="#">links</a> are allowed
<i>obviously</i> :)
</div>
<div class="qslide">
Mouse over to stop animation
</div>
<div class="qslide">
Mouse out to resume animation
</div>
</div>
#qscroller1 is the DIV inside which the animation occurs. Scrolling elements (DIVs of class qslide) are positioned out of the visible part of the screen (see css rules for DIV of class hide in qscroller.css below).
<script type="text/javascript">
<!--
window.addEvent('domready', function() {
var opt = {
duration: 3000,
delay: 1000,
auto:true,
onMouseEnter: function(){this.stop();},
onMouseLeave: function(){this.play();}
}
var scroller = new QScroller('qscroller1',opt);
scroller.load();
});
//-->
</script>
QScroller class is created in a domready event, as we need to be sure it can access DOM elements, and initialized with ID of animation container and an object containing the following configuration options.
- duration (default 3000) - duration of transition effect in milliseconds. Lower is the value, faster is the animation.
- delay (default 1000) - the number of milliseconds to pause between slides. Setting this option only makes sense when autoplay is on (see below).
- auto (default false) - autoplay, if true the animation automatically starts.
- onMouseEnter - this event is fired when the mouse pointer enters the container. In this example we pause the animation.
- onMouseLeave - this event is fired when the mouse pointer leaves the container. In this example we resume the animation.
scroller.load() loads the first slide and, if auto is true (as in this example), starts the animation.
CSS (in qscroller.css)
.hide {
visibility: hidden;
position: absolute;
top: -400px;
}
#qscroller1 {
width:350px;
height:21px;
border:1px solid #c0c0c0;
background:#f0f0f0;
}
.qslide {
background: #f0f0f0;
font-size: 10pt;
padding: 3px;
}
Not a lot to say. As you can see width, height, style of animation container and scrolling elements (slides) are controlled via css rules.
The class hide is used to put the scrolling elements out of view. It's up to the class code reading each slide's content from the document, injecting it inside the container and starting the animation effect.
Horizontal scroller with text and images
Simple product showcase with text and images. Scrolling is controlled through navigation links.
Product1
Simple example of product showcase. Use arrows at the bottom to scroll.
Product2
Product description here.
Product3
Product description here.HTML (head)
Same as first example.
HTML (body)
<div id="qscroller2" class="qscroller"></div>
<div class="qscroller2-nav">
<div>
<a id="go-prev" href="javascript:void(0)"><<</a>
<a id="go-next" href="javascript:void(0)">>></a>
</div>
</div>
Note the navigation bar (class qscroller2-nav). Links IDs (go-prev, go-next) will be passed to the class.
<div class="hide">
<div class="qslide2">
<img src="/images/product1.jpg" alt="" />
<h1>Product1</h1>Simple example of product showcase.
Use arrows at the bottom to scroll.
</div>
<div class="qslide2">
<img src="/images/product2.jpg" alt="" />
<h1>Product2</h1>Product description here.
</div>
<div class="qslide2">
<img src="/images/product3.jpg" alt="" />
<h1>Product3</h1>Product description here.
</div>
</div>
Scrolling elements (DIVs of class qslide2) are embedded in a DIV of class hide to put them out of the screen exactly as in the first example.
<script type="text/javascript">
<!--
window.addEvent('domready', function() {
var opt = {
slides: 'qslide2',
duration: 1500,
buttons: {next:'go-next',prev:'go-prev'},
transition: Fx.Transitions.Quint.easeOut
}
var scroller = new QScroller('qscroller2',opt);
scroller.load();
});
//-->
</script>
Class options
- slides - class of DIVs containing scrolling elements. This option has a default value of qslide, this is the reason because we've not explicitly set it in the first example.
- duration - see first example.
- buttons - IDs of links used to scroll through slides.
- transition: transition effect. See a list of possible values here and feel free to experiment with different transitions. Default Fx.Transitions.linear
CSS (in qscroller.css)
#qscroller2 {
width:320px;
height:154px;
border:1px solid #c0c0c0;
background:#fff;
}
.qscroller2-nav {
font-size: 9pt;
width:320px;
height: 15px;
background:#f0f0f0;
border:1px solid #c0c0c0;
}
.qscroller2-nav a {
text-decoration: none;
}
.qscroller2-nav div {
float: right;
}
.qslide2 img {
float: left;
padding: 1px;
border: 1px solid #00ffff;
margin: 3px 15px 0 3px;
}
.qslide2 h1 {
margin:0 0 5px;
font-size: 110%;
color: #16387c;
}
As expected navigation bar and links as well as slides (class qslide2) appearance are entirely controlled through css rules.
Vertical scroller with images
QScroller can be used to create simple slideshows. In this examples some images are scrolled vertically. When you move the mouse pointer over the image a navigation bar with play, stop, next and previous buttons is showed.
HTML (head)
Same as first example.
HTML (body)
<div id="qscroller3" class="qscroller">
<div id="qscroller3-nav">
<div>
<a id="go-prev2" href="javascript:void(0)">
<img src="/prev.gif" alt="previous" />
</a>
<a id="play" href="javascript:void(0)">
<img src="/play.gif" alt="play" />
</a>
<a id="stop" href="javascript:void(0)">
<img src="/stop.gif" alt="stop" />
</a>
<a id="go-next2" href="javascript:void(0)">
<img src="/next.gif" alt="next" />
</a>
</div>
</div>
</div>
<div class="hide">
<div class="qslide3">
<img src="/images/flower1.jpg" alt="" />
</div>
<div class="qslide3">
<img src="/images/flower2.jpg" alt="" />
</div>
<div class="qslide3">
<img src="/images/flower3.jpg" alt="" />
</div>
<div class="qslide3">
<img src="/images/flower4.jpg" alt="" />
</div>
</div>
<script type="text/javascript">
<!--
window.addEvent('domready', function() {
var opt = {
slides: 'qslide3',
duration: 2000,
delay: 1000,
auto:false,
direction: 'v',
transition:Fx.Transitions.Quart.easeIn,
buttons: {next:'go-next2',prev:'go-prev2',play:'play',stop:'stop'},
onMouseEnter: function(){
var el = $('qscroller3-nav');
el.effects({
duration:1000,
transition: Fx.Transitions.linear
}).start({
bottom:[-el.getStyle('height').toInt(),-1],
opacity:[0.8,0.8]
});
},
onMouseLeave: function(){
var el = $('qscroller3-nav');
el.effects({
duration:1000,
transition: Fx.Transitions.linear
}).start({
bottom:[-1,-el.getStyle('height').toInt()],
opacity:[0.8,0.8]
});
}
}
var scroller = new QScroller('qscroller3',opt);
scroller.load();
});
//-->
</script>
Class options
We have explained them all except direction. Possible values are v = vertical scrolling; h (default) = horizontal scrolling.
Code in event handlers (onMouseEnter, onMouseLeave) scrolls the bar with navigation links up or down when the mouse pointer enters or leaves the container area.
This code is more complicated than in previous examples, some familiarity with Mootools framework is needed to fully understand it.
CSS (in qscroller.css)
#qscroller3 {
position: relative;
width:205px;
height:137px;
}
#qscroller3-nav {
position:absolute;
height: 18px;
visibility: hidden;
background: #f0f0f0;
z-index: 1;
width: 100%;
}
#qscroller3-nav a {
text-decoration: none;
}
#qscroller3-nav div {
float: right;
}
#qscroller3-nav img {
border: none;
padding: 3px 2px 0;
}
.qslide3 img {
border: 1px solid #fff;
} Note that the navigation bar (#qscroller-nav) is hidden in the css as it's made visible by the script (onMouseEnter event handler)
