Sly - JavaScript library for one-directional scrolling

Sly is a JavaScript library for advanced one-directional scrolling with item based navigation support.

Sly supports navigation with:

• mouse wheel scrolling
• scrollbar (dragging the handle or clicking on scrollbar)
• pages bar
• various navigation buttons
• content dragging with mouse or touch
• automated cycling by items or pages
• lots of super useful methods

Sly works in every desktop browser, and due to some divine intervention, even in IE6+, but that is a complete accident. IEs lower than 8 are not officially supported :).

Source: darsa.in

1. INCLUDE JS FILES

<script src="//ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script>
<script src="../js/sly.min.js"></script>

2. HTML

Terminology: Sly is being applied to a FRAME. SLIDEE is a first child of a FRAME. The content/items are then inside of a SLIDEE.

In non-item based navigation, the content can be anything, and HTML would look something like this:

<div class="frame">
    <div class="slidee">
        <h2>This in here...</h2>
        <p>...can be anything. <strong>Anything!</strong></p>
    </div>
</div>

Otherwise in item-based navigation, you need a strict list of items, like:

<div class="frame">
    <ul class="slidee">
        <li></li> // Item
        <li></li> // Item
        <li></li> // Item
    </ul>
</div>

But the actual tags are not enforced. Dividitis is not discriminated

<div class="scrollbar">
    <div class="handle"></div>
</div>

3. JAVASCRIPT

When you want to have a direct access to all methods and complete control over Sly:

var sly = new Sly( frame, options [, callbackMap ] );

New instance has to be than initiated. That is to give you time to bind callbacks before anything happens. For example, if you want to register callbacks, but don't want to use callbackMap.

sly.init();

The .init() method returns the very same instance it is called on, so if you are binding callbacks via a callbackMap argument, or not binding callbacks at all, you can initiate the instance right after the new Sly call. The sly variable will be the same.

var sly = new Sly(frame, options, callbackMap).init();

Now you can use all methods directly on this instance.

sly.activate(1); // Activates 2nd element
sly.reload();    // Reload Sly

A common usecase is wanting sly to be reloaded when the user resizes the browser. The following accomplishes that

  $(window).resize(function(e) {
        $frame.sly('reload');
  });

4. OPTIONS

var frame = new Sly('#frame', {
    horizontal: 0, // Switch to horizontal mode.

    // Item based navigation
    itemNav:      null, // Item navigation type. Can be: 'basic', 'centered', 'forceCentered'.
    itemSelector: null, // Select only items that match this selector.
    smart:        0,    // Repositions the activated item to help with further navigation.
    activateOn:   null, // Activate an item on this event. Can be: 'click', 'mouseenter', ...
    activateMiddle: 0,  // Always activate the item in the middle of the FRAME. forceCentered only.

    // Scrolling
    scrollSource: null, // Element for catching the mouse wheel scrolling. Default is FRAME.
    scrollBy:     0,    // Pixels or items to move per one mouse scroll. 0 to disable scrolling.

    // Dragging
    dragSource:    null, // Selector or DOM element for catching dragging events. Default is FRAME.
    mouseDragging: 0,    // Enable navigation by dragging the SLIDEE with mouse cursor.
    touchDragging: 0,    // Enable navigation by dragging the SLIDEE with touch events.
    releaseSwing:  0,    // Ease out on dragging swing release.
    swingSpeed:    0.2,  // Swing synchronization speed, where: 1 = instant, 0 = infinite.
    elasticBounds: 0,    // Stretch SLIDEE position limits when dragging past FRAME boundaries.
    interactive:   null, // Selector for special interactive elements.

    // Scrollbar
    scrollBar:     null, // Selector or DOM element for scrollbar container.
    dragHandle:    0,    // Whether the scrollbar handle should be draggable.
    dynamicHandle: 0,    // Scrollbar handle represents the ratio between hidden and visible content.
    minHandleSize: 50,   // Minimal height or width (depends on sly direction) of a handle in pixels.
    clickBar:      0,    // Enable navigation by clicking on scrollbar.
    syncSpeed:     0.5,  // Handle => SLIDEE synchronization speed, where: 1 = instant, 0 = infinite.

    // Pagesbar
    pagesBar:       null, // Selector or DOM element for pages bar container.
    activatePageOn: null, // Event used to activate page. Can be: click, mouseenter, ...
    pageBuilder:          // Page item generator.
        function (index) {
            return '<li>' + (index + 1) + '</li>';
        },

    // Navigation buttons
    forward:  null, // Selector or DOM element for "forward movement" button.
    backward: null, // Selector or DOM element for "backward movement" button.
    prev:     null, // Selector or DOM element for "previous item" button.
    next:     null, // Selector or DOM element for "next item" button.
    prevPage: null, // Selector or DOM element for "previous page" button.
    nextPage: null, // Selector or DOM element for "next page" button.

    // Automated cycling
    cycleBy:       null, // Enable automatic cycling by 'items' or 'pages'.
    cycleInterval: 5000, // Delay between cycles in milliseconds.
    pauseOnHover:  0,    // Pause cycling when mouse hovers over the FRAME.
    startPaused:   0,    // Whether to start in paused sate.

    // Mixed options
    moveBy:        300,     // Speed in pixels per second used by forward and backward buttons.
    speed:         0,       // Animations speed in milliseconds. 0 to disable animations.
    easing:        'swing', // Easing for duration based (tweening) animations.
    startAt:       0,       // Starting offset in pixels or items.
    keyboardNavBy: null,    // Enable keyboard navigation by 'items' or 'pages'.

    // Classes
    draggedClass:  'dragged',  // Class for dragged elements (like SLIDEE or scrollbar handle).
    activeClass:   'active',   // Class for active items and pages.
    disabledClass: 'disabled'  // Class for disabled navigation elements.
});

