jQuery.SerialScroll 1.2.2 released

Enhancements

• Removed the check that avoids re-scrolling to the same index, this might be desirable sometimes.
• The settings object is exposed in the onBefore as the this.

Links

• Main Post
• Github Repo
• Demo
• jQuery.ScrollTo
• jQuery.ScrollTo's demo
• Changelog

Downloads

• jQuery.SerialScroll 1.2.2 Source(to learn or test)
• jQuery.SerialScroll 1.2.2 Minified(recommended)
• jQuery.ScrollTo 1.4.3.1 Source(to learn or test)
• jQuery.ScrollTo 1.4.3.1 Minified(recommended)

Doctorate on jQuery.SerialScroll

Introduction

After replying to a large amount of comments and emails about jQuery.SerialScroll, I decided to comment some more about this plugin, also to publish some snippets, to achieve commonly desired effects or behaviors.
This should save you (and me :)) some time. It might also show you some additions, that you haven't considered.
I'll also try to show some more model calls to the plugin, so you can unattach yourself from those in the demo.

A little bit of theory

Before the snippets, I'll go through the basics, to refresh your mind.

Calls to the plugin

It can be done on two different kind of elements

• Element to be scrolled: This is what you normally do when you want one single instance of SerialScroll in a page.

  $('#pane').serialScroll({
  //...
  });
  

• Container: You might want to create many "SerialScrolls" in the page, you don't need to call it many times, just put the option 'target' to work.

  $('div.container').serialScroll({
  //...
  target:'div.pane',
  //...
  });
  

  This will allow you to have many divs with class container, which contain a scrollable div with class pane. They don't need to be divs.
  When doing this, the selectos for the arrows also become relative to the container, instead of absolute.
• Global call: If by chance, you want to scroll the window, you'll need to use this approach.
  

  $.serialScroll({
  //...
  });
  

  If, for some reason, you need to retrieve this implicit element, call:

  $.scrollTo.window();

  This will return you the element, don't use window or document.

onBefore

This setting, which is a callback, will empower some snippets, so you better learn about it.

$('div.container').serialScroll({
//...
onBefore:function( e, elem, $pane, $items, pos ){
//...
},
//...
});

Note that:

• The 'this' is the element that triggered the event.
• e is the event object.
• elem is the element we'll be scrolling to.
• $pane is the element being scrolled.
• $items is the items collection at this moment.
• pos is the position of elem in the collection.
• if it returns false, the event will be ignored.
• Those arguments with $ are jqueryfied.

The onAfter, only receives 'elem' as the first argument, and the 'this' is the element being scrolled ($pane but not jqueryfied).

The snippets

Now, what you really want, the code required to do all those fancy things, that the plugin doesn't do natively.
One note, all the snippets are wrapped with a document ready and they use symbolic ids. Needless to say, you don't need to copy the ids, or even USE ids.
Only the relevant settings are specified, so you will see "..." reminding that it's incomplete code.
You configure the selectors and the rest of the settings, according to your needs.

• Use constant auto-scrolling. getnew
• Hide the arrows when the limits are met. get
• Stop the auto scrolling on hover. get
• Scroll from right to left (or bottom to top). get
• Manipulate the widget using the keyboard. get
• Generate a pager based on the items. get

Concluding

I hope this helped and saved you some time, I also hope you learnt something new.
I plan to add more snippets as they come up from requests.
If you have any doubt, don't hesitate to ask.

Update 6/25/08

Added the constant scrolling snippet

jQuery.SerialScroll 1.1 released

I added a major release of jQuery.SerialScroll. It doesn't have that many changes, but I really feel it made one step ahead.

Optimizations

• The animation is skipped if a bad position was received or it's the same as the actual. Saving some overhead.

Changes

• Changed the licensing from GPL to GPL+MIT.

Features

• The plugin binds 3 events to the container to allow external manipulation. They are clearly explained in the main post, please check it.
• Added 2 more arguments to the onBefore callback: actual item collection, index of the actual item in the collection.
• Added option 'interval', can be a number specifying the amount of milliseconds for autoscrolling.

I upgraded the main post and it has extensive and detailed documentation. Also added some more text and options to the demo.

Links

• Main Post
• Github Repo
• Demo
• jQuery.ScrollTo
• jQuery.ScrollTo's demo
• Changelog

Downloads

• jQuery.SerialScroll 1.2.2 Source(to learn or test)
• jQuery.SerialScroll 1.2.2 Minified(recommended)
• jQuery.ScrollTo 1.4.3.1 Source(to learn or test)
• jQuery.ScrollTo 1.4.3.1 Minified(recommended)

I really advice using the minified versions. The code is optimized for those releases. Source versions should only serve to learn.

jQuery.SerialScroll

Notice

