v1.9 documentation

Documentation for v1.9 ( DEPRECATED)

Disclaimer 1: v1.9 has been superseeded by v4.* and is not longer supported. Please consider switching to the latest version.

Disclaimer 2: This documentation may be outdated.
Please consider using the Readme that always has up-to-date information.

Changing the defaults options

The complete list of options are below

There are multiple ways for changing the options. To format "123456789.00" to "€ 123.456.789,00" you could do the following:

options - pass when initializing autoNumeric

$(document).ready(function(){
   $(selector).autoNumeric("init", {
        digitGroupSeparator: '.',
        decimalCharacter: ',', 
        currencySymbol: '€ '
    });
});

HTML5 data - *By convention the data attribute is written in lower-case. Compound words (example: "decimalCharacter") 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.

<input type='text' name="someName" value="1234.56" data-a-sep="." data-a-dec="," data-a-sign="€ "/>

$.extend method - in this example ASP.NET current culture settings are passed.

note: - this can change defaults globally

<script type="text/javascript">  

    $(document).ready(function() {          
        $.extend($.fn.autoNumeric.defaults, {              
            digitGroupSeparator: '@System.Threading.Thread.CurrentThread.CurrentCulture.NumberFormat.NumberGroupSeparator',              
            decimalCharacter: '@System.Threading.Thread.CurrentThread.CurrentCulture.NumberFormat.NumberDecimalSeparator',
                        currencySymbol: '@System.Threading.Thread.CurrentThread.CurrentCulture.NumberFormat.CurrencySymbol'
        });      

        $('selector').autoNumeric('init'); 

    });

</script>

Callback function - this example changes the number of decimal places.

 <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', { decimalPlaces: functionName }) 

---

Values - locale formats that autoNumeric can properly handle as a numeric value

By default autoNumeric formats the default values on page ready. The values should be sent as text. autoNumeric supports the use on locale formats with the following rules:

• Numeric values should be send as text
• The first comma or period will be considered the decimal character
• Any additional commas or periods will cause an error to be thrown
• The sign (minus only) can be proceeding or trailing
• Currency symbols or other non-numeric characters will throw an error
• Quick visual guide:

value / text	valid?
"123456"	true
"123456.78"	true
"123456,78"	true
"-123456"	true
"-123456.78"	true
"-123456,78"	true
"123456-"	true
"123456.78-"	true
"123456,78-"	true
"123,456.78"	false
"123.456.78"	false
"-123456.78-"	false
"€ 123456.78"	false
"2.034E23"	false

Default values and values being "set" need to fall with the min/max range.

If you do not want the default values formatted on set the option from "formatOnPageLoad: true" to "formatOnPageLoad: false"

---

ASP.NET default value and post-back

During page load / re-load autoNumeric compares the value of the input "$this[0].value" and the "$this.prop('defaultValue')" value. If they are equal and "formatOnPageLoad: true" the value is formatted.

What happens during ASP.NET form post-back is the input tag is re-rendered. An example Page loaded

<input type='text' name="someName"  id="someID" class='someClass' value="" />

// user enters "1234.56" => "1,234.56" with default settings
// during post-back the input is re-rendered and is now showing the new default value. 

<input type='text' name="someName"  id="someID" class='someClass' value="1,234.56" />

Once the page is reloaded on post-back and autoNumeric compares $this[0].value" and the "$this.prop('defaultValue')" and sees they are equal it attenpts to format the values. From the above valid value table the "1,234.56" would be invalid.

There are two options that can handle the postback event "formatOnPageLoad" & "defaultValueOverride":

1) "formatOnPageLoad option" - this option controls if default values are formatted on page load. By default it is set to "formatOnPageLoad: true"

Change the "formatOnPageLoad" option to "formatOnPageLoad: false" - this can be done when initalizing "init" the element as an option or as HTML5 data attribute

If there are no default value(vs) simply initialize 'init' the element

$('selector').autoNumeric('init', {formatOnPageLoad: false});    

If there is a default value you will need to pre-format the default value as shown

<!-- it is important that a preformatted default values match the options/settings.
      mismatches could cause errors -->
<input type='text' name="someName" value="1,234.56"/>

2) "defaultValueOverride" option was created to help ASP.NET postabck and is used if "formatOnPageLoad: true" is set 'true'.

Note: "defaultValueOverride" option should be the same value as the default value

<input type='text' name="someName" value="1234.56"/>

// 'defaultValueOverride' is the value of the default value above 
$('selector').autoNumeric('init', {defaultValueOverride: "1234.56"});       

Please note that "formatOnPageLoad" and "defaultValueOverride" can be set by either {options} or HTML5 data attribute

---

Min / Max settings and decimal places

The minimum and maximum values and decimal places are set via minimumValue: '-9999999999999.99' and maximumValue: '9999999999999.99' option. The decimal places are determined be the number of characters following the "." decimal point.

minimumValue:	maximumValue:	decimal places
"0"	"9999999999"	0
"0.00"	"99999999.99"	2
"0.00"	"9999999999"	2
"-9999999"	"9999999.999"	3

Notes: - minimumValue should always be a lower value than maximumValue! - minimumValue and maximumValue can be both positive or negative but do so with caution. - If the range of the minimumValue & maximumValue is small or you make them numbers other then "9" nines (example "1000) you could create a situation where the uses will need to delete characters before the can obtain the minimumValue / maximumValue limits.

---

Additional documentation for v1.9 can be found on the old website.