DP Number Picker

by Dustin Poissant

Installation

This is a jQuery Plugin. This plugin requires jQuery 2.x or jQuery 1.x with Migrate Plugin. To install this plugin download jQuery and this plugin, place them somewheres accessible to your site. Import jquery, this plugin's JavaScript file, and a skin (css file) for this plugin.


<script src="http://code.jquery.com/jquery-2.1.0.min.js"></script>
<script src="./dpNumberPicker-1.0.1.js"></script>
<link rel="stylesheet" href="./dpNumberPicker-holoLight-1.0.1.css" />

This is typically done in the <head> of the document.

Back to Top

Basic Usage

This plugin extends the jQuery Object with the method dpNumberPicker. This method takes a container element (typically a <div> or <span>) and converts it into the number picker widget.

Setting up the DOM (HTML)

A HTMLElement such as a <div>, <span> or <section> are used. This element must be selectable via jQuery selector, the easiest way to accomplish this is by assigning it an id or a class.


<div id="numberPicker"></div>

This should be placed in the <body> of the document.

Calling the Plugin (JavaScript)

Because this method modifies the DOM, it can not be called until the DOM (document) has loaded. There are many methods for accomplishing this. The $(document).ready(); method is the prefered method for sites using jQuery. For example:


<script>
  $(document).ready(function(){
    $("#numberPicker").dpNumberPicker();
  });
</script>

This should be placed in the <head> of the document.

Putting it Together (Results)

Here are the final results of a basic number picker (Example 1):


<html>
<head>
	<script src="http://code.jquery.com/jquery-2.1.0.min.js"></script>
	<script src="./dpNumberPicker-1.0.1.js"></script>
	<link rel="stylesheet" href="./dpNumberPicker-holoLight-1.0.1.css" />
	<script>
		$(document).ready(function(){
			$("#numberPicker").dpNumberPicker();
		});
	</script>
</head>
<body>
	<div id="numberPicker"></div>
</body>
Results:

Start, Min, Max, Step

This method takes 1 argument. It takes an options paramter, or an object litteral with various options specified as items. The four basic options are, min, max, step (incrament), and value (starting value). The can be used as follows (Example 2):


<html>
<head>
	<script src="http://code.jquery.com/jquery-2.1.0.min.js"></script>
	<script src="./dpNumberPicker-1.0.1.js"></script>
	<link rel="stylesheet" href="./dpNumberPicker-holoLight-1.0.1.css" />
	<script>
		$(document).ready(function(){
			$("#numberPicker").dpNumberPicker({
				value: 5,
				min: 1,
				max: 10,
				step: 1.5
			});
		});
	</script>
</head>
<body>
	<div id="numberPicker"></div>
</body>
Results:

Getting the Value

This widget would be useless if you were not able to access the access the information (the number). This widget creates a text <input> in the DOM within the contained Number Picker. There are two main ways of accessing the value. The first and most obvious way is to access the value of the <input> tag as follows:


$("#numberPicker input").val(); // Returns it's value

This will return the formatted string (i.e. "$3.25"), which can be parsed to retrive the actual value. We will discuss later another method after we dicuess the options parameter which becomes a member of the Number Pickers HTMLElement.

Back to Top

Options

Previous we discussed the options parameter, and the four basic options. Here is a list of all available options and a their descriptions.

min: (number, default=null) The minumum value allowed.

max: (number, default=null) The maximum value allowed.

value: (number, default=0) The starting value.

step: (number, default=1) The incrament at which the value will increase or decrease when the control buttons are pressed.

format: (string, default=null) The format that the number should be displayed as. For example "##.##" will format "3.4362" as "03.44"

editable: (boolean, default=true) Determines if the user will be able to edit the input box using their keyboard. true allows keyboard input, false disables it.

addText: (string, default="+") Text that appares on the add button.

subText: (string, default="-") Text that appears on the subtarct button.

formatter: (function, default=null) Method that formats the value as a string to be displayed. The value is passed in and the desired format should be returned.

beforeIncrease: (function, default=null) Method that is executed right before the value is increase.

afterIncrease: (function, default=null) Method that is executed right after the value is increase.

beforeDecrease: (function, default=null) Method that is executed right before the value is decrease.

afterDecrease: (function, default=null) Method that is executed right after the value is decrease.

beforeChange: (function, default=null) Method that is executed right before the value is changed.

