Easy Numbers and Currency Formatting Plugin - autoNumeric

Easy Numbers and Currency Formatting Plugin - autoNumeric
File Size: 188 KB
Views Total:
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   

autoNumeric is an useful jQuery plugin for international currency formatting as well as numbers formatting. It supports almost all the major international numeric formats and currency signs used in Europe, North and South America, Asia and India.

You might also like:

How to use (Use both HTML5 data and options.):

1. Include the latest jQuery library and autoNumeric.js

<script src="http://code.jquery.com/jquery-latest.min.js" type="text/javascript"> </script>
<script src="autoNumeric-1.8.8.js" type=text/javascript> </script>

2. Create a input field with HTML5 data for the German Euro

<form>
  <input type="text" id="DEMO" data-a-sign="€ " data-a-dec="," data-a-sep=".">
</form>

3. Call the plugin

<script>
 jQuery(function($) {
      $('#DEMO').autoNumeric('init');    
  });
</script>

4. Options and defaults. You can also pass the following options via HTML5 data attributes.

/** allowed thousand separator characters
* comma = ","
* period "full stop" = "."
* apostrophe is escaped = "\""
* space = " "
* none = ""
* NOTE: do not use numeric characters
*/
aSep: ",",

/** when true => when the input has focus only the decimal character is visible
*/
nSep: false,

/** digital grouping for the thousand separator used in Format
* dGroup: "2", results in 99,99,99,999 India's lakhs
* dGroup: "2s", results in 99,999,99,99,999 India's lakhs scaled
* dGroup: "3", results in 999,999,999 default
* dGroup: "4", results in 9999,9999,9999 used in some Asian countries
*/
dGroup: "3",

/** allowed decimal separator characters
* period "full stop" = "."
* comma = ","
*/
aDec: ".",

/** allow to declare alternative decimal separator which is automatically replaced by aDec
* developed for countries the use a comma "," as the decimal character
* and have keyboards\numeric pads that have a period 'full stop' as the decimal characters (Spain is an example)
*/
altDec: null,

/** aSign = allowed currency symbol
* Must be in quotes aSign: "$"
* space to the right of the currency symbol aSign: '$ '
* space to the left of the currency symbol aSign: ' $'
*/
aSign: "",

/** pSign = placement of currency sign as a p=prefix or s=suffix
* for prefix pSign: "p" (default)
* for suffix pSign: "s"
*/
pSign: "p",

/** placement of negative sign relative to the aSign option l=left, r=right, p=prefix & s=suffix
* -1,234.56  => default no options required
* -$1,234.56 => {aSign: "$"}
* $-1,234.56 => {aSign: "$", pNeg: "r"}
* -1,234.56$ => {aSign: "$", pSign: "s", pNeg: "p"}
* 1,234.56-  => {pNeg: "s"}
* $1,234.56- => {aSign: "$", pNeg: "s"}
* 1,234.56-$ => {aSign: "$", pSign: "s"}
* 1,234.56$- => {aSign: "$", pSign: "s", pNeg: "r"}
*/
pNeg: "l",

/** Additional suffix
* Must be in quotes aSuffix: 'gross', a space is allowed aSuffix: ' dollars'
* Numeric characters and negative sign not allowed'
*/
aSuffix: "",

/** override min max limits'
* oLimits: "ceiling" adheres to vMax and ignores vMin settings
* oLimits: "floor" adheres to vMin and ignores vMax settings
* oLimits: "ignore" ignores both vMin & vMax
*/
oLimits: null,

/** maximum possible value
* value must be enclosed in quotes and use the period for the decimal point
* value must be larger than vMin
*/
vMax: '9999999999999.99',

/** minimum possible value
* value must be enclosed in quotes and use the period for the decimal point
* value must be smaller than vMax
*/
vMin: "-9999999999999.99",

/** Maximum number of decimal places = used to override decimal places set by the vMin & vMax values
* value must be enclosed in quotes example mDec: "3",
*/
mDec: null,

/** Expanded decimal places visible when input has focus - example:
* {eDec: "5"} and the default 2 decimal places with focus "1,000.12345" without focus "1,000.12" the results depends on the rounding method used
* the "get" method returns the extended decimal places
*/
eDec: null,

/** Scaled number displayed when input does not have focus example with the following:
* {aScale: ["1000", "0", "K"]}  => with focus "1,000.00" without focus "1K"
* ["divisor", "decimal places", "symbol"]
* divisor value - does not need to be whole number - please understand that Javascript has limited accuracy in math
* the "get" method returns the full value and scaled value.
* decimal places "optional" when not in focus - if omitted the decimal places will be the same when the input has focus
* Symbol "optional" displayed when the input does not have focus - NOTE: if a symbol is used you MUST also specify the decimal places
* value must be enclosed in quotes example mDec: "3"
*/
aScale: null,

