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. |
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 sectioncur
: 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 sectiontarIndex
: index of target sectioncur
: current sectiontar
: 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 sectionlastIndex
: index of last sectioncur
: current sectionlast
: last section
After switching, execute callback
with current DoSlide object as context object (this
) .
onOverRange(callback(curIndex, tarIndex, cur))
curIndex
: index of current sectiontarIndex
: index of target sectioncur
: current section
When try to switch to overrange section, execute callback
with current DoSlide object as context object (this
) .
onUserMouseWheel(callback(direction))
direction
: stringup
ordown
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
: stringup
,down
,left
orright
represent swipe direction
Before switching which caused by swipe event occurs, execute callback
with current DoSlide object as context object (this
) .
Trigger order
onUserMouseWheel
oronUserSwipe
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
: stringup
ordown
represent scroll directionisStopPropFn
: a function returntrue
orfalse
, 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
: stringup
,down
,left
orright
represent swipe directionisStopPropFn
: a function returntrue
orfalse
, 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 (ง •̀_•́)ง