Author: Robert Knothe
Contact: bob{@}decorplanit.com (remove brackets)
Web site: http://www.decorplanit.com/plugin/ complete with detailed examples and option/html 5 data code generator/
github: https://github.com/BobKnothe/autoNumeric
jQuery: http://plugins.jquery.com/autoNumeric/
autoNumeric 1.9.46 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 attribute or passed as an argument. These settings can easily be changed at any time using the new ‘update’ method or via the callback feature.
Seven built in methods and fifteen options gives you the flexibility needed to use autoNumeric to its maximum potential (details below).
Examples of autoNumeric's flexibility:
Key features and general notes:
Elements supported:
- The input types supported:
- <input type="text">, <input type="hidden"> & <input> no type attribute.
- Other input types are NOT supported including HTML 5 number type.
- Non-input tags supported:
- 'b', 'caption', 'cite', 'code', 'dd', 'del', 'div', 'dfn', 'dt', 'em', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'ins', 'kdb', 'label', 'li', 'output', 'p', 'q', 's', 'sample', 'span', 'strong', 'td', 'th', 'u', 'var'
Default settings, options and HTML 5 data:
- The default settings can be changed via options or HTML 5 data attribute
- $(selector).autoNumeric('init', {aSep: '.', aDec: ',', aSign: '€ '}); - example using options
- Options can be sent as a variable:
- var myOptions = {aSep: '.', aDec: ',', aSign: '€ '};
- $(selector).autoNumeric('init', {aSep: '.', aDec: ',', aSign: '€ '});
- <input type="text" id="someID" class="someClass" data-a-sign="€ " data-a-dec="," data-a-sep="."> - example of HTML 5 data
- Order of precedence: defaults, HTML 5 (overides defaults), options (overides defaults and HTML5 data).
- FYI - my web site has a easy to use code genterator
asp.Net WebForm requirements (new in version 1.9.37):
- During postback the default value is re-rendered showing the updated value, because autoNumeric cannot distinguish between a page re-load and asp.net form postback so the following option or HTML5 data attribute is NEEDED (data-an-default="same value as the value attribute") to prevent errors on postback.
- Example: if the value="1234.56" then anDefault option should be {anDefault"1234.56} or HTML5 data-an-default="1234.56"
Callback function:
- Callback function is supported and can be done via options or HTML5 data.
Defaults values on autoNumeric controlled elements:
- The option "aForm" controls how default values are handled on page ready.
- When "aForm" is set to "aForm: true" the defaults values will be formatted on page ready.
- Default values format: '99999.99' - see more detail below.
- If the default value falls outside the min/max range an empty string will be returned
- When "aForm" is set to "aForm: false" the values will not formatted on page ready
- The input field values will be formatted on the first keypress event is fired for that element
Defaults values formats accepted when aForm = true:
- Only one decimal characters is allowed - one locale decimal chartacters are accepted
- Examples:
- 1234.56 => OK
- -1234.56 => OK
- 1234,56 => OK
- -1234.56 => OK
- 1,234.56 => fails
- 1.234,56 => fails
Precision control of minimum & maximum values:
- Controlled by "vMin" & "vMax" settings / options
Currency signs:
- Most currency symbols are supported and can be placed as a prefix or suffix.
Default settings & options - for a detailed info please see http://www.decorplanit.com/plugin/
- aSep: ',' - controls the thousand separator (note - the thousand & decimal separators can not be the same)
- aSep: '\'' apostrophe (note: the apostrophe is escaped)
- aSep: '.' period
- aSep: ' ' space
- aSep: '' none
- dGroup: '3' - controls the digital grouping - the placement of the thousand separator
- dGroup: '2' produces 22,22,22,333 (India's lakhs format on values below 1 billion)
- dGroup: '4' produces 4,4444,4444 used in some Asian country's
- aDec: '.' - controls the decimal (note - the thousand & decimal separators can not be the same)
- aDec: ',' comma
- altDec: null - altDec allows you to declare an alternative key to enter the decimal separator assigned in aDec.
- developer sellectable - example: {aSep: '.', aDec: ',', altDec: '.'} would allow the period on the numeric pad to enter the decimal ","
- aSign: '' - desired currency symbol (examples: € or EUR). Note: other symbols can be used, such as %, °C, °F, km/h & MPH
- developer sellectable - example: {aSign: '€ '} note numeric character not allowed.
- pSign: 'p' - controls the placement of the currency symbol (the default placement is set as a prefix
- pSign: 's' - place the sign as a suffix
- vMin: '0.00' - values can be whole numbers, floating point, positive, zero or negative.
- vMax: '999999999.99' - values can be whole numbers, floating point, positive, zero or negative.
- mDec: null - overrides the number of decimal places that are set by the vMin & vMax values
- mRound: 'S' - controls the rounding method
- mRound: 'S' Round-Half-Up Symmetric (default)
- mRound: 'A' Round-Half-Up Asymmetric
- mRound: 's' Round-Half-Down Symmetric (lower case s)
- mRound: 'a' Round-Half-Down Asymmetric (lower case a)
- mRound: 'B' Round-Half-Even "Bankers Rounding"
- mRound: 'U' Round Up "Round-Away-From-Zero"
- mRound: 'D' Round Down "Round-Toward-Zero" - same as truncate
- mRound: 'C' Round to Ceiling "Toward Positive Infinity"
- mRound: 'F' Round to Floor "Toward Negative Infinity"
- mRound: 'CHF' Rounding for Swiss currency "to the nearest .00 or .05"
- aPad: true - pads the decimal places with zeros.
- aPad: false - no padding
- nBracket: null - controls if negative values are display with brackets when the input does NOT have focus.
- nBracket: '(,)' Parentheses - visable only on 'focusout'
- nBracket: '[,]' Brackets - visable only on 'focusout'
- nBracket: '{,}' Braces - visable only on 'focusout'
- nBracket: '<,>' Angle brackets - visable only on 'focusout'
- wEmpty: 'empty' - field allowed to be empty
- wEmpty: 'zero' input field will have at least a zero value
- wEmpty: 'sign' the currency symbol is always present
- lZero: 'allow' - allows leading zeros as you type but are removed on focusout event
- lZero: 'deny' leading zeros not allowed.
- lZero: 'keep' leading zeros allowed and will be retained on the focusout event
- aForm: true- formats the default values on page ready (default value decimal must be a period / full stop "####.##")
- aForm: false - default value are not formatted on page ready.
- anDefault: null - this is a helper option for asp.net only pages with form postback. THe underling issue is asp.net re-renders the page on postback over writing the original default value.
- should be the value of the unformatted default value for the original pag
- examples:
- no default value='' {anDefault: ''}
- value=1234.56 {anDefault: '1234.56'}
| 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'); | |
'init' method - initializes autoNumeric and must be run before other methods can be called.
- $(selector).autoNumeric('init'); "initialized with defaults only"
- $(selector).autoNumeric(); "initialized with defaults only"
- $(selector).autoNumeric('init', {options}); "initialized with options"
- $(selector).autoNumeric({options}); "initialized with options"
- var someOptions = {options}; "options placesd as a variable"
- $(selector).autoNumeric('init', someOptions);
- $(selector).autoNumeric(someOptions);
Note the following:
- Using 'init' is optional on the initialize method all other methods require being declared.
- 'init' is case sensitive.
- The input element is the only tag that supports auto formatting as you type.
- Calling the 'init' method on a element that is already initilized will NOT change the options.
Warning
Calling the "init" method on a element where the decimal point "aDec" and the thousand separator "aSep" are equal will cause an error message to be thrown to the javascript console.
Calling the 'init' methods on a element that is not supported by autoNumeric will cause an error message to be thrown to the javascript console.
'destroy' method - removes autoNumeric from the selected element(s).
- $(selector).autoNumeric('destroy');
Note the following:
- The method name 'destroy' is required
- 'destroy' is case sensitive.
- Options and arguments are NOT accepted.
- Existing values are NOT modified or deleted. If you need to remove the formatting you should do so prior to calling the destroy method via the 'get' method described later.
- The selected fields or elements can be re-initialized at any time.
"update' method - easily update element(s) that have been previously initialized 'init' by autoNumeric.
- $(selector).autoNumeric('update', {options});
Note the following:
- The 'update' method name is required "$(selector).autoNumeric('update', {options});".
- 'update' is case sensitive.
- Options are required and are accepted as an argument or variable (see the 'init' method description).
- The 'update' method will function on all elements supported by autoNumeric.
- The 'update' method can be called repeatably with one or more options at a time.
- Existing values will be stripped, preserved and reformatted to the new settings.
- Values that fall outside the range of the new min/max range will be returned as "0.00" (depending on the number of decimal places and the decimal separator character in the settings).
Warning
Calling the 'update' method prior to the 'init' method will cause a error message to be thrown to the Javascript console.
Calling the "update" method on a element where the decimal point "aDec" and the thousand separator "aSep" are equal will cause an error message to be thrown to the javascript console.
Calling the 'update' method on a element that is not supported by autoNumeric will cause an error message to be thrown to the javascript console.
'set' method - The 'set' method allows you to easily format numbers and numeric strings
Proper format for the 'set' method.
- $(selector).autoNumeric('set', value);
Note the following:
- The 'set' method name is required "$(selector).autoNumeric('set', value);".
- 'set' is case sensitive.
- Options are NOT accepted.
- The 'set' method can be used on any element that are supported by autoNumeric.
- The value can be sent as a string or variable
- $(selector).autoNumeric('set', '1234.56');
- var someValue = 1234.56 then $(selector).autoNumeric('set', someValue);
- Returns a string
- Values that fall outside the min/max range will not be 'set' and a error message will be thrown to the javascript console.
- Setting "set" a null value returns an empty string.
Calling the 'set' method prior to the 'init' method will cause a error message to be thrown to the Javascript console.
Calling the 'set' method on a element that is not supported by autoNumeric will cause an error message to be thrown to the javascript console.
'get' method - The 'get' method allows you to easily remove the formating from a string on a autoNumeric controlled element and returns a string.
Proper format for the 'get' method.
- $(selector).autoNumeric('get');
Note the following:
- The 'get' method name is required "$(selector).autoNumeric('get');".
- 'get' is case sensitive.
- Options and values are NOT accepted.
- Works on any element supported by autoNumeric.
- Returns only the first element of the selector.
- Returns a string.
Warning
Calling the 'get' method prior to the 'init' method will cause a error message to be thrown to the Javascript console.
Calling the 'get' method on a element that is not supported by autoNumeric will cause an error message to be thrown to the javascript console.
'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');
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
Warning
At least one input must be controled by autoNumeric. If not the 'getSting' method 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');
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.
Warning
At least one input must be controled by autoNumeric. If not the 'getArray' method will cause a error message to be thrown the the Javascript console.
'getSettings' method - this returns an object that shows the autoNumeric settings for the field. You may find this helpful when developing a page.
Proper format for the 'getArray' method.
- $(selector).autoNumeric('getSettings');
Note the following:
- Only the first element from the selector will be returned.
- If the selector points to a non-autoNumeric field or tag "undefined" is returned.
Warning
Calling the 'getSettings' method prior to the 'init' will cause a error message to be thrown the the Javascript console.
Complete documentation and examples can be found at http://www.decorplanit.com/plugin/
Need a custom modification? Cantact me at bob{@}decorplanit.com or github.
Enjoy