/** Set to true to allow the eDec value to be saved with sessionStorage
* if ie 6 or 7 the value will be saved as a session cookie
*/
aStor: false,

/** method used for rounding
* 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: "N05" Rounds to the nearest .05 => same as "CHF" used in 1.9X and still valid
* mRound: "U05" Rounds up to next .05
* mRound: "D05" Rounds down to next .05
*/
mRound: "s",

/** controls decimal padding
* aPad: true - always Pad decimals with zeros
* aPad: false - does not pad with zeros.
* aPad: `some number` - pad decimals with zero to number different from mDec
* thanks to Jonas Johansson for the suggestion
*/
aPad: true,

/** places brackets on negative value -$ 999.99 to (999.99)
* visible only when the field does NOT have focus the left and right symbols should be enclosed in quotes and separated by a comma
* nBracket: null - (default)
* nBracket: '(,)', nBracket: '[,]', nBracket: '<,>' or nBracket: '{,}'
*/
nBracket: null,

/** Displayed on empty string ""
* wEmpty: "focus" - (default) currency sign displayed and the input receives focus
* wEmpty: "press" - currency sign displays on any key being pressed
* wEmpty: "always" - always displays the currency sign only
* wEmpty: "zero" - if the input has no value on focus out displays a zero "rounded" with or with a currency sign
*/
wEmpty: "focus",

/** controls leading zero behavior
* lZero: "allow", - allows leading zeros to be entered. Zeros will be truncated when entering additional digits. On focusout zeros will be deleted.
* lZero: "deny", - allows only one leading zero on values less than one
* lZero: "keep", - allows leading zeros to be entered. on focusout zeros will be retained.
*/
lZero: "allow",

/** determine if the default value will be formatted on page ready.
* true = automatically formats the default value on page ready
* false = will not format the default value
*/
aForm: true,

/** determine if the select all keyboard command will select
* the complete input text or only the input numeric value
* if the currency symbol is between the numeric value and the negative sign only the numeric value will selected
*/
sNumber: false,

/** helper option for ASP.NET postback
* should be the value of the unformatted default value
* examples:
* no default value="" {anDefault: ""}
* value=1234.56 {anDefault: '1234.56'}
*/
anDefault: null,

/** removes formatting on submit event
* this output format: positive nnnn.nn, negative -nnnn.nn
* review the 'unSet' method for other formats
*/
unSetOnSubmit: false,

/** allows the output to be in the locale format via the "get", "getString" & "getArray" methods
* null => nnnn.nn or -nnnn.nn default
* ","  => nnnn,nn or -nnnn,nn can als be "-,"
* ".-" => nnnn.nn or nnnn.nn-
* ",-" => nnnn,nn or nnnn,nn-
*/
localeOutput: null,

/** error handling function
* true => all errors are thrown - helpful in site development
* false => throws errors when calling methods prior to the supported element has been initialized be autoNumeric
*/
debug: false

Change Logs:

v2.0.0 beta5 (2016-12-02)

  • Prepare the code base for future Jasmine tests
  • Add initial babel support
  • Add uglify and npm-build-process support
  • Merge the 2.0 changes into master
  • Add npm support for building the minified version
  • Multiple small fixes
  • Fixed paste event on both context menu and ctrl-v
  • Fixed tab in key select all and deletion
  • Fixed issue with Vue.js 2.0 
  • Fixed context menu paste event
  • switch from jsLint to jsHint
  • Fixed tab in key 
  • Fixed the cursor position when tabbing in Chrome
  • Fixed the destroy method
  • Fixed the readme file to show correct $.extend defaults
  • Fixed bug in unSetOnSubmit option to handle non autoNumeric controlled inputs
  • Fixed bug in get method
  • Mods to the trailing minus sign code
  • Added UMD support
  • Modified & improved the shim for throwing the input event
  • Added option unSetOnSubmit to unformat input on the submit event
  • Added option debug to turn on and off error being thrown
  • Added support for arbitrary-precision decimal arithmetic.
  • Added support for trailing minus signs
  • Added rounding methods for currencies with smallest coin being $0.05
  • Added modified sNumber option that selects only numbers ctr & a keys thanks Zayter
  • Added support for return values to have locale formats
  • Added debug option to turn off errors
  • Added option anDefault to help ASP.NETR postback errors
  • Modified the wEmpty option
  • Modified the init && set methods
  • General code clean up
  • Modified the set, getString & getArray methods
  • Modified the nBracket function
  • Fixed the update method when it is called during the onfocus event
  • Fixed the getString & getArray methods when multiple inputs share the same name
  • Fixed bug in ctrl + v paste event to properly round
  • Merged a mod that makes the defaults public and overridable
  • Fixed page reload when the thousand separator is a period .
  • Major code reorganization with ES6 module, Webpack, Karma & Jasmine.
  • Fixed NSep option and mad null the defaults for scaled options
  • Rename the 'localOutput' setting to 'outputType', and add an option 'number' that makes 'getLocalized' always return a Number, instead of a string.

