NumBox jQuery Plugin - Mobile-Friendly HTML5 Numeric Input

May 16, 2014 in Validation 4753 views

Download

Overview
Documents

User Rating: 4.6/5 ( 3 votes)

Your Rating:

Features

Input filtering and formatting of HTML5 type="number" inputs.
Helps ensure numeric keyboard appears on mobiles for entry.
Assists in ensuring input box stays in viewport during entry.
Does not rely on spinners, which can optionally be hidden.
Mobile-first design also works on desktops, including IE6+.
Extremely light weight at 2.62KB of code gzipped.
Provides both formatted value and numeric value.
Provides optional event hooks for your own code.
As-you-type real-time validation doesn’t rely on browser.
Custom formatting of displayed numbers.
Localizable: currency symbol, location, etc.
Fully compatible with PhoneGap and Apache Cordova.
Fully compatible with jQuery Mobile & other frameworks.
Requires either jQuery 1.7+ or Zepto.js v1.0+.
Free license for both commercial and non-commercial use.

Source: numbox.org

1. INCLUDE JS AND CSS FILES

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js" type="text/javascript"></script>
<script src="jquery.numbox-1.1.0.min.js"  type="text/javascript"></script>
<link href="/incjquery.numbox-1.1.0.css" rel="stylesheet" type="text/css" />

2. HTML

<input id="myInput" type="number" value="" placeholder="Please enter a dollar amount" />

3. JAVASCRIPT

$(document).ready(function()
{
        $('#myInput').NumBox();// defaults to dollars
});

4. OPTIONS

Optional Property

Default Value

Usage & Permissible Values

type

'currency'

Handy presets that conveniently save you from having to set multiple properties. Makes your code more readable from a maintenance perspective. Since 'currency' is the default, calling .NumBox() without any parameters is the same as specifying a dollar currency format. If using a credit card type, please note that credit card checksums (Luhn algorithms) are not applied. NumBox allows incomplete numbers to be entered as this is a better user experience than wiping out incomplete entries.

'ccard'	Option best suited for a wide range of credit cards and store cards. Allows up to sixteen digits to be entered. Formats number in a VISA/MasterCard credit card style with a hyphen every four digits.
'ccard-15'	Specifically targets American Express credit cards. Allows up to fifteen digits to be entered, starting with a 34 or 37. Formats number in an American Express credit card style.
'ccard-16'	Specifically targets VISA and MasterCard credit cards. Allows up to sixteen digits to be entered, starting with a 4 or 51 through 55. Formats number in a VISA/MasterCard credit card style with a hyphen every four digits.
'currency'	Shortcut for specifying a decimal number to two decimal places preceded by a dollar sign. Default range is $0.00 to $999,999.99 but can be changed. Defaults can be overridden by specifying additional properties such as the currency symbol, symbol location (to left or right of number) and number of decimal places.
'decimal'	Shortcut for specifying a decimal number defaulting to two decimal places without a currency or other symbol. Default range is 0.00 to 999,999.99. Defaults can be overridden by specifying additional properties.
'ein'	Specifically targets U.S. Employer Identification Numbers that are issued by the U.S. Internal Revenue Service. Allows up to nine digits to be entered. Formats the number with a hyphen after the second digit.
'integer'	Shortcut for specifying an integer number without a currency or other symbol. Default range is 0 to 999,999 but this can be overridden with a new max value.
'percent'	Shortcut for specifying an integer number followed by a percent sign with a range of 0 through 100. Defaults can be overridden if you want decimal places or higher maximum value. Example: $('#increase').NumBox({ type: 'percent', max: 200 });
'ssn'	Specifically targets U.S. social security numbers. Allows up to nine digits to be entered. Formats the number with a hyphen after the third and fifth digits.
'zip' or 'zip5'	Specifically targets 5 digit U.S. ZIP codes. Allows up to five digits to be entered without any formatting.
'zip9'	Specifically targets nine digit U.S. ZIP codes, and allows five digit ZIP codes. Up to nine digits can be entered. Formats the number with a hyphen after the fifth digit.

places

2 (integer)

Specifies how many decimal places. Set to zero if you only want to work with integers.
Not applicable for card types, EINs or SSNs.

min

0 (decimal)

Minimum value permitted. Currently can only be zero.
NumBox will be improved to permit negative numbers in future.
Not applicable for card types, EINs or SSNs.

max

999999.99 (decimal)

Maximum value permitted. Can be adjusted as desired.
Must be the same or higher than the minimum value permitted.
Not applicable for card types, EINs or SSNs.

step

'min'