5. METHODS

init

sly.init();

Initiates Sly instance, i.e. sets the required styles, binds event handlers,...

This method returns the very same object it was called on, so you can chain it right after the instance creation:

var sly = new Sly(frame, options, callbackMap).init();

The purpose of this is to give you time to register callbacks with .on() and .off()methods without using callbackMap argument before anything happens.

destroy

sly.destroy();

Removes classes, resets positions, and unbinds all event listeners. When called via .sly()proxy, you can also use an alias:

$('#frame').sly(false); // does the same thing

Returns the Sly object, so you can do shenanigans like new Sly().init().destroy().init().

reload

sly.reload();

Recalculates sizes and positions of elements. Call it if any change has happened to FRAME or its content, like things have been appended, removed, or resized.

slideTo

sly.slideTo( position [, immediate ] );

Animate SLIDEE to a specific position - offset from the start of a FRAME in pixels. In item based navigation, final position will be adjusted to snap items to the edge/center of the visible FRAME.

• position: Integer New SLIDEE position. It will be adjusted to fit within pos.start andpos.end.
• immediate: Boolean When true, re-positioning will occur immediately without animation.

slideBy

sly.slideBy( delta [, immediate ] );

Animate SLIDEE by an amount of pixels. In item based navigation, final position will be adjusted to snap items to edge/center of the visible FRAME.

• delta: Integer Number of pixels, or items (in item based navigation) to slide the SLIDEE by. Negative animates towards the beginning, positive towards the end. The final position will be adjusted to fit within pos.start and pos.end.
• immediate: Boolean When true, re-positioning will occur immediately without animation.

This method is essentially just a shorthand for sly.slideTo(sly.pos.dest + delta).

toStart

sly.toStart( [ target ] [, immediate ] );

Positions target to the start of a visible FRAME. When no target is passed, the whole SLIDEE will be used.

Doesn't work in centered or forceCentered item navigation.

• target: Mixed In item based navigation, it can be an item index, or an item DOM element. In non-item base navigation, it can be a selector or a DOM node of any element inside of SLIDEE.
• immediate: Boolean When true, re-positioning will occur immediately without animation.

Examples:

// Universal
sly.toStart(); // Position the whole SLIDEE to the start
sly.toStart(true); // Position whole SLIDEE to the start, immediately

// Item based navigation
sly.toStart(2); // Position 3rd item in SLIDEE to the start of a visible FRAME
sly.toStart($items.eq(1), true); // Position 2nd item in SLIDEE to the start, immediately

// Non-item based navigation
sly.toStart('h2'); // Position the first H2 element in SLIDEE to the start of a visible FRAME
sly.toStart($('h2').eq(1), true); // Position second H2 element in SLIDEE to the start, immediately

toCenter

sly.toCenter( [ target ] [, immediate ] );

Positions target to the center of a visible FRAME. When no target is passed, the whole SLIDEE will be used.

• target: Mixed In item based navigation, it can be an item index, or an item DOM element. In non-item base navigation, it can be a selector or a DOM node of any element inside of SLIDEE.
• immediate: Boolean When true, re-positioning will occur immediately without animation.

Examples from toStart apply here as well.

toEnd

sly.toEnd( [ target ] [, immediate ] );

Positions target to the end of a visible FRAME. When no target is passed, the whole SLIDEE will be used.

