zwoosh

v1.0.2

Published

2 years ago

Dragscroll, Wheelzoom and Infinityscroll Javascript and Typescript library

Downloads

0High
0Medium
0Low

chaoos

drag dragscroll wheelzoom zoom scale infinityscroll scroll typescript swoosh

Zwoosh

Dragscroll, Wheelzoom and Infinityscroll Javascript and Typescript library

Demo

Try out the demo!

Features

No dependencies
Just use it: invokations in Javascript and Typescript are the same
Dragscroll: use the mouse to scroll oversized content by dragging
Wheelscroll: scrolling by wheel can be customized too (for example horizontal scroll)
Wheelzoom: each element can be zoomed by mousewheel
Anchor links: anchor links are handled too
Elements can be nested
There is a grid system, which can be configured

Install

There are multiple ways to include zwoosh to your project.

NPM

You can get it with NPM:

npm install zwoosh --save

Bower

You can get it with Bower:

bower install zwoosh --save

The classic way

If you prefer the good old way. Place it in the <body> as normal script tag.

<script src='/path/to/zwoosh.js'></script>

Or if you got it with npm:

<script src='node_modules/zwoosh/zwoosh.js'></script>

The require way

If you're using requireJS:

var zwoosh = require("/path/to/zwoosh");

The Typescript way

If you work in Typescript you can import the module just by invoking the import statement. When importing a module using export =, TypeScript-specific import let = require("module") must be used to import the module. Notice that the file ending .ts is not needed:

import zwoosh = require("/path/to/zwoosh");

CSS

Zwoosh needs some CSS styles. You can add them by including dist/zwoosh.css (or dist/zwoosh.min.css for the minified version) in the <head> section of your document.

<link href='/path/to/zwoosh.css' rel='stylesheet' type='text/css' />

Or if you're using Stylus, you can import them with the @import directive

@import 'node_modules/zwoosh/zwoosh'

Usage

Zwoosh can be coustomized heavily. Whether you want dragscroll, whellzoom, wheelscroll or a combination of all of them.

Zwoosh has to be be invoked separately for every element. An invokation with the default options looks like this (notice that it does not depend whether you call zwoosh in Javascript or Typescript):

zwoosh(element);

This allows the user to dragscroll the content within the provided container element. Zwoosh does not care whether there is a scrollbar or not. If the contents oversize the size of the element, then the content will be scrollable by Zwoosh.

Options object

You can also provide an options object. The following invokation is an example with the default options:

zwoosh(element, {
  gridX: 1,
  gridY: 1,
  elasticEdges: {
    left: false,
    right: false,
    top: false,
    bottom: false,
  },
  dragScroll: true,
  dragOptions: {
    exclude: ['input', 'textarea', 'a', 'button', '.zw-ignore', 'select'],
    only: [],
    fade: true,
    brakeSpeed: 2500,
    fps: 30,
    maxSpeed: 3000,
    minSpeed: 300,
  },
  wheelScroll: true,
  wheelOptions: {
    direction: 'vertical',
    step: 114,
    smooth: true,
  },
  wheelZoom: false,
  zoomOptions: {
    maxScale: 0,
    minScale: 0,
    step: 0.1,
    direction: 'up',
  },
  handleAnchors: true,
  });

Most options can be changed later on, when the object has already initialized. Some of them (those which need event handlers to attach/detach or those which do DOM manipulations) need a reinittialization of the object by zwoosh.reinit().

integer `options.gridX` and `options.gridX`

When scrolling, you may want the contents to align to a grid. The grid is calculated in pixels and can be of each size grather than 1. The default values are 1x1, which means not to align to a grid. If options.gridShow is set to true, a modification of one or both options need a reinit() of the object.

boolean `options.gridShow`

This is a boolean value, defaulting to false. If set to true a visible overlay grid is placed over the contents of the Zwoosh element, indicating the size of the grid. This will only be visible is one of options.gridX or options.gridX is set greather than 1.

This works only if the browser supports CSS Generated content for pseudo-elements

boolean `options.elasticEdges.left`, `.top`, `.right` and `.bottom`

The contents can be extened by elastic edges. When scrolling further than the inner elements size and elastic edges are enabled, you will be able to scroll over the edges. Each edge can be enabled or disabled separately.

boolean `options.dragScroll`

Whether to enable or disabled scrolling by dragging with the mouse.

See options.dragOptions for customizations.

array `options.dragOptions.exclude`

Defines an array of CSS selectors. All elements inside the Zwoosh element are ignored for dragscroll when matching against one of those CSS selectors. Besides the obvious tag elements, like input, textarea and such (see the default options), there is a CSS class called zw-ignore. All elements holding this class, will be ignored for dragscrolling. The array can be extended by more elements.