This is the HTML5 step attribute, which is the amount that the number increments or decrements when you press the up or down spinner buttons, which some browsers provide for type=number inputs. According to the W3C specifications, the step setting should also limit the number itself, but how this is implemented in browsers varies and should not be relied upon. If you plan to hide the spinner buttons, (recommended as a better user experience,) then you can just leave this set to 'min'. Please never set this to 'any' (an HTML5 option) since that stops some mobile devices from displaying a numeric keyboard.

'min'

NumBox will automatically set the step attribute to the lowest possible value based upon the number of decimal places. e.g. For two decimal places, NumBox will automatically set a step value of '0.01'. If you choose to display spinners and the number will have frequent micro-adjustments, this can be a convenient setting.

'decimal #'

You can specify your own step value as a decimal number, but it needs to be contained within quotes. For example a step value of '1' on a NumBox set up as a dollar currency to two decimal places will, theoretically, only allow a number to be incremented or decremented in whole dollars, but when displayed, you will see the .00 cents too as part of the formatting. Note the word "theoretically". Not all browsers behave the same way. So, if you intend to override NumBox, you should test what is appropriate in all of your target environments.

On iPhones and iPads in particular, overriding 'min' with an integer typically cause a numeric keyboard to appear without a decimal point or an option to change keyboards. Similarly overriding 'min' with a number smaller than an integer typically gives you the decimal point in your numeric keyboard.

symbol

'$'

Specifies a symbol to display alongside the number, either immediately to the left or right of the number. Can be set to empty quotes, '', if not desired. Can also contain multiple characters such as 'USD' or even words, as shown in the atomic radius example. Not applicable for card types, EINs or SSNs.

location

'l'

Location of symbol in relation to the number being displayed.
Not applicable for card types, EINs or SSNs.

'l'	Symbol is placed immediately to the left of the number.
'r'	Symbol is placed immediately to the right of the number.

separator

',' or '-'

To make a long number more readable, you may want to segment it into groups of a fixed number of digits with a character separating each segment. This property specifies the character to be used to separate each segment, and, for real numbers, defaults to a comma. For credit cards, EINs and SSNs, the character defaults to a hyphen. You can specify your own character choice, but it cannot be a decimal point or number. Applicable for all types, including credit cards, EINs, SSNs and real numbers. Use empty quotes, '', if you don’t want to see a separating character.

grouping

3 or 4 (integer)

To make a long number more readable, you may want to segment it into groups of a fixed number of digits with a character separating each segment. This property specifies how many digits are to be grouped together into a segment. In the case of real numbers, segmenting occurs every x digits to the left of the decimal point. In all other cases (credit cards, EIN and SSN) segmenting occurs every x digits moving from left to right. Only applicable for ccard, ccard-16 and real number types. Not applicable for ccard-15, EIN or SSN types, which have irregular grouping intervals that NumBox handles directly. Must be an integer that is larger than zero.

autoScroll

'auto'

When you tap on an HTML input box using a phone, typically your browser viewport is resized to the top half of your phone's screen, and the lower half is replaced with a virtual keyboard, so you can type an entry into the input box. However, sometimes the box you just tapped on is hidden by the virtual keyboard that just popped up. NumBox can optionally try to scroll the browser viewport so that the input box is scrolled up automatically to remains in view after the keyboard has appeared.

'auto'	For mixed mobile/desktop use with responsive designs. The 'auto' string setting, tells NumBox to set the value to true if it thinks the browser is on a mobile device, and to set the value to false if it thinks the browser is on a desktop device. This way, mobile devices can take advantage of the auto-scroll feature, while desktop browser experiences remain unchanged.
true	Recommended for mobile-only use – PhoneGap, etc. NumBox will attempt to scroll the browser viewport so that the input box is more likely to be in a mobile browser’s viewport once the pop-up keyboard has appeared. In case you have a fixed header and footer that stays put and doesn't scroll, such as can be achieved using jQuery Mobile’s data-position="fixed" attribute, NumBox needs to know the area that can be scrolled. You should mark the scrollable area in one of two ways: A div with a data-role="content" attribute. An element with an id="content" attribute. If you don’t have a fixed position header, you could apply one of these attributes to the <body> element. NumBox won’t try to scroll the browser viewport unless one of these attributes are found.
false	For desktop-only use or sites not catering for mobiles. NumBox will never attempt to scroll the browser viewport. This can be advisable if a mobile user has to keep on zooming or panning.

onFocus

'' (empty string)

You should set this property if you want to hook the focus event of the input. The value should be set to a string which is the name of the function you want to be called during the event. Please see the Hooking Event Handlers section for full details.

onBlur

'' (empty string)

You should set this property if you want to hook the blur event of the input. The value should be set to a string which is the name of the function you want to be called during the event. Please see the Hooking Event Handlers section for full details.

onKeydown

'' (empty string)

onInput

'' (empty string)

