Fullpage scroll / Section scroll / Slider / No dependency / Gzipped size < 5KB
JavaScript HTML CSS
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

preview

DoSlide

Build Status Version License

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


简体中文



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.
listenUserSwipe true Defines whether to listen user swipe 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

  1. onUserMouseWheel or onUserSwipe
  2. onBeforeChange
  3. 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_1_horizontal (source)

Horizontal scrolling.

0_2_infinite (source)

Infinite scrolling.

0_3_transition (source)

About transition.

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 (ง •̀_•́)ง