preview

DoSlide

Fullpage scroll / Section scroll / Slider / No denpendency / Gzipped size < 5KB

Introduction
Usage
Behavior pattern
Create object
Configuration
Properties
Functions
Callbacks
Inner tool library
Plugins
Low invasive
Compatibility
FAQ
Examples
Contributing

Introduction

DoSlide is a light, no dependency and low invasive JS plugin, providing a pattern which switch entire one section at a time. DoSlide can be flexibly configured and has an inner tool library like jQuery, you can implement specific requirements quickly by taking advantage of it.

Take a quick look at introduction page.

Noted: In order to optimize performance (especially on mobile), the version 1.0.0 changes the default switch (scroll) mechanism, meanwhile, the way of including CSS and other places have been changed, so it's not compatible with previous versions.

Usage

Download dist folder or install it by using npm:

npm install --save do-slide

DoSlide is a UMD module, which can be used as a module in both CommonJS and AMD modular environments. When in non-modular environment, a variable named 'DoSlide' will be exposed in outer scope.

Include CSS file:

<link rel="stylesheet" href="path/to/do-slide/dist/do-slide.min.css">

Include JS file:

<script src="path/to/do-slide/dist/do-slide.min.js"></script>

HTML structure:

<div class="ds-parent">
    <div class="ds-container">
        <div>Section 1</div>
        <div>Section 2</div>
        <div>Section 3</div>
    </div>
</div>

Then create a corresponding DoSlide object:

var slide = new DoSlide('.ds-container', {/* configurations */})

