autoNumeric() - just another jQuery plugin

autoNumeric() - "just another jQuery™ plugin"

Please visit http://www.decorplanit.com/plugin/ for the latest version

Download: autoNumeric-1.4.5.js - 'heavy on comments'
Download: autoLoader.js

A flexible International numeric formatter, that will automatically place a thousand separator as you type and supports nine different rounding methods. Here are some of the key features on this jQuery™ plugin:

Compatible with jQuery-1.3.2 and higher
I have tried to keep this plugin as unobtrusive and flexible as possible. There is no JS code or calls in the markup. This is not a mask - The client is only allowed to enter numeric values and the decimal separator and/or negative sign if the input field is configured to do so (more on this later).
Supports multiple international numeric formats including those from Australia, Belgium, Bosnia, Canada (English & French), Chinese, Croatia, Czech Republic, Denmark, Estonia, Finland, France, Germany, Hungary, India (lakhs), Israel, Italy, Japan, Korea (North & South), Malaysia, Netherlands, Philippines, Poland, Romania, Serbia, Singapore, Slovakia, Sweden, Switzerland, United Kingdom and United States. The varied formats are controlled by a special; format code placed in the "alt " attribute of the input tag. This plugin allows multiple formats to reside on the same page.
Nine different rounding methods now supported.
Maximum and minimum values are controlled by the number of digits to the left and right of the decimal separator. So if three digits (integers) are assigned to the left and right of the decimal separator the max value is '999.999'. Note: if you delete the decimal separator you create a whole number that exceeds to maximum value - this will reset the value to "".
Field can be positive only or positive & negative.
You now can type multiple leading zero's but the client is still restricted to the number of digits. Note: On the blur event leading zeros on numbers >= 1 & numbers <= -1 will be removed. On numbers < 1 & numbers > -1, one leading zero is allowed.
Paste values are now accepted in IE, FF, Chrome & Safari. (Thanks to Josh at Digitalbush). Opera does not support the paste event.
The public function ($.fn.autoNumeric.Strip) removes the format and if needed converts the decimal character to a decimal point.
The public function ($.fn.autoNumeric.Format) formats values that are sent to the input field.

Implementing:

First - include the jQuery, autoNumeric (above) and autoLoader (above) javascript files in the header.

<script type="text/javascript" src="jQuery.js"></script> (version 1.3.2 or higher)

<script type="text/javascript" src="autoNumeric-1.4.3.js"></script>

<script type="text/javascript" src="autoLoader.js"></script>

Second - input fields can be aligned left or right. This can be done inline or via the auto class.

Third A - assign "auto" to the class of the input field that will use this plugin. This will produce the default settings - see below.

<input id="name" value="" type="text" class="auto" size="25" />

This demonstration shows the defaults when the alt attribute is left blank. The second and third columns show the strip and format functions respectively - more on this later.

Third B - If you want to change the numeric format you will need to add the alt attribute as follows.

<input id="name" value="" type="text" class="auto" alt="p7s3c2S" size="25" />

The format code consists of 7 alpha numeric characters in the following sequence. Please note these are case sensitive. Also note that incomplete codes and incorrect codes can produce undesired results.

First position can be either "p" (default) allows positive value only or '"n" allows positive or negative values.
Second is numeric 0-9 (9 is the default) for the number of digits allowed to the left of the decimal separator. The value "0" allows for 15 integers (that is a big number!).
Third character is used for the digital group separator:
- a = apostrophe
- c = comma (default)
- p = period
- s = space
- x = none

Fourth character is for the thousand digital grouping sequence
- 3 digital grouping 123,123 (default).
- 2 is for 12,12,123 where the first group is 3 followed by groupings of 2. This is used in India.
- 4 will result is in digital groupings of four: 1234,1234 which is used in some far East Countries

Fifth is for the decimal separator

c = comma
p = period (default).

Sixth is numeric (0-9 or a thru Z) is for the number of decimal places:
- 0 will also prevent the decimal character from being entered
- 1-9 the number of decimal places (2 decimal places is the default)
- a-Z lower or upper case. This is to look up the input field with the id = "dp[a-Z]" for the number of places in a input field. This allows the user to set their own decimal places. Multiple decimal fields are allowed but each must have their own unique id (examples dpa, dpb ....).

Seventh is for the Rounding method used:
- S = Round-Half-Up Symmetric (default)
- A = Round-Half-Up Asymmetric
- s = Round-Half-Down Symmetric
- a = Round-Half-Down Asymmetric
- B = Round-Half-Even "Bankers Rounding"
- U = Round Up "Round-Away-From-Zero"
- D = Round Down "Round-Toward-Zero"
- C = Round to Ceiling "Toward Positive Infinity"
- F = Round to Floor "Toward Negative Infinity"

