autoNumeric 1.8.3 is a jQuery plugin that automatically formats currency and numbers as you type on form inputs. It supports most International numeric formats and currency signs including those used in Europe, North and South America, Asia and India (lakhs**).
Any number of currency formats can reside on the same page and are configured by options that can be placed as HTML5 data attribu te or passed as an argument. These settings can easily be changed at any time using the new ‘update’ method or via the callback feature. utoNumeric to many other elements, allowing you to place formatted numbers and currency on just about any part of the page.
Seven built in methods gives you the flexibility needed to use autoNumeric to its maximum potential. You can now easily start and stop autoNumeric, update the settings and remove the formatting from multiple inputs, preparing the values for manipulation or form submission.
There are fifteen options which controls the behavior and format of the form input field. These options are easy to implement with the data/argument code generator located below.
If you are developing sites that span across International lines that use different currency symbols and formats you will find autoNumeric() the ideal tool to shorten your development time.
Donations allow me to keep
hosting & updating autoNumeric()
Authors:
- Robert Knothe
- Contact - bob{@}decorplanit.com (remove brackets)
- github - https://github.com/BobKnothe/autoNumeric
- Sokolov Yura- aka funny_falcon
Download: autoNumeric-1.8.3.js 'heavy on comments'
Last update: 2013-2-10 GMT 3:00 PM
Demonstration of autoNumeric()'s flexibility
Key features of autoNumeric()
- Compatible with jQuery-1.7.2 and higher.
- Supports multiple international numeric formats including those used in most of Europe, North and South America, Asia and India (lakhs on values below 1 billion).
- Most currency symbols are supported and can be placed as a prefix or suffix in the input field.
- Precision control of minimum & maximum values to the nth decimal places!
- The number of decimal places and negative sign are now set via the min/max values. Also positive and negative values are easily toggled from any caret position within the input field.
- Supports nine different rounding methods (Round-Half-Up Symmetric & Asymmetric, Round-Half-Down Symmetrical & Asymmetric, Round-Half-Even "Bankers Rounding", Round Up, Round Down, Round to Ceiling & Round to Floor).
- Callback function is supported and can be done via options or HTML5 data.
- NEW - Added 7 methods for greater control.
- NEW - Added HTML 5 data support and eliminated the metadata plugin dependency.
- NEW - autoNumeric can be attached to the following elements: 'dd', 'dt', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'input', 'label', 'p', 'span', 'td', 'th'.
- NEW - Added 'lZero' to the defaults which controls the leading zero behavior.
- NEW - Added 'nBracket' to settings - controls negative numbers being shown with brackets. Example "-$99.00 = ($99.00)". The brackets are only visible when the input field does NOT have focus.
- Pasting is supported as long as the values being pasted conform to the format set for that target field.
Guide on how the balance of this page is organized:
- Methods supported by autoNumeric
- Settings defaults and options with code generator
- Tutorial on implementing autoNumeric
- Callback function details
- Methods examples
- Options examples
- Supported Browsers
- Known issues
- Change notes & History log
Deploying autoNumeric can be accomplished in just a few steps. The methods listed below gives you the ability to start, stop and update options of autoNumeric as well as format or remove the formatting from input fields for use in other scripts and or form submissions. Click on the links for details and demos on each method.
Method(s) | Description | Format |
'init' | initializes autoNumeric | $(selector).autoNumeric('init', {options}); |
'destroy' | disables autoNumeric for the selected element | $(selector).autoNumeric('destroy'); |
'update' | updates options - can be called multiple times | $(selector).autoNumeric('update', {options}); |
'set' | returns a formatted string via ".val()" or ".text' | $(selector).autoNumeric('set', value); |
'get' | returns un-formatted object via ".val()" or ".text()" | $(selector).autoNumeric('get'); |
'getString' | returns a string 'URL encoded' from the selected form | $(selector).autoNumeric('getString'); |
'getArray' | returns a array of objects from the selected form | $(selector).autoNumeric('getArray'); |
'getSettings' | returns settings for the selected element | $(selector).autoNumeric('getSettings'); |
Configuring autoNumeric settings: The are a total of 15 settings/options that control the format and the behavior of the input field. For your convenience I have created a HTML5 data and option code generator - all you need to do is select the desired option and the code will be shown at the bottom for you to copy and paste into the appropriate document.
back
The basics on getting autoNumeric() up and running with the initialize 'init' method and default settings:
First - include jQuery.js and autoNumeric-1.8.3.js javascript files in the header.
<script src="http://code.jquery.com/jquery-latest.min.js" type="text/javascript"> </script> <script src="autoNumeric-1.8.0.js" type=text/javascript> </script>
Second - insert a form and input field on the HTML document.
- The input type attribute must equal text "<input type="text">". Other input types are NOT supported including HTML 5 number type.
<!-- input field with no HTML 5 data options --> <form> <input type="text" id="someID_defaults"> </form>
Third - in a separate script initialize autoNumeric $('selector').autoNumeric('init').
- Selector - is any valid jQuery selector
// this example uses the id selector & no options passed jQuery(function($) { $('#someID_defaults').autoNumeric('init'); });
Finished - an input field with autoNumeric default settings. Now add CSS styling if desired and test the results.
Changing autoNumeric's default settings using HTML5 data attributes or options is just as easy! First a couple notes prior to proceeding with the examples.
- The loading order for autoNumeric settings is defaults, HTML5 data and then Options. Where defaults are overridden by the HTML5 data and options overrides both the defaults and HTML5 data.
- Understand that different formats are used for HTML5 data attribute and options. Let say you want to change the decimal point from "." period to a "," comma and change the thousand separator from a "," comma to a "." period.
- Options example: $('#someID').autoNumeric('init', {aSep: '.', aDec: ','}); - options are written in "camelCase notation" which is identically to that of the settings defaults. A colon is used to separate the name of the option and the value which should be enclosed with quotes. If multiple options are being sent they should be separated by a comma. All options need to be enclosed braces (curly brackets).
- HTML5 data example: <input type="text" id="someID" data-a-dec="," data-a-sep=",">. By convention the data attribute is written in lowercase. Compound words (example: "aDec") need to be split and separated by a dash. The equal sign separates the name and value. The value should be enclosed with quote marks. If multiple options are being used they each need to have the own data attribute.
- Do not worry - I have created a option/HTML5 code generator below that you just copy and paste.
First - include jQuery.js and autoNumeric-1.8.3.js javascript files in the header.
<script src="http://code.jquery.com/jquery-latest.min.js" type="text/javascript"> </script> <script src="autoNumeric-1.8.0.js" type=text/javascript> </script>
Second - insert a form and input field on the HTML page with the desired HTML5 data.
<!-- input field with HTML 5 data for the German Euro --> <form> <input type="text" id="someID_HTML5" data-a-sign="€ " data-a-dec="," data-a-sep="."> </form>
Third - in a separate script initialize autoNumeric $('selector').autoNumeric('init');
// this example uses the id selector & no options passed jQuery(function($) { $('#someID_HTML5').autoNumeric('init'); });
Completed - an input field with HTML5 data being passed to autoNumeric.
This example uses both HTML5 data and options.
First - repeat step 1 in the previous examples.
Second - repeat step 2 and insert a form and input field on the HTML page with the same HTML5 data.
Third - initialize autoNumeric with options being passed. Please note that setting "aSign" was passed
// this shows options being passed - details on allowed options are below jQuery(function($) { $('#someID_options').autoNumeric('init', {aSign:' EUR', pSign:'s' }); });
Completed - this demonstrates the options overrides both defaults and HTML5 data.
back
Callback function - allows the returned value to be taken as parameter to the default/options settings. You can pass the function via options or HTML5 data and can be used on any of the 15 options.
The following shows the the function being passed via options with the mDec setting.
<script type="text/javascript"> /* the callback function must be defined prior to initiating autoNumeric */ var functionName = function(){ /* your code here */ var value = 4; /* example only */ return value; } /* initiates autoNumeric and passes a function */ $('selector').autoNumeric('init', {mDec: functionName}) </script>
This shows the the function name being passed via HTML5 data with the mDec setting.
<script type="text/javascript"> /* the callback function must be defined prior to initiating autoNumeric */ /* please note that the function is namespaced and defined prior to autoNumeric being initiated */ $.fn.autoNumeric.functionName = function(){ /* your code here */ var value = 4; /* example only */ return value; } /* initiates autoNumeric and passes a function */ $('selector').autoNumeric('init', {mDec: functionName}) </script> <input type="text" data-m-dec="functionName"/>
back
back back back
'getString' method - this basically uses jQuery's .serialize() method which creates a text string (URL-encoded notation) from a set of form elements that is ready for submission. The extra step taken here is the string is split and iterated through and the formatted values are replaced with unformatted values. The string is then joined back together and returned.
Proper format for the 'getString' method.
- $(selector).autoNumeric('getString');
Please note the following
- The 'getString' method name is required "$(selector).autoNumeric('getString');".
- Options and value are NOT accepted.
- The "getString" method does NOT validate the form inputs. It will return what has been entered including empty strings.
- If your selector includes non-autoNumeric fields they will be returned untouched.
- Only "successful controls" are serialized to the string. Please read more about jQuery's .serialize() method to see if "getString" method will work for your application.
- Returns a string
Demo
- To view the method results open your browser's console (you may need to reload the page).
- Press the "getString" button. Two strings should be appear.
- The first string was created to show jQuery's .serialize() method with no modifications.
- The second string is from the "getString" method.
Note
- The 'getString' method returns numbers
Warning
Calling the 'getSting' method prior to the 'init' will cause a error message to be thrown the the Javascript console.
'getArray' method - this basically uses jQuery's .serializeArray() method which returns a Javascript array of objects, ready to be encoded as a JSON string. The extra step taken here is the the object array is iterated through and formatted values are replaced with un-formatted values and returned.
Proper format for the 'getArray' method.
- $(selector).autoNumeric('getArray');
Please note the following
- The 'getArray' method name is required "$(selector).autoNumeric('getArray');".
- Options are NOT accepted.
- An object is returned. If you want this converted to a valid JSON string to submit to the server you should consider JSON2.js as I did in this demo.
- The "getArray" method does NOT validate the form inputs. It will return what has been entered including empty strings.
- If your selector includes non-autoNumeric fields they will be returned untouched.
- Only "successful controls" are serialized to the string. Please read more about jQuery's .serializeArray() method to see if "getArray" method will work for your application.
Demo
- To view the "getArray" method open your browser's console (you may need to reload the page). Fill in the inputs above and then press the "getArray" button. The following lines should be appear so you can see the differences.
- The first string was created to show jQuery's .serializeArray() method with no modifications.
- The second object is from the "getArray" method
- The third line takes the return object from the "getArray" method and converts to a valid JSON string via JSON.stringify.
Note
- jQuery does not have a native stringify method.
Warning
Calling the 'getArray' method prior to the 'init' will cause a error message to be thrown the the Javascript console.
back
Browsers supported - limited testing conducted on the following:
- Chrome 23.0.1271.97
- Firefox 17.0.1
- IE 9.0.8112.16421
- Opera 12.12
- Safari 5.0.3 Mac
- Safari 5.1.7 WIN
- iPad2
- iPhone 4
- Andriod 4 (phone)
Known issues
- HTML 5 input when type is set to number <input type="number" id="someID">. Type must best set to "text" to have autoNumeric function properly.
- Android mobile browsers prior to Android version 4.
Change notes on 1.8.3
- Added input[type=hidden] support - this was done mainly for backward compatibility.
- The "get" method now returns a numeric string - this also was done for backward compatibility.
History
Version 1.8.2
- Allowed dGroup settings to be passed as a numeric value or text representing a numeric value
- Allows input fields without type that defaults to type text - Thanks Mathieu DEMONT
Version 1.8.1
- Modified the 'get' method so when a field is blank and the setting wEmpty:'empty' a empty string('') is returned.
Version 1.8.0
- autoNumeric() 1.8.0 is not compatible with earlier versions but I believe you will find version 1.8.0's new functionality and ease of use worth the effort to convert.
- Changed autoNumeric structure to conform to jQuery's recommended plugin development.
- Created a single namespace and added multiple methods.
- Added HTML 5 data support and eliminated the metadata plugin dependency.
- Added support for the following elements: 'DD', 'DT', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'input', 'LABEL', 'P', 'SPAN', 'TD', 'TH'.
- Changed the settings loading order to defaults, HTML5 data then options. Now the defaults settings are overridden by HTML5 data and options overrides both defaults & HTML5 data.
- Added "lZero" to the settings to control leading zero behavior.
- Added "nBracket" to the settings which controls if negative values are display with brackets.
- Changed the callback feature to accept functions only.
- Improved the 'aForm' behavior that allows values to be automatically formatted on page ready.
- Fixed the issue for numbers that are less than 1 and greater than -1 and have six or more decimal places.
- Fixed 'crtl' + 'a' (select all) and 'ctrl' + 'c' (copy) combined key events.
- Fixed a IE & FF bug on readonly attribute.
- General code clean up
- Fixed ctrl + a (select all) and ctrl + c (copy) key events.
Version 1.7.4-B
- Fixed caret routine for IE (oops mistake).
Version 1.7.4
- Depreciated the use of "options" in the autoNumericGet() & autoNumericSet() public functions.
- Bug fix - prevent multiple instances of autoNumeric from being loaded.
- Bug fix - corrected loop through a array using "for( i in left_ar )" - thanks Peter Kovari.
- Eliminated the use of ++ & -- to iterate and the "continue" statement.
- General code maintenance.
Version 1.7.2 & 1.7.3
- Bug fix - limited releases.
Version 1.7.1 click here to view
- Bug fix - change event is corrected.
Version 1.7.0
- Precision control of minimum & maximum values to the nth decimal places!
- The number of decimal places and negative sign are now set via the min/max values. Also positive and negative values are easily toggled from any caret position within the input field.
- Public functions $('selector').autoNumericGet({options}) & $('selector').autoNumericSet(value, {options}) to strip and format values that use jQuery's selector format.
- Callback function that is very powerful.
- Options for input behavior including, padding, cell to be empty or always display the currency sign or zero.
Version 1.6.2 click here to view
- Bug fix - on setting the caret position.
- General code clean up.
Version 1.6.1
- Bug fix - that prevented a decimal character from being entered when only the currency symbol is present.
- Bug fix - when entering a decimal character when the thousand separator is a space ' ' and the currency symbol has a space and in placed as a suffix.
Version 1.6.0
- Eliminated the hard coded space between the currency symbol and numeric characters.
- Spacing between the currency symbol and numeric characters is now determined by the developer (you).
- Re-wrote the routine that handles the decimal character key events.
- Re-wrote the routine that handles the numeric character(s) key events.
- Re-wrote the set caret position routine.
- Added focus out event
- Fixed leading zero when no numeric characters were entered to the left of the decimal point
- Currency symbol and padding are only displayed when a numeric and/or decimal character have been entered - special thanks to B. Cull for his contribution.
Version 1.5.4
- Added padding option - see aPad above for greater details - special thanks Jonas Johansson for his contribution
- Fixed select all (ctrl + a)
- Fixed caret position when a negative sign is added when a currency symbol is present
Version 1.5.3
- Corrected issues with id's that used special characters - Thanks Anthony & Evan C.
- MAC command key is now recognized (version 1.5.2) - Thanks Bart B.
- Changed the blur event to change - this corrected the onchange not being thrown in IE7/IE8 - Thanks Javier P.
Version 1.5.1
- Corrected return key support (thanks Bart B.)
Version 1.5.0
- Added currency symbol support
- Added meta data support and eliminated alt code that was used in previous versions.
Version 1.4.5 (Last version using the alt code) click here to view
- Correct caret position when one digit was present (thanks Bart V.)
Version 1.4.3
- Added set caret routine to the keyup event. Keeps the caret in the proper place after the format routine
- Added focus event handler - corrected issues with pages that have multiple formats
- Corrected the focus control when client tabs in to the field on the keyup event (reverted to earlier version)
- Corrected the Caps Lock key issue on the keyup event.
- Change the leading zero routine to the above
- Added routine that handles values that exceed the maximum
- Corrected the browser hang up issue when no thousand separator is used in Chrome and Safari
Versions 1.3.3 to 1.4.2: (requested custom versions)
Version 1.3.2:
- Changed keyup event and replaced e.keyCode
- Corrected a "bad assignment" - JSLint Gotch Yah
Version 1.3.1:
- Allow input to remain blank no value stays no value
Version 1.3.0:
- Added keyDown keyCode support
- Corrected "tab in" focus IE issue - you can now over write or delete the hi-lighted portion of the input value even when field has reached max length. Thanks Bart
- Corrected the "tab out" issue in Opera. Version 1.3.2:
- Eliminated the Opera specific call that was meant to handle a paste event
- jQuery 1.4 compatible
Version 1.2.0 - 1.2.2: (please do not use and upgrade to 1.3.0 or greater)
- Removed the Dom Calls and replaced with jQuery
- Added Home and End (e.keyCode 35 & 36) support to the keyup event (thanks JPM USA)
- Paste values are accepted in IE, FF, Chrome & Safari. (Thanks to Josh at Digitalbush)
Version 1.1.0 - abandoned
Original version 1.0.0 - 1.0.2
Please contact me if you have questions, comments and or suggestions at:
bob{@}decorplanit.com (remove brackets)
Created & maintained by Bob Knothe
Copyright "All rights reserved"