You should set this property if you want to hook the input or propertychange events of the input. The value should be set to a string which is the name of the function you want to be called during the event. Please see Hooking Event Handlers .

onPaste

'' (empty string)

5. METHODS

Method (Click for Details)	Chainable	Usage Summary
.NumBox() .NumBox({ property: value, … }) .NumBox('setup') .NumBox('setup', { property: value, … })		Different ways of specifying the initial set up of NumBox against type="text" or type="number" inputs, with or without an optional list of configuration properties. Required first. Call once per input unless you use 'destroy' between calls.
.NumBox('destroy')		Disassociates NumBox (including events) from inputs.
.NumBox('getFormatted')		Returns display formatted number as a string. e.g. $1,234.50.
.NumBox('getRaw')		Returns raw number for calculations, et cetera. e.g. 1234.5.
.NumBox('setRaw', rawValue)		Lets you change NumBox value programmatically. Optional as NumBox picks up existing value during set up.
.NumBox('autoScroll', 'auto' \| true \| false)		Whether or not to help scroll input box higher up the screen. Handy on mobile devices where pop-up keyboards can appear. Also available as a property in 'setup'. Defaults to 'auto'.
.NumBox('onFocus', 'fnCallbackName')		Optional. Use if you need to hook gained focus events. Also available in 'setup'. Fn name is a quoted string. Callback fires on the input’s focus events.
.NumBox('onBlur', 'fnCallbackName')		Optional. Use if you need to hook lost focus events. Also available in 'setup'. Fn name is a quoted string. Callback fires on the input’s blur events.
.NumBox('onKeydown', 'fnCallbackName')		Optional. Use if you need to hook key press events. Also available in 'setup'. Fn name is a quoted string. Callback fires on the input’s keydown events.
.NumBox('onInput', 'fnCallbackName')		Optional. Use if you need to hook value is changing events. Also available in 'setup'. Fn name is a quoted string. Callback fires on the input & propertychange events.
.NumBox('onPaste', 'fnCallbackName')		Optional. Use if you need to hook paste events. Also available in 'setup'. Fn name is a quoted string. Callback fires on the input’s paste events (if supported.)

6. CALLBACKS

Callback Method	Parameters Forwarded †	Important Notes on Use
onFocus	jQuery event object	Callback occurs when the input gains focus, during the focus event.
onBlur	jQuery event object	Callback occurs when the input loses focus, during the blur event.
onKeydown	jQuery event object	Callback usually occurs when a key is pressed, during the keydown event. You can use this event to obtain a key code, to identify which key was pressed. Some browsers do not send every key press, so use with caution. Google Chrome for Android, (not the native browser,) also has a major flaw, and sends a zero for all key presses, making it impossible to identify the key.
onInput	jQuery event object, input succeeded Boolean	Callback usually occurs when the value of the input is changed by the user typing, while the input still has the focus. This is during the input event on all modern browsers. On older Microsoft browsers (IE8-) which don’t support the standard input event, NumBox hooks Microsoft’s proprietary propertychange event instead. However, since propertychange, unlike input, also fires when a value is changed via JavaScript, NumBox takes care not to hand off to your callback unless a keydown event is also fired. To add fuel to the fire, IE8 has a bug where it doesn't fire propertychange on the first key press.
onPaste	jQuery event object	Callback sometimes occurs during a paste event, when the user is copy-pasting. This event should not be relied upon as it is not standard and only some browsers support it. Additionally, as NumBox blocks certain key presses during the keydown event, such as ctrl-v (Windows paste shortcut) then we may never get to this event.

7. EXAMPLES

$('#money'  ).NumBox(); // defaults to dollars
$('#money'  ).NumBox({symbol: '€', location: 'r'});
$('#plastic').NumBox({type: 'ccard'});
$('#percent').NumBox({type: 'percent'});
 
$('.NumBox' ).NumBox('destroy'); // '.NumBox' = all
 
var forShow = $('#input').NumBox('getFormatted');
var forCalc = $('#input').NumBox('getRaw');
$('#input'  ).NumBox('setRaw',  1234.5 );
$('#input'  ).NumBox('setRaw', '1234.5');
 
$('.NumBox' ).NumBox('autoScroll', true);
 
$('.NumBox' ).NumBox('onFocus', 'callback');
$('.NumBox' ).NumBox('onInput', 'callback');
 
function callback(event, valid)
{
    // all callbacks pass the jQuery event object
    console.log
    (
        event.currentTarget.id + ' : ' +
        event.type
    );
     
    // input also has a change permitted Boolean
    if (typeof valid === 'boolean')
    {
        console.log
        (
            '>> valid = ' + valid.toString()
        );
    }
}

JS Tutorial

NumBox jQuery Plugin - Mobile-Friendly HTML5 Numeric Input

Features

Related Articles