Just Slider
A jQuery plugin, customizable and responsive range slider for modern browsers. Requires jquery to work.
Compatible with
- node v18.10.0
- npm 8.19.2
- jquery v3.6.1
Demo
You can try slider out on the Demo page. It has 4 different configurations with control panels to test and change sliders with different options.
Installation
npm i just-slider
Usage
import "just-slider";
import "just-slider/dist/just-slider.css";
$("#element").justSlider(options);
Documentation
Options
number
= 0
min Minimum possible value of the slider.
number
= 100
max Maximum possible value of the slider.
number
= 10
step Step size.
number
= 0
from Sets value of the first handle.
number
= 100
to Sets value of the second handle. It'll be disabled if range is false.
"horizontal" | "vertical"
= "horizontal"
orientation Sets slider's orientation. For horizontal case, slider's direction is from left to right. For vertical, it is from bottom to top.
"forward" | "backward"
= "forward"
direction Sets slider's direction.
boolean
= false
range If true, two handles will be enabled instead of one.
boolean
= false
tooltips Shows tooltips attached to handles, indicating their current values.
boolean
= false
progressBar Shows progress bar between two handles if range mode is enabled. Otherwise bar is in between minimum and first handle values.
ScaleOptions
= null
scale Shows scale next to the slider. Customizable with its own options. It has divisions with little lines and values.
ScaleOptions
number
= 3
density Calculates little divisions between values on slider's scale. For instance, if set to 3, scale will generate a line every 3% of the slider's range in between the divisions with values.
boolean
= true
numbers Shows numbers on scale.
boolean
= true
lines Shows little lines (divisions) on scale.
(state) => void
onUpdate Callback, which will be triggered whenever slider's state changes. State argument has all of slider's properties mentioned above.
Example
const options = {
min: 5,
max: 50,
from: 25,
orientation: "vertical",
scale: {
lines: false,
numbers: true,
}
}
$("div.container").justSlider(options);
Initialization with data-attributes
Slider can be initialized with just-slider
class and providing options via data attributes.
Attributes list
data-min="0"
data-max="100"
data-step="10"
data-from="0"
data-to="100"
data-orientation="horizontal"
data-direction="forward"
data-range="false"
data-tooltips="false"
data-progress-bar="false"
data-scale="false"
data-scale-density="3"
data-scale-numbers="true"
data-scale-lines="true"
Example
<div class="just-slider" data-min="10" data-step="5" data-orientation="vertical" data-scale="true" data-scale-lines="false"></div>
API
When justSlider is created, you can get an instance with methods to get and set different data.
$("div.container").justSlider(options);
const justSlider = $("div.container").data("just-slider");
justSlider.updateOptions({
from: 1000,
});
updateOptions(options)
Updates slider's options. Same properties as on initialization.
update(type, value)
Sets handle value.
- type
"from" | "to"
— handle that is going to be changed - value
number
— new value
State
getState() => Returns slider's state.
number | number[]
get() => Returns handle values. Single number if range is false. Otherwise it's an array of 2 numbers.
JQuery<HTMLElement>
$slider() => Returns generated html node of the slider.
reset()
Resets handle values to the state they were initialized with.
Events
To subscribe on slider changes, set a callback function on initialization.
function callback(state) {
const { from, to } = state;
// code
}
$("div.container").justSlider({
...options,
onUpdate: callback,
});
Or you can do it anytime when slider is already created by overwriting previous callback.
justSlider.updateOptions({
onUpdate: callback,
});
Development
Installation
git clone https://github.com/Riemelt/justSlider.git
cd justSlider
npm i
Commands
Run demo on dev-server
npm start
Build demo in development mode. Built demo is located at /demo
folder.
npm run dev:demo
Build demo in production mode. Built demo is located at /demo
folder.
npm run build:demo
Build plugin in development mode. Built plugin is located at /dist
folder.
npm run dev
Build plugin in production mode. Built plugin is located at /dist
folder.
npm run build
Run unit-tests
npm test
Architecture
Plugin's placed at src/app
and its styles are at src/styles
.
Entry point is index.ts
, which imports styles and just-slider-jquery.ts
file, which, in turn, creates the plugin by extending jquery object.
Slider is implemented using MVP pattern. It's made with JustSlider, Model, Presenter, View, Subview classes (e.g. ProgressBar, Handle, Scale) and EventManager class as a link between them.
User gets an instance of JustSlider class when creating slider with jquery on a DOM element. It stores initial slider values and provides API methods for user to update or get slider's state. In order to do so, it has Presenter instance and calls its methods.
EventManager is a mutual class that provides possibility to subscribe on the slider changes to dispatch them lately everytime the events are triggered.
Presenter has instances of Model, View and EventManager. It initializes both model and view, registers events and creates user input handlers for View, using its API.
For example, View has addCreateHandleHandlers
method. Presenter provides a callback to View, which will be called with slider changes when user interacts with slider's handles. That callback, in turn, will update Model, where all the validations and logic are happening. Eventually Model updates slider's state and dispatches events via EventManager. In the end, these events will call View update methods and user will see the result.
Presenter also adds event listeners (observers) to the manager. Events trigger View to update visual part of the slider when new Model state is set and trigger onUpdate
callback provided with slider options.
Model class is responsible for all the business logic, validating and operating with data and slider's options. It receives data, updates slider's state and dispatches events. Presenter is the only class that calls Model methods.
View generates all the HTML nodes and updates visual part of the application, applying corresponding styles. It gets updated whenever events from EventManager are triggered. Some of View calculation helpers are stored at View/utilities.ts
and shared among different subviews.
View is responsible for handling clicks on the slider and handling, creating, deleting or updating its subviews.
Subview classes provide methods like update
and setSomeHandler
to the layer above.
Example of how to works
Presenter creates a handler for View.
// Presenter.ts
function handler(value: number, handle: HandleType) {
this.model.updateHandle(value, handle);
}
this.view.addCreateHandleHandlers(handler);
And adds an event listener (observer) for the event.
// Presenter.ts
function observer() {
const state = this.model.getState();
this.view.updateHandle(state, "from");
}
this.eventManager.addEventListener("HandleFromMove", observer);
When user moves the handle, View calls provided handler.
// View/Handle.ts
private handleHandleMousemove(event: MouseEvent) {
// code
this.handleMousemoveHandler(value, "from");
}
Then Model updates slider's state and dispatches event.
// Model.ts
private updateHandle(value: number, type: HandleType) {
// code
this.setHandle(value, type);
this.eventManager.dispatchEvent("HandleFromMove");
}
After that, all subscribed observers will be called.
UML diagram
Click to see full version.