Doesn't work in centered or forceCentered item navigation.

• target: Mixed In item based navigation, it can be an item index, or an item DOM element. In non-item base navigation, it can be a selector or a DOM node of any element inside of SLIDEE.
• immediate: Boolean When true, re-positioning will occur immediately without animation.

Examples from toStart apply here as well.

moveBy

sly.moveBy( speed );

Initiates continuous linear movement in the direction and speed specified by speedargument. The movement will continue until the position reaches a limit, or .stop() method is called.

• speed: Int Movement speed in pixels per second. Negative number means backward movement.

Examples:

sly.moveBy(300); // Move forwards with speed of 300px per second
sly.moveby(-200); // Move backwards with speed of 200px per second

stop

sly.stop();

Stops the continuous movement initiated my .moveBy() method.

activate

sly.activate( item [, immediate ] );

Activates an item, and when smart is enabled, repositions it to help with further navigation. Irrelevant in non-item based navigation.

• item: Mixed Index or DOM element of an item in SLIDEE that should be activated. Items index starts at 0.
• immediate: Boolean When true, re-positioning will occur immediately without animation.

prev

sly.prev();

Activates previous item. Irrelevant in non-item based navigation.

next

sly.next();

Activates next item. Irrelevant in non-item based navigation.

activatePage

sly.activatePage( index [, immediate ] );

Activate a page.

• index: Int Index of a page that should be activated, starting at 0.
• immediate: Boolean When true, re-positioning will occur immediately without animation.

prevPage

sly.prevPage();

Activates previous page. When forceCentered navigation is used, this is a mere alias of.prev() method.

nextPage

sly.nextPage();

Activates next page. When forceCentered navigation is used, this is a mere alias of.next() method.

pause

sly.pause( [ priority ] );

Pauses automated cycling.

• priority Int Pause priority level. Default is 100.

The priority level is used internally for pauseOnHover functionality. You can mostly ignore it.

resume

sly.resume( [ priority ] );

Resumes automated cycling.

• priority Int Resume priority level. Default is 100.

Will resume only a pause with equal or lower priority level.

The priority level is used internally for pauseOnHover functionality. You can mostly ignore it.

toggle

sly.toggle();

Starts when paused, or pauses when cycling.

set

sly.set( name [, value ] );

Updates one, or multiple values in an options object.

sly.set('speed', 0); // Updates one property in options object
sly.set({ speed: 0, cycleInterval: 0 }); // Extends current options object

Not all options can be updated. This is the list of those that can:

• smart
• activateMiddle
• scrollBy
• mouseDragging
• touchDragging
• releaseSwing
• swingSpeed
• elasticBounds
• dragHandle
• clickBar
• syncSpeed
• cycleBy
• cycleInterval
• pauseOnHover
• moveBy
• speed
• easing
• keyboardNavBy
• draggedClass
• activeClass
• disabledClass

You can however update any option, and than do sly.destroy().init() to re-initiate Sly object, thus rebinding all event listeners, rebuilding pages, ...

add

sly.add( element [, position ] );

Adds one or multiple items to the SLIDEE end, or a specified position, and than reloads the Sly object.

• item: Mixed DOM element, DOM node list, array with DOM elements, or HTML string of new item(s).
• position: Int The position where the new item should be placed. Relevant only in item based navigation.

When inserting new items, especially in item-based navigation, you want to use this method as it also handles the active item index. For example: when sly.rel.activeItem: 8, and inserting new item at position 6, the item 6 will be pushed to position 7, andsly.rel.activeItem will shift to 9.

Examples:

sly.add(document.createElement('li'), 5); // Insert item at position 5
sly.add([LIElement, LIElement]); // Insert multiple items at the end of SLIDEE
sly.add('<li></li>', 0); // Insert new item at the beginning of SLIDEE

remove

sly.remove( element );

Removes one element from SLIDEE, and reloads the Sly object.

• element: Mixed In item based navigation, it can be item index, DOM element, or selector. In non-item based, it can be only a DOM element or selector.

moveAfter

sly.moveAfter( item, position );

Method for re-arranging items. Moves an item after the position index. Irrelevant in non-item based navigation.

• item: Mixed Item to be positioned. Can be DOM element, or relative item index.
• position: Mixed Anchor item. Can be DOM element, or relative item index.

Relative index means, that you can pass negative index to select items from the end of items list. For example: passing -1 selects the last item.

Examples:

sly.moveAfter(0, -1); // Moves first item after the last item
sly.moveAfter(-2, 5); // Moves the second to last item after the 6th item

