Drum

Drum is responsive, accessible jQuery plugin to replace a number field or a select menu.

Demo

Getting Started

Using npm

Navigate to your project directory and install the Drum module

$ npm install --save drum-control

Given you have this element in your html:

<div class="drum"></div>

In your script:

import 'drum-control'

$('.drum').drum();

Manually downloading the script

Download the minified production version

In your web page:

<div class="drum"></div>

<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
<script src="jquery.drum.min.js"></script>

<script>
  jQuery(function($) {
    $('.drum').drum();
  });
</script>

A note about jQuery file

The plugin uses jQuery Widget Factory. Two files are available: one that contains the Widget Factory code, and one that doesn't.

1. You can use the smaller jquery.drum.bare.min.js, if you have already included the jQuery Widget Factory or another native jQuery widget in your page.
2. Otherwise you must use jquery.drum.min.js, which includes the jQuery Widget Factory code.

Usage

Initiate Drum

$('.drum').drum(options);

where options is object map of options (optional).

Options

You can customize Drum with these options by either passing options object at initiation, or setting them later, e. g.:

$('.drum').drum('option', 'value', 20);

or

$('.drum').drum('option', {
	max: 100,
	value: 20,
});

All available options

| Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | type | string | number | Type: either numer or select (currently it is not possible to change type after initialization) | | min | number | 0 | Minimum value (for type=number) | | max | number | Infinity | Maximum value (for type=number) | | step | number | 1 | Increment step (for type=number) | | options | array | [] | Array of items for type=select. Supported format is either strings or objects {value: 'value', label: 'Value'} | | orderAsc | boolean | true | Whether the items are displayed in ascending order or descending | | watchOutside | boolean | true | Whether dragging outside the widget rigion should be counted | | edgeLimit | number | 0.8 | Limit where the drum can reach on the edges as part of the viewport.E.g. edgeLimit: 1 means the drum can be spinned to the viewport edge but no further.edgeLimit: .5 - the drum can't go further than half the viewport.valuew higher than 1 will let the drum go beyond viewport. | | acceleration | number | 300 | Drum acceleration (deceleration) | | renderItemsNum | integer | 100 | Number of items to render in the drum. If total number of items is more, they will be inserted as the drum rolls closer to the edge. | | maxSpinOffset | number | 500 | Maximum offset the drum can spin to after a swipe in pixels |

Events

You can listen to events by passing a callback at the initialization:

$(".drum").drum({
	max: 100,
	value: 13,
	change: function(event, data) {
		console.log('Value: '+ data.value);
	}
});

or attach a listener to the "drumchange" event at a later point:

$(".drum").on('drumchange', function(event, data) {
	console.log('Value: '+ data.value);
});

In both cases the callback receives data object with the new value.

All events

| Event | Description | | ----- | ----------- | | dragstart | Triggers when dragging has started on the drum (similar to mousedown) | | drag | Triggers during drag (similar to mousemove) | | dragend | Triggers when dragging has ended (similar to mouseup) | | change | Triggers when the drum has finished revolving and we have a new value |

Styling

To customize widget's appearance, you can style its underlying HTML elements with CSS. The elements' classes are:

| Class | Description | | ------------------- | ----------- | | drum-viewport | The viewport container | | drum-drum | The drum containing all the items. Stretches outside the viewport | | drum-item | Single item inside the drum | | drum-item-current | Currently selected drum item |

You can also add classes using option:

$('.drum').drum('option', 'classes.drum-viewport', 'my-container-name');

The default options are stored in jQuery.fn.drum.defaults. You can override them, so that all instances will be created with the overridden options.

Browser Support

Chrome, Firefox, Safari, Edge and IE 11 are supported.

License

© 2019 Tigran Sargsyan

Licensed under the MIT License