v1.9.46 (2016-09-12)

  • multiple fixes

v1.9.45 (2016-06-14)

  • Modified the "set" method to handle NaN

v1.9.44 (2016-06-07)

  • Fixed destroy method
  • Added Typings support

v1.9.43 (2015-12-20)

  • UMD support

v1.9.42 (2015-11-21)

  • Fixed bug when pasting using ctrl & v keys

v1.9.41 (2015-11-04)

  • Fixed bug that allowed two currency symbols

v1.9.40 (2015-10-26)

  • Fixed bug when pasting value and the decimal seperator is a comma ","

v1.9.39 (2015-07-18)

  • Fixed 'aForm'option.

v1.9.38 (2015-07-13)

  • Added / fixed option to address asp.Net WebForm postback.
  • please see the readme section on default settings & options

v1.9.37 (2015-05-25)

  • Added / fixed support for asp.Net WebForm postback.
  • 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, the following HTML data attribute is REQUIRED (data-an-default="same value as the value attribute") to prevent errors on postback

v1.9.36 (2015-05-11)

  • Rewrote the "getString" & "getArray" methods to index successful elements and inputs that are controlled by autoNumeric. This ensures the proper input index is used when replacing the formatted value.
  • Added support for FireFox for Mac meta key "keycode 224"

v1.9.35 (2015-04-20)

  • Revert 'set' back to version 1.9.34

v1.9.34 (2015-03-09)

  • Modified the 'set', 'getString' & 'getArray' methods
  • Modified the 'nBracket' function
  • General code clean up   

v1.9.33 (2015-02-16)

  • Fixed bug in "ctrl + v" paste event
  • Fixed bug when the "update" method is called in the "onfocus" event
  • Fixed the "getString" & "getArray" methods when multiple inputs share the same name

v1.9.30 (2015-01-13)

  • Fixed in 1.9.29 too interest in Ohio State vs. Oregon

v1.9.29 (2014-12-08)

  • Fixed focusout event when the thousand separator is a period "." and only one is present "x.xxx" with not other alpha characters.
  • Fixed bug introduced in 1.9.27.

v1.9.27 (2014-12-08)

  • Merged a mod that makes the defaults public and over ridable.
  • Fixed page reload when the thousand separator is a period "."

v1.9.26 (2014-10-08)

  • Fixed "getString" & "getArray" methods when multiple forms having some shared named inputs

v1.9.25 (2014-08-02)

  • Fixed mRound option "round-half-even"
  • Modified the "set" method to not throw an error when trying to "set" a null value

v1.9.24 (2014-06-30)

  • Changed the case on the supported elements
  • This was required because jQuery.prop('tagName') returns upper-case on html5 pages and returns lower-case on xmhtl pages

v1.9.22 (2014-04-21)

  • fix bug and code cleanup

v1.9.21 (2014-04-01)

  • Mod to checkValue function to handle empty string - thanks to jedichenbin.
  • If CHF rounding is used decimal is automatically set to 2 places

v1.9.20 (2014-03-31)

  • increase vMax default value

v1.9.19 (2014-03-24)

  • fix format of text elements on pageload

v1.9.18 (2013-12-04)

  • fix format of text elements on pageload

v1.9.17 (2013-09-28)

  • Fixed leading zero on page load

v1.9.14 (2013-09-12)

  • Bug fix on checkValue function

v1.9.14 (2013-8-6)

  • fixed bugs

v1.9.11 (2013-6-23)

  • fixed "get" method

v1.9.11 (2013-6-23)

  • Another mod to the 'set' method.
  • Fixed the 'set' method to handle page reload using the back button.

v1.9.9 (2013-6-23)

  • Fixed how non-input tags default value is handled. When the default is an empty string and aSign is not empty the return value is now and empty string.
  • Modified how default values are handled when the decimal character equals ',' comma. Your default value can now use either a a period '.' or comma ',' as the decimal separator
  • Modified the caret placement on focusin (tab in). If only the currency sign is visible the caret is placed in the proper location depending on the sign placement (prefix or suffix).

v1.9.8 (2013-5-20)

  • Changed bind / unbind to on / off.
  • added lastSetValue to settings - this saves the unrounded value from the set method - $('selector').data('autoNumeric').lastSetValue; - helpful when you need to change the rounding accuracy

This awesome jQuery plugin is developed by BobKnothe. For more Advanced Usages, please check the demo page or visit the official website.