I've pretty much stopped updating this blog, but the plugin development is still on-going. You can find the link to the Github project page at the bottom of the article.

Introduction

This plugin allows you to easily animate any series of elements, by sequentially scrolling them. It uses jQuery.ScrollTo to achieve the scrolling animation. It is a very unrestricted plugin, that lets you customize pretty much everything from outside. You can use horizontal or vertical scroll, also combined.

What's it for ?

jQuery.SerialScroll doesn't have one definite purpose. It's generic and adaptable. You can certainly use it as a screen slider. That is, to sequentially navigate a group of screens.
This plugin can also animate a text scroller in no time.
It can definitely handle slideshows, the high customizability of the scrolling effect lets you create beautiful animations.
You can even build an automatic news ticker!
Three of these uses are exemplified in the demo.
Remember, it's not restricted to these situations. It will take care of any collection of html elements that you want to scroll consecutively.

Settings and customization

jQuery.SerialScroll gives you access to a lot of options.
These are:

• target

  The element to scroll, it's relative to the matched element.
  If you don't specify this option, the scrolled element is the one you called serialScroll on.

• event

  on which event to react (click by default).

• start

  first element of the series (zero-based index, 0 by default).

• step

  how many elements to scroll each time. Use a negative number to go on the other way.

• lock

  if true(default), the plugin will ignore events if already animating. Then animations can't be queued.

• cycle

  if true, the first element will be shown after going over the last, and the other way around.

• stop

  if true, the plugin will stop any previous animations of the element, to avoid queuing.

• force

  if true, an initial scroll will be forced on start.

• jump

  if true, the specified event can be triggered on the items, and the container will scroll to them.

• items

  selector to the items(relative to the scrolled element).

• prev

  (optional)selector to the 'previous' button.

• next

  (optional)selector to the 'next' button.

• lazy

  if true, the items are collected each time, allowing dynamic content(AJAX, AHAH, jQuery manipulation, etc).

• interval

  If you specify a number, the plugin will add auto scrolling with that interval.

• constant

  Should the speed remain constant, no matter how many items we scroll at once ? (true by default).

• navigation

  Optionally, a selector to a group of elements, that allow scrolling to specific elements by index. Can be less than the amount of items.

• excludenew

  If you want the plugin, to stop scrolling before the actual last element, set this to a number, and that amount of items is ignored counting from the end.
  This is useful if you show many items simultaneously, in that case, you probably want to set this option to the amount of visible items - 1.

• onBefore

  A function to be called before each scrolling. It receives the following arguments: event object, targeted element, element to be scrolled, collection of items and position of the targeted element in the collection.
  The scope(this) will point to the element that got the event. If the function returns false, the event is ignored.

Also, you can use jQuery.ScrollTo's settings!
Check its demo to see all of them.

The option 'target'

This option is a new addition, included since 1.2.0.
Before, you needed to call the plugin once for each scrolled element.
When this option is specified, the matched elements are no longer the scrolled elements, but a container.
In this case, the selectors of prev, next, navigation and target will be relative to this container, allowing you to call SerialScroll on many elements at once.

External manipulation, event triggering

jQuery.SerialScroll automatically binds 3 events to the containers.
These are:

• prev.serialScroll

  Scrolls to the previous element.

• next.serialScroll

  Scrolls to the next element.

• goto.serialScroll

  Scrolls to the specified index, starts with 0.

• start.serialScroll

  (Re)starts autoscrolling.

• stop.serialScroll

  Stops the autoscrolling.

• notify.serialScroll

  Updates the active item.

This looks confusing, but it's not. You use it like this:

$(container).trigger( 'prev' );

$(container).trigger( 'next' );

$(container).trigger( 'goto', [ 3 ] );

$(container).trigger( 'start' );

$(container).trigger( 'stop' );

$(container).trigger( 'notify', [ 4 ] );

'notify' also accepts a DOM element(item), or any of its descendants.
$(container) is the element that gets scrolled each time. If you specified a 'target', then that element, else, the element you called the plugin on.
Note that to use 'start' and 'stop' you need to use the option 'interval' first.
If your container element already has any of these event names bound(odd!), then just add the namespace when you trigger.
You probably won't need to deal with these events, but if so, this is how.

What makes jQuery.SerialScroll so special ?

This plugin has many positive features, of course, it won't fit everyone's needs. That's impossible.

• Small Footprint

  This plugin is tiny, as said before, it requires jQuery.ScrollTo. Both plugins together, take less than 3.5kb minified.
  If by chance, you decide to include jQuery.LocalScroll, the 3 of them require less than 5kb. Including this plugin is not a bad idea, it can be used, instead of the option 'navigation' to build a widget with sequential and random scrolling.

