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.
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.
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.
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.
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:
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:
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.
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.
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.
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 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:
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:
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.
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.
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();
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();
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 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();
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:
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(); } } });
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.
"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.
"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.
"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.
"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");
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: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.