afterChange: (function, default=null) Method that is executed right after the value is changed.

onMin: (function, default=null) Method that is executed when the minimum is reached.

onMax: (function, default=null) Method that is executed when the maximum is reached.


*default=null indicates that options is ignored unless set by the user.

This options paramter is also attached to the element itself as [HTMLElement].options. The options.value item is updated as the value of the number picker updates. This means that you can also access the value of this Number Picker using:


document.getElementById("numberPicker").options.value

or


$("#numberPicker")[0].options.value;

This also means you can access any of the other members of the options paramter, or call any of its methods.


Back to Top

Advanced Usage

In Basic Usage we dicussed the very basics of how to use this plugin. Then we introduced all the options available for the plugin. Now we will explore how to use them.

Formatting

There are two ways of formatting the way the number is displayed. The format option can be used to define the format of the number in terms of the layout of the digits. For example, if you would like "5.8923" to be displayed as "5.9" assign the value "#.#" to the format option as follows:


$('numberPicker').dpNumberPicker({
	format: "#.#"
});

This method works well for formatting the number itself. If you wish to add units before or after the numer the formatter option (function) will work. The value (as a string) is passed into the function, a string in the correct format should be returned. For instance, if you wish "3.25" to become "$3.25", define the formatter function as follows:


$('numberPicker').dpNumberPicker({
	formatter: function(val){
		return "$"+val;
	}
});

This method will work as long as the number is exactly "3.25", if the number is "3.24612" you should use the format and the formatter options together. For example (Example 3):


$('numberPicker').dpNumberPicker({
	step: 0.25,
	format: "#.##",
	formatter: function(val){
		return "$"+val;
	}
});
Results:

Adding units after the number is also easily posible with this option by using return val+" mph";. or any other unit you wish.

Furthermore, when this formatter options is executed it's scope (this) is set to the that particular Number Picker. This feature can can be used handle more advanced usage. We will discuss this in the callback methods section.

Callback Methods

Callback Methods are functions that are executed at specific times by the widget. For instance, beforeChange and afterChange are executed by the widget right before or right after the value changes. When these methods are called the are scoped (this) to the widget HTMLElement allowing you to directly access the options of that specifc widget via this.options.

Here is an example that shows all callback methods at use (Example 4).


$("#np").dpNumberPicker({
	min: -5,
	max: 5,
	beforeIncrease: function(){log("Before Increase: "+this.options.value);},
	afterIncrease: function(){log("After Increase: "+this.options.value);},
	beforeDecrease: function(){log("Before Decrease: "+this.options.value);},
	afterDecrease: function(){log("After Decrease: "+this.options.value);},
	beforeChange: function(){log("Before Change: "+this.options.value);},
	afterChange: function(){log("After Change: "+this.options.value);},
	onMin: function(){log("On Min: "+this.options.value);},
	onMax: function(){log("On Max: "+this.options.value);},
});
var count = 0;
function log(message){
	var l = $("#log");
	count++;
	l.html( count+": "+message+"<br>"+l.html());
}
Results:

These may have no use at all or many advanced usage depending on your needs. One example of a nice usage is the ability to change the color of the <input> text to red when the number is below 0 and green above 0. For example (Example 5):


$("#numberPicker").dpNumberPicker({
	afterChange: function(){
		$(this).removeClass("pos").removeClass("neg");
		if(this.options.value > 0) $(this).addClass("pos");
		else if(this.options.value < 0) $(this).addClass("neg");
	}
});
Results:
Back to Top

Skinning (styling/css)

This plugin has the ability to be skinned (styled) any way you want. I provided 2 skin ("Holo Light" and "Holo Dark") and a wireframe base skin. These skins are applied by importing a different stylesheet. So far in this documentation we have used the "Holo Light" skin/theme. These themes "Holo" are modeled after Android 4.1's theme. "Light" works best on light backgrounds, and "Dark" looks best on dark backgrounds. Here is an example of the "Holo Dark" skin (Example 6):

Results:

The default skin is the wire frame skin (no style just a basic outline of the componets. This is used to create your own skin (Example 7).

Results:

Creating Your Own

Start with the basic wire frame skin. You will notice there are four main parts to style. The entire widget has a class of dp-numberPicker, the decrease button has a class of dp-numberPicker-sub, the increase button hass a class of dp-numberPicker-add and the input box has a class of dp-numberPicker-input. Style these four elements, also use sudo selectors such as :hover for interesting effects.

When the widget reaches its min or max value the decrease and increase buttons are given as class of disabled respectivly. So use .dp-numberPicker-sub.disabled to style those buttons when they are disabled.

Back to Top

JavaScript Interface

A JavaScript Interface is a way of interfacing (interacting) with the widget (using JavaScript) after the widget has been created. We will discuss later the importance of this and show an example.

Here is a list of the JavaScript interfaces, what they do and how to use them.

increase

Calling this method will act as if the increase button was pressed, it will increase the value by the step amount. This method takes no arguments. This method can be called as folllows:


document.getElementById("numberPicker").increase();

decrease

Just as increase, decrease is as if the decrease button was pressed, it will decrease the value by the step amount. This method takes no arguments. This method can be called as follows:


document.getElementById("numberPicker").decrease();

setValue

This sets the value of the widget to a value. The value should be passed to the method as the first argument. For example:


document.getElementById("numberPicker").setValue(5.234);
// Sets the value to 5.234

update

Update is used to refresh the widget. If you change the values of the options paramter call update to refresh the widget. Do so using:


document.getElementById("numberPicker").update();

Min/Max Example

This example uses two Number Pickers to select a range. The two are linked together in that the value of one, is the min or the max of the other. The min slinder can not go higher than the max slider, and vice-versa. (Example 8)


<script>
	$(document).ready(function(){
		$("#min").dpNumberPicker({
			max: 5,
			value: 0,
			afterChange: function(){
				document.getElementById("max").options.min = this.options.value;
				document.getElementById("max").update();
			}
		});
		$("#max").dpNumberPicker({
			min: 0,
			value: 5,
			afterChange: function(){
				document.getElementById("min").options.max = this.options.value;
				document.getElementById("min").update();
			}
		});
	});
</script>
<strong>	Select a Range</strong>
<br><br>
Min:
<div id="min"></div>
<br><br>
Max:
<div id="max"></div>
Results:

Min/Max Example with Pushing

This example is similar to the last but instead of not allowing the max to get lower than the min and vice-versa, they will push each other. Play with it to understand what I mean. For the last instance the update interface was inplimented but not 100% needed, for this example it is required. (Example 9)


$("#min").dpNumberPicker({
	value: 0,
	afterChange: function(){
		var max = document.getElementById("max");
		if(max.options.value < this.options.value){
			max.options.value = this.options.value;
			max.update();
		}
	}
});
$("#max").dpNumberPicker({
	value: 5,
	afterChange: function(){;
		var min = document.getElementById("min");
		if(min.options.value > this.options.value){
			min.options.value = this.options.value;
			min.update();
		}
	}
});

Back to Top

jQuery Interface

For each JavaScript interface above, there is a jQuery equivelent. Basically what we will be doing is recalling the inital plugin function, but on an Element that is already a widget. We will pass strings (and numbers) as parameters instead of an options paramter. The argument is not case sensitive.

dpNumberPicker("increase")

"increase", "add", "addition" and "incrament" can all be passed into the method and it will act just as the JavaScript Interface increase. The argument is not case sentsitive.

dpNumberPicker("decrease")

"decrease", "sub", "subtract" and "decrament" can all be passed into the method and it will act just as the JavaScript Interface decrease. The argument is not case sentsitive.

dpNumberPicker("setvalue")

"setvalue", "set", "value" and "change" can all be passed into the method and it will act just as the JavaScript Interface setValue. The value to change to should be passed as the second argument. The first argument is not case sensitive.

dpNumberPicker("update")

"update" and "refresh" can both be passed into the method and it will act just as the JavaScript Interface update. The argument is not case sensitive.

Here is how to use these interfaces:


$("#numberPicker").dpNumberPicker("increase");
$("#numberPicker").dpNumberPicker("decrease");
$("#numberPicker").dpNumberPicker("setvalue", 5.25);
$("#numberPicker").dpNumberPicker("update");

Back to Top

License

This software is licensed to Dustin Poissant under Attribution-NonCommercial-ShareAlike 3.0 United States (CC BY-NC-SA 3.0 US) which means...

You are free to: Under the following terms:

No warranties are implied or given, this software is distributed AS-IS. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.

View the "Human Readable" version of this license.
View the full version of this lincese.

Back to Top