moveBefore

sly.moveBefore( item, position );

Method for re-arranging items. Moves an item before the position index. Irrelevant in non-item based navigation.

• item: Mixed Item to be positioned. Can be DOM element, or relative item index.
• position: Mixed Anchor item. Can be DOM element, or relative item index.

Relative index means, that you can pass negative index to select items from the end of items list. For example: passing -1 selects the last item.

Examples:

sly.moveBefore(-1, 0); // Moves the last item before the first one
sly.moveBefore(-2, 5); // Moves the second to last item before the 6th item

on

sly.on( eventName, callback );

Registers a callback to one or more of the Sly events. All available events and arguments they receive can be found in the Events documentation.

• eventName: Mixed Name of the event, or callback map object.
• callback: Mixed Callback function, or an array with callback functions.

Examples:

// Basic usage
sly.on('load', function () {});

// Multiple events, one callback
sly.on('load move', function () {});

// Multiple callbacks for multiple events
sly.on('load move', [
    function () {},
    function () {}
]);

// Callback map object
sly.on({
    load: function () {},
    move: [
        function () {},
        function () {}
    ]
});

one

sly.one( eventName, callback );

Same as .on() method, but registered callbacks will be executed only once, and will be unbind afterwards.

• eventName: Mixed Name of the event, or callback map object.
• callback: Mixed Callback function, or an array with callback functions.

off

sly.off( eventName [, callback ] );

Removes one, multiple, or all callbacks from one of the Sly events.

• eventName: String Name of the event.
• callback: Mixed Callback function, or an array with callback functions to be removed. Omit to remove all callbacks.

Examples:

// Removes one callback from load event
sly.off('load', fn1);

// Removes one callback from multiple events
sly.off('load move', fn1);

// Removes multiple callbacks from multiple event
sly.off('load move', [ fn1, fn2 ]);

// Removes all callbacks from load event
sly.off('load');

getPos

sly.getPos( item );

Returns the position object of a requested item.

• item: In non-item based navigation, it can be DOM element, or selector for any item inside of a SLIDEE. In item based navigation, it can also be an index of item starting at 0.

The item position object looks like this:

{
    start: 100,  // Start position inside of the FRAME.
    center: 300, // Center position inside of the FRAME.
    end: 700,    // End position inside of the FRAME.
    size: 150    // Size in the current Sly direction.
}

When item hasn't been found, returns false.

getIndex

sly.getIndex( item );

Returns an index of an item in item based navigation, or -1 when not found.

• item: Can be DOM node of an item element, or index in case of checks.

When you pass an integer to the item argument, the function will just check whether it is a valid index (fits between 0 and sly.items.length - 1), and return the very same number, or -1 when invalid.

6. EVENTS

load

Event triggered on first sly load, and on each .reload() method call.

Callback arguments:

1. eventName String Event name.

NOTE: The sly.pos or this.pos object in this event also contains an old property, containing the position object as it was before the reload. The position object than looks like this:

{
    cur: 100,
    dest: 100,
    end: 120,
    start: 0,
    old: {
        cur: 100,
        dest: 100,
        end: 100,
        start: 0
    }
}

active

Event triggered when new item has been activated.

Callback arguments:

1. eventName String Event name.
2. itemIndex Int Index of activated item.

activePage

Event triggered when new page has been activated, or Sly arrived at it while scrolling.

Callback arguments:

1. eventName String Event name.
2. pageIndex Int Index of activated page.

change

Event triggered whenever a new position change has been requested. That means that when you call .slideTo(newPos) it will trigger one change event right before the animation starts.

Callback arguments:

1. eventName String Event name.

Note!: When dragging a scrollbar handle or a SLIDEE, this event is being triggered on each mouse move, which is quite often.

move

Event triggered on every frame of the animation. Animations are chained to requestAnimationFrame, so the frequency of this event when Sly is in animation is 60 FPS.

Callback arguments:

1. eventName String Event name.

moveStart

Event triggered on start of every animation or dragging.

Callback arguments:

1. eventName String Event name.

moveEnd

Event triggered on end of every animation or dragging.

Callback arguments:

1. eventName String Event name.

pause

Triggered when cycling has been paused. That includes pauseOnHover functionality.

Callback arguments:

1. eventName String Event name.

resume

Triggered when cycling has been resumed.

Callback arguments:

1. eventName String Event name.

cycle

Triggered on each cycle tick.

Callback arguments:

1. eventName String Event name.

• Horizontal
• Vertical
• Full page
• Infinite scrolling
• Parallax mode