jquery.ui.spinner

jquery.ui.spinner copied to clipboard

jQuery.ui.spinner 1.20 jQuery.ui extension for a numeric spinner

Licensing

Written by Brant Burnett http://btburnett.com/ mailto:[email protected] Copyright (c) 2009-2010 Brant Burnett Dual licensed under the MIT or GPL Version 2 licenses.

jQuery.ui.spinner is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

Source Control

The root branch for jQuery.ui.spinner is hosted on GitHub at http://github.com/btburnett3/jquery.ui.spinner/.

Overview

jQuery.ui.spinner is based upon jQuery UI 1.8 http://ui.jquery.com, and provides a new spinner widget that can be added to any text box. It fully uses the theme settings created by the ThemeRoller, and has been tested for compatibility with IE 6/7/8, Firefox 2/3, Safari 3.1, and Opera 9. Supports both mouse and keyboard input, and validates input directly into the text box. It requires only minimal CSS to be supplied, mostly relying on the CSS built into the jQuery UI framework.

I did a lot of experimenting to try to find the best method that would work across a variety of web browswers while still using the jQuery UI theme framework rather than images. I finally settled on this method of spans with display: inline-block set on them, which is then positioned next to the text box using absolute positioning, relative to an outer wrapper that is relative positioned. The only restriction I know of with this system is that if you put a right margin on the text box, you must specify it in pixels.

To use, add the CSS found in ui.spinner.css to your jQuery UI CSS files, or link to it separately. Then include the ui.spinner.js or ui.spinner.min.js script file beneath your include for jQuery UI. Finally, during or after $(document).ready call $("#myinput").spinner() to add the spinner to your text box.

Options

The spinner also support a variety of options which can be passed in an object to the constructor. Page wide defaults can be assigned to $.ui.spinner.defaults.

min (float)
	Minimum allowed value of the spinner.  If left with the default, null, there will be no
	minimum unless the input has a maximum length.  Then the minimum will be calculated.  For
	a textbox with a maximum length of 3 characters, the minimum will be -99, etc.
				
max (float)
	Maximum allowed value of the spinner.  If left with the default, null, there will be no
	maximum unless the input has a maximum length.  Then the maximum will be calculated.  For
	a textbox with a maximum length of 3 characters, the maximum will be 999, etc.
	
places (integer)
	Number of decimal places to display.  Defaults to use the number of places found in step.
			
step (float)
	A positive number that the spinner should be incremented by when up is clicked or pressed.
	The spinner will be decremented by this amount for down.  Defaults to 1.
	
largeStep (float)
	Used like step, but for when page up or page down are pressed to jump in larger
	amounts.  Defaults to 10.
	
group (string)
	Grouping separator.  Would commonly be set to ',', defaults to ''.

point (string)
	Decimal point character.  Defaults to '.'.
	
prefix (string)
	Character prefix before the number.  Commonly used for currency symbols.  Defaults to ''.
	
suffix (string)
	Character suffix after the number.  Commonly used for percentage signs.  Defaults to ''.
	
className (string)
	Optional class name that should be applied to the container span that is created around
	the input and the buttons
	
showOn (string)
	Defines when the spin buttons are visible
	'always': Spin buttons are always visible
	'focus': Spin buttons are only visible when the input has focus
	'hover': Spin buttons are only visible when the mouse is hovering over the input
	'both': Spin buttons are visible when the input has focus or is being hovered over
	
width (integer)
	Width in pixels of the spinner.  Defaults to 16.
	
increment (array or string)
	Controls the speed of the incremental spin when you hold a button or key down.  Can be set
	to 'fast' or 'slow' to use predefined speeds.  However, you can also supply an array of
	objects to control the speed increments, or null to stop continuous spinning.  The default
	is 'slow'. The objects in the array must have the following properties:
	
	count (integer)
		Number of times to increment at this speed before moving to the next speed.
	
	mult (integer)
		Number to multiply the current step by.  This increases the amount of each increment.
	
	delay (integer)
		Number of milliseconds to delay between each increment.
	
mouseWheel (boolean)
	If true then mouse wheel events will be attached.  Defaults to true.
	
allowNull (boolean)
	If true then the control will allow a blank (null) value.  Defaults to false.

format ( function(num, places, element) )
	Function that returns a formatted number.  By default formats using the prefix, suffix,
	places, and point options.  Note that this may be called during initialization before
	the spinner is fully constructed.
	
	this
		options object, should be treated as read-only
	
	num (float)
		Number to be formatted
	
	places (integer)
		Number of decimal places to display
	
	element (jQuery)
		input element
		
	
parse ( function(num, element) )
	Function that returns a number parsed from an input string.  Will only be called if the
	input is non-null.  By default parses using the prefix, suffix, and point options.
	
	this
		options object, should be treated as read-only
	
	num (string)
		Number to be parsed
	
	element (jQuery)
		input element
	

Example Option Usage

0 - 100 incrementing by 2: $("#myinput").spinner({min: 0, max: 100, increment: 2});

Show on hover/focus only: $("#myinput").spinner({showOn: 'both'});

Other Commands

The spinner also support commands after they are created, using the standard UI widget method of passing strings.

$("#myinput").spinner("value") Returns the integer value of the input. Returns null if the input is blank.

$("#myinput").spinner("value", value) Sets the integer value of the input. Still validates against min and max, null blanks the input if nulls are allowed.

$("#myinput").spinner("enable") Enables the spinner and the input

$("#myinput").spinner("disable") Disables the spinner and the input

$("#myinput").spinner("destroy") Destroys the spinner, restoring the input to its previous state

$("#myinput").spinner("increment") Increments the spinner, just like you hit the button

$("#myinput").spinner("decrement") Decrements the spinner, just like you hit the button

$("#myinput").spinner("showButtons", [immediate]) Shows the buttons if they are hidden. If immediate is passed as true, the show won't be animated.

$("#myinput").spinner("hideButtons", [immediate]) Hides the buttons if they are visible. If immediate is passed as true, the hide won't be animated.

Version History

1.20 Updated for the UI 1.8 widget factory

1.10 Added support for mouse wheel Added keypress filtering for numbers, special keys only Fixed input always focusing on spinner init (caused error in IE) Added event namespacing to improve destroy Added allowNull option Renamed increment option to step Will now load HTML5 min, max, and step attributes Now sets the maxlength of the input based on min and max Changed incremental speed increase to use an array, or be passed 'slow' and 'fast' options Changing options after the spinner is created now works Added support for decimal places and currency prefix/suffixes Added support for custom formatting

1.01 Renamed from spinbuttons to spinner Implemented right/left and home/end keys per the DHTML Style Guide http://dev.aol.com/dhtml_style_guide Fixed destroy implementation Made setValue call change event on input

1.0 Initial release