array `options.dragOptions.only`

Defines an array of CSS selectors. Elements matching one of the selectors from the array, will be included for dragscrolling. Every other element will respond to dragscroll. It's the opposite of the options.dragOptions.exclude array from above, and can therefore not be used in combination with that.

This is not implemented yet.

boolean `options.dragOptions.fade`

A flag to enable or disable a scroll fade when dragging an element. If set to false the scroll element will instantly stop after releasing the mouse buttom. If set to true, which is the default, the element will scroll further in the same speed, slowly braking until it stands still or it hits an edge.

integer `options.dragOptions.brakeSpeed`

This options is to customize the fade animation.

This is the amount of pixels/s² to brake the scroll animation. The lower the value, the further the scroll.

integer `options.dragOptions.fps`

This options is to customize the fade animation.

It sets the amount of steps in one second. The more steps, the smoother the animation, but the more CPU power is needed. Don't set this value too high. Values grather than 25 will look as a real motion for the user.

integer `options.dragOptions.maxSpeed`

This options is to customize the fade animation.

This speed in pixels/second will never be exceeded. This is to prevent a scroll animation to be too fast.

integer `options.dragOptions.minSpeed`

This options is to customize the fade animation.

The velocity of the mouse while dragging must exceed this value in pixels/second to trigger a fade animation.

boolean `options.wheelScroll`

Whether to enable or disable scroll by mouse wheel.

See options.wheelOptions for customizations.

string `options.wheelOptions.direction`

This options defines the direction of scrolling when using the mouse wheel. It can have one if two values:

vertical which is the default and
horizontal

If the options is set to vertical and if there are scrollbars present, zwoosh will leave scrolling to the browser itself.

integer `options.wheelOptions.step`

The size of one step when scrolling in pixels. 114 is kind of a default value in most browsers. If you want the scroll animation to be faster, increase the value or decrease the value to scroll slower.

boolean `options.wheelOptions.smooth`

Whether to scroll smooth or instant.

boolean `options.wheelZoom`

Whether to enable or disable zooming by mouse wheel.

This works only with a CSS3 2D Transform capable browser. See options.zoomOptions for customizations.

integer `options.zoomOptions.maxScale`

Defines the maximum scale for an element. If set to 0, there is no maximum. If the maximum is hit, the element will not zoom further in.

integer `options.zoomOptions.minScale`

Defines the minimum scale for an element. If set to 0, there is no minimum. If the minimum is hit, the element will not zoom further out. Notice that the contents will not shrink smaller than the size of the zwoosh element.

integer `options.zoomOptions.step`

When caculating the new scale value, this options is taken. The calculation is as follows:

newScale = oldScale * (1 + step) ... to scale up and: newScale = oldScale / (1 + step) ... to scale down.

string `options.zoomOptions.direction`

Defines the mouse wheel direction of scrolling to zoom in. This can be set to one of two values:

up which is the default and
down

boolean `options.handleAnchors`

When clicking an anchor link whose target resides within a zwoosh element, all nesting zwoosh elements have to scroll to the correct position to reveal the target to the user. If set to true, it lets zwoosh handle anchor links targeting to an anchor inside of this zwoosh element. Notice that, the element outside (maybe the body) handles anchors too. If you want to prevent this, add to body as zwoosh element too.

This behavior can be disabled and thus left to the browser by setting handleAnchors to false.

This work only if the browser supports history.pushState()

Events

There are 4 events triggered from zwoosh:

collide.left
collide.right
collide.top
collide.bottom

They trigger when the zwoosh element collides with one of the edges. They trigger once. That means when scrolling to bottom on the left hand border, the collide.left event is triggered only once, not on each step. The element has to leave the edge and collide again to trigger the event again.

CSS

Zwoosh needs some CSS classes. Their purpose is quickly explained below:

zw-ignore is the default CSS class on elements in a Zwoosh elment, where dragscroll is ignored. This is set in the array array options.dragOptions.exclude.
zw-outer is added to the given container element (the zwoosh element). This class should not be used to style the container element. Use an own CSS class instead.
zw-inner is the class added to the inner element, which wraps all the content of the zwoosh element.
zw-grab is added to containers whose contents are dragscollable.
zw-nograb is added to containers whose contents are not dragscollable.
zw-grabbing is added to the body element, when a dragscroll is in progress.
zw-scale is added to the scale element which is parent of the inner element and child of the container element.
zw-fakebody is added to the element wrapping all body contents. This element is appended afterwards to the body. This only is needed when the body is defined as zwoosh element.
zw-{random-string} is a class randomly generated when the zwoosh element initializes. It is to uniquely identify a zwoosh element.

Public accessible methods

Some methods are public accessible and can be invoked from outside the object context.