The CSS file content (do-slide.css) is very simple, you can copy it to your project CSS instead of including the file alone (if don't take update into account) . Default ds-parent class doesn't set position property (not be positioned) and size properties, you can set them when you need.

Noted: Do not use <body> as parent element, it may cause a problem with height in some Android browsers which have auto-hide location bar (issue#8) , don't do this:

<body class="ds-parent"> <!-- Do not use 'body' as parent element -->
    <div class="ds-container">
        <div></div>
        <div></div>
        <div></div>
    </div>
</body>

This structure is OK:

<body>
    <div class="ds-parent">
        <div class="ds-container">
            <div></div>
            <div></div>
            <div></div>
        </div>
    </div>
</body>

TL;DR: The basic code to apply full page scrolling:

<body>
    <div class="wrap ds-parent">
        <div class="ds-container">
            <div>Section 1</div>
            <div>Section 2</div>
            <div>Section 3</div>
        </div>
    </div>
</body>

body {
    margin: 0;
    padding: 0;
    overflow: hidden;
}
.wrap {
    position: absolute;
    width: 100%;
    height: 100%;
}

var slide = new DoSlide('.ds-container')

There are several practices in Examples section.

Behavior pattern

By understanding how DoSlide works, you can use it better. In its default configuration, DoSlide acts as follows:

Assume there is a HTML structure:

<html>
    <head>
        ......
    </head>
    <body>
        <div class="ds-parent">
            <div class="ds-container ds-init">
                <div class="section-1"></div>
                <div class="section-2"></div>
                <div class="section-3"></div>
            </div>
        </div>
        ......
    </body>
</html>

After page structure finishes loading, we execute

new DoSlide('.ds-container')

to create a new DoSlide object. In this time, the object performs the following actions:

initialize child elements
activate (add active class) and display the first child element
start listen user mouse wheel and touch slide events
remove ds-init class from corresponding element

The code about above process is in init.js . The default CSS is in style.css .

Then the HTML will look like:

<html>
    <head>
        ......
    </head>
    <body>
        <div class="ds-parent">
            <div class="ds-container">
                <div class="section-1 active"></div>
                <div class="section-2"></div>
                <div class="section-3"></div>
            </div>
        </div>
        ......
    </body>
</html>

When user mouse wheel or touch slide event is triggered, DoSlide will switch active section if it can.

When switching start, DoSlide will add transition-out class to current section and add transition-in class to target section, then remove them both when switching complete.

Create object

DoSlide provides two ways to create object:

new DoSlide([selector, config])
DoSlide.from(doSlideObj[, selector, config])

The selector argument can be a selector string or a HTMLElement.

There can be several DoSlide objects in a page, you can use DoSlide.from() to create a new object configured as same as the given doSlideObj.

Configuration

In DoSlide's source code (config.js) , configurations look like this:

const DEFAULT_INIT_CONFIG = {
    initIndex            : 0,
    initClass            : 'ds-init',
 
    activeClass          : 'active',
    transitionInClass    : 'transition-in',
    transitionOutClass   : 'transition-out',
 
    silent               : false,
 
    horizontal           : false,
    infinite             : false,
 
    listenUserMouseWheel : true,
    listenUserSwipe      : true,
    eventElemSelector    : null
}
 
const DEFAULT_CONFIG = {
    duration             : 1000,
    timingFunction       : 'ease',
    minInterval          : 50,
 
    translate3d          : true,
 
    parent               : null,
 
    respondToUserEvent   : true,
    stopPropagation      : false
}

In index.js :

// in constructor
this.config = Object.assign({}, DEFAULT_CONFIG, DEFAULT_INIT_CONFIG)
this.set(config)

The default config is a combination of DEFAULT_INIT_CONFIG and DEFAULT_CONFIG. The DEFAULT_INIT_CONFIG only can be customized once at initialization time:

var slide = new DoSlide('.container', {
    horizontal: true    // customize DEFAULT_INIT_CONFIG
})

don't do this:

slide.set({
    horizontal: true    // don't o(>_<)o
})

but you can customize DEFAULT_CONFIG in any time.

A more detailed explanation of the configurations follows below:

Name	Default value	Description
initIndex	0	Index of section to be activated on initialization.
initClass	do-slide-init	Class to be removed after initialization.
activeClass	active	Class to be added to active child element.
transitionInClass	transition-in	Class to be added to translate-in element.
transitionOutClass	transition-out	Class to be added to translate-out element.
silent	false	The actions of DoSlide object will be pure logic with no affect to HTML.
horizontal	false	Defines whether to be horizontal switching or not.
infinite	false	Defines whether to be infinite switching or not.
listenUserMouseWheel	true	Defines whether to listen user mouse wheel event or not.
listenUserSlide	true	Defines whether to listen user touch slide event or not.
eventElemSelector	null	User event element selector. Set to `null` to let corresponding element be event element. Set to `false` will don't listen user events. In other case, it can be a selector string or a HTMLElement.

Name	Default value	Description
duration	1000	Transition time (ms) .
timingFunction	ease	The value of `transition-timing-function` property in CSS.
minInterval	50	The minimum time interval between switching.
translate3d	true	Defines whether to use CSS `translate3d` or not.
parent	null	Parent DoSlide object.
respondToUserEvent	true	Defines whether to respond to user event or not.
stopPropagation	false	Defines whether to stop event propagation or not.

Noted: parent just a shortcut that be used to implement linkage in nested structure quickly, you can totally implement the linkage by using onOverRange() and stopPropagation instead of using parent.

Properties

Properties of DoSlide object (instance):

Name	Readonly	Description
el	yes	Corresponding element.
eventEl	yes	Event element.
sections	yes	Collection of sections
currentIndex	yes	Index of current section.
currentSection	yes	Current section.
isChanging	yes	Is switching sections now.
$	yes	Inner tool library.

Properties of DoSlide:

Name	Readonly	Description
supportedTransition	yes	Supported CSS `transition` property name.
supportedTransform	yes	Supported CSS `transform` property name.
$	yes	Inner tool library.

Functions

Functions of DoSlide object (instance):

next()

Switch to next section.

prev()

Switch to previous section.

go(index)

Switch to section with given index.

set(name, value) || set({ name: value, ... })

Set configuration value.

get(name)

Get configuration value.

do(callback(curIndex, cur))

curIndex: index of current section
cur: current section

Execute callback with current DoSlide object as context object (this) .

initSpaceByKey(key)

Initialize space of current DoSlide object by key, return initialized space. The space is an object, the key is generated by applyNewKey.

getSpaceByKey(key)

Get space by key.

Functions of DoSlide:

applyNewKey()

Apply a globally unique key for getSpaceByKey.

use(plugin[, config])

Install a plugin. It will call plugin.install(DoSlide, config) , so the plugin should provide an install function which will be called with the DoSlide as the first argument, along with possible config.

Callbacks

onBeforeChange(callback(curIndex, tarIndex, cur, tar))

curIndex: index of current section
tarIndex: index of target section
cur: current section
tar: target section

Before switching occurs, execute callback with current DoSlide object as context object (this) .

onChanged(callback(curIndex, lastIndex, cur, last))

curIndex: index of current section
lastIndex: index of last section
cur: current section
last: last section

After switching, execute callback with current DoSlide object as context object (this) .

onOverRange(callback(curIndex, tarIndex, cur))

curIndex: index of current section
tarIndex: index of target section
cur: current section

When try to switch to overrange section, execute callback with current DoSlide object as context object (this) .

onUserMouseWheel(callback(direction))

direction: string up or down represent scroll direction

Before switching which caused by mouse wheel event occurs, execute callback with current DoSlide object as context object (this) .

onUserSwipe(callback(direction))

direction: string up, down, left or right represent swipe direction

Before switching which caused by swipe event occurs, execute callback with current DoSlide object as context object (this) .

Trigger order

onUserMouseWheel or onUserSwipe
onBeforeChange
onChanged

You can return false in any callback to terminate subsequent calls.

Example 2_0_event (source) shows the process.

Inner tool library

You can access inner tool library through DoSlide.$ or $ property of DoSlide object.

The library provides such functions like jQuery:

on(type, listener[, useCapture = false])

$(selector) .on(type, listener, useCapture)
$.on(HTMLElement, type, listener, useCapture)

off(type, listener[, useCapture = false])

$(selector) .off(type, listener, useCapture)
$.off(HTMLElement, type, listener, useCapture)

attr(name, value) || attr(attrObj)

$(selector) .attr(name, value) || $(selector) .attr(attrObj)
$.attr(HTMLElement, name, value) || $.attr(HTMLElement, attrObj)

removeAttr(name)

$(selector) .removeAttr(name)
$.removeAttr(HTMLElement, name)

css(name, value) || css(propertyObj)

$(selector) .css(name, value) || $(selector) .css(propertyObj)
$.css(HTMLElement, name, value) || $.css(HTMLElement, propertyObj)

addClass(name)

$(selector) .addClass(name)
$.addClass(HTMLElement, name)

removeClass(name)

$(selector) .removeClass(name)
$.removeClass(HTMLElement, name)

hasClass(name)

$(selector) .hasClass(name)
$.hasClass(HTMLElement, name)

eq(index)

$(selector) .eq(index)

each(callback, isContext, isFalseBreak, breakValue)

$(selector) .each(callback, isContext, isFalseBreak, breakValue)
$.each(Array, callback, isContext, isFalseBreak, breakValue)

getSupportedCSS(name[, isAutoPrefix = true])

$.getSupportedCSS(name, isAutoPrefix)

Get supported CSS property name. For example, the browser only supports -webkit-transform, then getSupportedCSS('transfrom') will return '-webkit-transform'.

onMouseWheel(HTMLElement, callback(direction)[, isStopPropFn() => false])

direction: string up or down represent scroll direction
isStopPropFn: a function return true or false, defines whether to stop event propagation or not

Listen user mouse wheel event, execute callback with HTMLElement as context object (this) when triggered.

onSwipe(HTMLElement, callback(direction)[, isStopPropFn() => false])

direction: string up, down, left or right represent swipe direction
isStopPropFn: a function return true or false, defines whether to stop event propagation or not

Listen user touch swipe event, execute callback with HTMLElement as context object (this) when triggered.

Example codes

DoSlide.$('.foo')
       .addClass('fooClass')
       .attr({
            fooAttr: 'fooValue'
       })
       .css({
            'font-size': '2em'
       })
       .on('click', function(event) {
            console.log(event)
       })

DoSlide.$.onMouseWheel(document.body, function(direction) {
    console.log(direction)
})

Plugins

See src/plugins .

Low invasive

The feature is mainly embodied in the following 2 aspects:

No monkey-patching. No more than one variable (DoSlide) may be exposed in outer scope.
You can take only what you need.

Compatibility

DoSlide can run on all modern browsers which support ES5.

If the browser dosen't support CSS transform, DoSlide will use left / top instead.

FAQ

Waht is DoSlide, anyway?

Actually, in my mind, it's a switch pattern, by the way, providing some functionalities. But no matter how I explain, it is (looks like) a plugin.

How to customize the transition effect?

You can reference 3_0_fade (source) , the KEY is setting silent to true to make original actions be pure logic, then you can do whatever you want.

Examples

0_0_basic (source)

Basic usage, apply full page scrolling easily and quickly.

0_4_nested (source)

Nested structure.

1_0_set_class (source)

Configurate class name.

2_0_event (source)

About event callbacks.

2_1_event_element (source)

Configurate event element.

2_2_invert_mouse_wheel (source)

Invert mouse wheel.

3_0_fade (source)

Implement fade effect quickly by using inner tool library and event callbacks.

3_1_slider (source)

A simple slider.

3_2_slider_fade (source)

A simple slider with fade effect.

3_3_init (source)

About initialization.

Contributing

Development is in the dev branch, please push new changes to dev branch.

Development: webpack + babel
Test: karma + jasmine + phantomjs
Continuous integration: Travis CI

 
# install 
npm install
 
# develop 
npm run watch
 
# test 
npm test
 
# build 
npm run build

If you catch a mistake or want to contribute to the repository, any PR is welcome.

Love & Peace (ง •̀_•́)ง

do-slide