• Highly customizable

  This plugin has many settings to customize, in addition, it can use jQuery.ScrollTo's settings. That makes 27 different options!
  If you take a while to analyze them all, you can make your work really unique.

• Accessible, degrades gracefully

  Probably many will automatically skip this part, shame on you!
  If you make sure non-javascript users will see the scrollbars, then they can perfectly navigate your content. You can show the scrollbars only for these few users, easily, using css/js.
  This is one of the main differences with many similar scripts, they generate the content and the styling using javascript.

• Adaptable

  jQuery.SerialScroll won't alter the html or styles at all.
  You are in control of the styles and content of your collections. You don't need the plugin to decide what html to use, or how many items to show simultaneously, and you can safely change that yourself, the plugin will always work.
  The items don't need to have fixed size, nor to be aligned. SerialScroll will scroll from one to the other, no matter what.
  If you want a plugin with premade styles or automatic generation of html, then you should consider any of jQuery carousels.

• Generic and reusable

  Finally, as mentioned before, this plugin can be used for many different situations and doesn't have one specific application.

Links

• Downloads
• Main Post
• Github Repo
• Demo
• jQuery.ScrollTo
• jQuery.ScrollTo's demo

jQuery.ScrollTo

Notice

I've pretty much stopped updating this blog, but the plugin development is still on-going. You can find the link to the Github project page at the bottom of the article.

Introduction

An article about animated scrolling with jQuery inspired me to make a small, customizable plugin for scrolling elements, or the window itself.

How to specify what to scroll ?

Simple, all the matched elements will be scrolled, for example:

$('div.pane').scrollTo(...);//all divs w/class pane

If you need to scroll the window (screen), then use:

$.scrollTo(...);//the plugin will take care of this

How to specify where ?

There are many different ways to specify the target position.
These are:

• A raw number
• A string('44', '100px', '+=30px', etc )
• A DOM element (logically, child of the scrollable element)
• A selector, that will be relative to the scrollable element
• The string 'max' to scroll to the end.
• A string specifying a percentage to scroll to that part of the container (f.e: 50% goes to to the middle).
• A hash { top:x, left:y }, x and y can be any kind of number/string like above.

Note that you only need to use the hash form, if you are scrolling on both axes, and they have different positions.
Don't use the hash to scroll on both axes. Instead, keep reading :)

Settings

The plugin offers you many options to customize the animation and also the final position.
The settings are:

• axis: Axes to be scrolled, 'x', 'y', 'xy' or 'yx'. 'xy' is the default.
• duration: Length of the animation, none (sync) by default.
• easing: Name of the easing equation.
• margin: If true, target's border and margin are deducted.
• offset: Number or hash {left: x, top:y }. This will be added to the final position(can be negative).
• over: Add a fraction of the element's height/width (can also be negative).
• queue: If true and both axes are scrolled, it will animate on one axis, and then on the other. Note that 'axis' being 'xy' or 'yx', concludes the order
• onAfterFirst: If queing, a function to be called after scrolling the first axis.
• onAfter: A function to be called after the whole animation ended.
• You can use any other setting accepted by $().animate()

These settings are very well explained in the demo. Make sure to check it to understand them all.

Manually finding the scrolling limit

$.scrollTo always had an internal function that calculates the scrolling limit for both axes. Since 1.4.2, this function is exposed as $.scrollTo.max.

It's not too nice to use yet but it's probably not something you'll need, you must pass two arguments: a DOM element and an axis string ('x' or 'y') and it will return the max number.

Overloading

This plugin accepts the arguments in two ways, like $.animate().

$(...).scrollTo( target, duration, settings );

$(...).scrollTo( target, settings );

In this second case, you can specify the duration in the hash. You don't need to include any setting, not even the duration, everything has defaults.
The hash of defaults can be accessed at: $.scrollTo.defaults.

jQuery.scrollTo's sons

Indeed, jQuery.scrollTo has offspring :)

• jQuery.localScroll: Will add a scroll effect, to any anchor navigation. Ideal for slides, table of contents, etc. It's small, and incredibly easy to implement.
• jQuery.serialScroll: It's a multi-purpose plugin to animate any kind of sequential navigation(prev/next). It's also small and highly customizable.

These plugins require jQuery.scrollTo and can use its settings!.
That makes around 20 options to fully customize each of them.
They are wrappers for common situations where you might need this plugin.
Using them will save you a lot of time and will give you even more customization.
They can be safely used simultaneously and the 3 of them minified, take merely 3.5kb altogether!

Troubleshooting

Doesn't scroll on IE

Sometimes, you need to set a position (relative or absolute) to the container and give it fixed dimensions, in order to hide the overflow.
If this doesn't work, try giving the container fixed dimensions (height & width).

Links

• Downloads
• Github Repo
• Demo
• Changelog