`zwoosh.scrollTo()`

/**
 * scrollTo helper method to scroll to a x- and y-coordinate
 *
 * @param {number} x - x-coordinate to scroll to
 * @param {number} y - y-coordinate to scroll to
 * @param {boolean} smooth - whether to scroll smooth or instant
 * @return {void}
 */
public scrollTo (x: number, y: number, smooth = true)

`zwoosh.scrollBy()`

/**
 * scrollBy helper method to scroll by an amount of pixels in x- and y-direction
 *
 * @param {number} x - amount of pixels to scroll in x-direction
 * @param {number} y - amount of pixels to scroll in y-direction
 * @param {boolean} smooth - whether to scroll smooth or instant
 * @return {void}
 */
public scrollBy (x: number, y: number, smooth = true)

`zwoosh.scaleTo()`

/**
 * Scales the inner element to an absolute value.
 * 
 * @param {number} scale - the scale
 * @param {boolean} honourLimits - whether to honour maxScale and the minimum width and height
 * of the container element.
 * @return {void}
 */
public scaleTo (scale: number, honourLimits = true)

`zwoosh.scaleBy()`

/**
 * Scales the inner element by a relatice value based on the current scale value.
 * 
 * @param {number} percent - percentage of the current scale value
 * @param {boolean} honourLimits - whether to honour maxScale and the minimum width and height
 * of the container element.
 * @return {void}
 */
public scaleBy (percent: number, honourLimits = true)

`zwoosh.on()`

/**
 * Register a custom event callback
 *
 * @param {string} event - The event name
 * @param {(e: Event) => any} callback - A callback function to execute when the event raises
 * @return {Zwoosh} - The Zwoosh object instance
 */
public on (event: string, callback: (e: Event) => any): Zwoosh

`zwoosh.off()`

/**
 * Deregister a custom event callback
 *
 * @param {string} event - The event name
 * @param {(e: Event) => any} callback - A callback function to execute when the event raises
 * @return {Zwoosh} - The Zwoosh object instance
 */
public off (event: string, callback: (e: Event) => any): Zwoosh

`zwoosh.reinit()`

/**
 * Reinitialize the zwoosh element
 * 
 * @return {Zwoosh} - The Zwoosh object instance
 */
public reinit ()

`zwoosh.destroy()`

/**
 * Revert all DOM manipulations and deregister all event handlers
 * 
 * @return {void}
 */
public destroy ()

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Zwoosh

Demo

Features

Install

NPM

Bower

The classic way

The require way

The Typescript way

CSS

Usage

Options object

integer options.gridX and options.gridX

boolean options.gridShow

boolean options.elasticEdges.left, .top, .right and .bottom

boolean options.dragScroll

array options.dragOptions.exclude

array options.dragOptions.only

boolean options.dragOptions.fade

integer options.dragOptions.brakeSpeed

integer options.dragOptions.fps

integer options.dragOptions.maxSpeed

integer options.dragOptions.minSpeed

boolean options.wheelScroll

string options.wheelOptions.direction

integer options.wheelOptions.step

boolean options.wheelOptions.smooth

boolean options.wheelZoom

integer options.zoomOptions.maxScale

integer options.zoomOptions.minScale

integer options.zoomOptions.step

string options.zoomOptions.direction

boolean options.handleAnchors

Events

CSS

Public accessible methods

zwoosh.scrollTo()

zwoosh.scrollBy()

zwoosh.scaleTo()

zwoosh.scaleBy()

zwoosh.on()

zwoosh.off()

zwoosh.reinit()

zwoosh.destroy()

License

integer `options.gridX` and `options.gridX`

boolean `options.gridShow`

boolean `options.elasticEdges.left`, `.top`, `.right` and `.bottom`

boolean `options.dragScroll`

array `options.dragOptions.exclude`

array `options.dragOptions.only`

boolean `options.dragOptions.fade`

integer `options.dragOptions.brakeSpeed`

integer `options.dragOptions.fps`

integer `options.dragOptions.maxSpeed`

integer `options.dragOptions.minSpeed`

boolean `options.wheelScroll`

string `options.wheelOptions.direction`

integer `options.wheelOptions.step`

boolean `options.wheelOptions.smooth`

boolean `options.wheelZoom`

integer `options.zoomOptions.maxScale`

integer `options.zoomOptions.minScale`

integer `options.zoomOptions.step`

string `options.zoomOptions.direction`

boolean `options.handleAnchors`

`zwoosh.scrollTo()`

`zwoosh.scrollBy()`

`zwoosh.scaleTo()`

`zwoosh.scaleBy()`

`zwoosh.on()`

`zwoosh.off()`

`zwoosh.reinit()`

`zwoosh.destroy()`