The table below demonstrates the flexibility of the autoNumeric plugin and it's ability to format to different international standards.

The first column allows the user to to enter the value and formats as you type. Several formats are demonstrated.

The 2nd and 3rd columns are populated on the blur event, however you can choose any event or action.

$('input.auto').autoNumeric()	$.fn.autoNumeric.Strip(ii)	$.fn.autoNumeric.Format(ii, iv)
no alt attr	Strip results	no alt attr
"n7c3p3D"		"n7c3p0U"
"p8s3p3a"		"p5c3p3B"
"n7p3caF"		"n7c3paC"
"p7a3c4A"		"p7s3c4A"
"n8x3p0U"		"n8c3p3D"
"p9c4p3S"		"p9p3c3S"
"n9c2p2s"		"n9c3p2s"
Decimal Places:

There are two public functions that are use in the above table that are called from another script.

The second column shows demonstrates the 'Strip' function. If the decimal separator is a comma it will be converted to a period. This takes one argument - the id of input field you want to have the formatting removed as the argument.

$.fn.autoNumeric.Strip('id of the input field that you want to remove the format');

The strip function can be used in the following ways:

var name = $.fn.autoNumeric.Strip('id');
$(selector).val($.fn.autoNumeric.Strip('id'));
Note: id is the id of the input field that is to be striped. This id can e a ' name' a variable.

The third column demonstrates the 'Format' function which requires two arguments. The target input id and the value (non formatted) to be formatted. Again this column is populated on the blur event, however you can choose any event or action.

$.fn.autoNumeric.Format('id of the target input field', 'value to be formatted');

The format function is implemented as follows:

var name = $.fn.autoNumeric.Format('id', 'iv');
$(selector).val($.fn.autoNumeric.Format('id', 'iv'));
Note: id is the id of the input field with the desired format code. iv is the var containing the value to be formatted.

Paste function try pasting various values including some with mixed text and numbers in the first column on the above table. Notes on the pasting abilities and limitations:

Only assigned characters are allowed. Others will be cleared (1P23X4 will result in 1234 with the letter P & X being dropped).
The pasted value can not exceed the input field's assigned limits. Example: If the target input is assigned 8 integers and the user attempts to paste 8 the will result in a 0 value. Also the pasted length can not exceed 25.
The only characters recognized by the field are numeric, decimal separator and the negative sign if allowed. If the pasted value has characters that are not recognized by the input field they will be discarded (Decimal separator = '.' & a pasted value of 'ju1,876.88' = '1876.88' before formatting.
If the number of decimal places exceeds the fields setting it is rounded using the method assigned to that field.
Only one leading zero is accepted (00.00 results in 0.00).
The pasted value inherits the format assigned to the target field. Example: if the target input field has the format code = 'p4p3c2' where the comma is assigned as the decimal separator and you are pasting the following value '1,234,567.99' the result = 1.234,57 after formatting.
If multiple decimal characters are pasted the result will be zero.
If the input field is configured to accept the negative symbol, there must be only one and it must be the first character. If not the result is zero.
Note: Opera does not fire on the paste event - on blur event will format the paste value.

Rounding function - The below table is for testing the rounding methods that are supported. Experiment by entering various values in the upper left input field. The right column will display the 9 different rounding methods. Decimal places can range from 0 to 9.

For further details on rounding the DIY Calculator site is a excellent resource. Additional information can be found on Wikipedia.

Entered value to be rounded		Rounded results
"n8c3p5S"	Round-Half-Up "Symmetric"	"n8c3pbS"
Decimal Places:	Round-Half-Up "Asymmetric"	"n8c3pbA"
	Round-Half-Down "Symmetric"	"n8c3pbs"
	Round-Half-Down "Asymmetric"	"n8c3pba"
	Round-Half-Even "Bankers"	"n8c3pbB"
	Round Up "Away From Zero"	"n8c3pbU"
	Round-Down "Toward Zero"	"n8c3pbD"
	Round to Ceiling "Toward Positive Infinity"	"n8c3pbC"
	Round to Floor "Toward Negative Infinity"	"n8c3pbF"

Version 1.4.5

Corrected caret position when one character was present

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 eariler 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 to set maximum
Corrected the browser handup 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 wright 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 ment 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)

Version 1.1.0 - abandoned

Original version 1.0.0 - 1.0.2 (please do not use and upgrade to 1.3.0 or greater)

Future improvements:

iPhone compatible.
Add support for currency symbols.
Clean the code and reduce the footprint.

Limited testing conducted on the following browsers:

Firefox 3.0.11
Opera 9.62
Safari 4.0 WIN
Chrome 1
IE 7.0.7730.13

Please contact me is you have any questions, comments and or suggestions at bob@decorplanit.com