• Guide
• API
• License
• Demo
• Download
• Support

NumBox API v1.1.0

Full API - Methods & Properties

        $('#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()
                );
            }
        }
    

Setup Method

Destroy Method

Obtaining Values

When the NumBox element has the focus, it’s value attribute will be either an empty string or a raw unformatted number. When the NumBox element doesn’t have the focus, such as when a form is submitted, it’s value attribute will be the display formatted number, including currency symbol (if applicable) and grouping separators. You can explicitly obtain either the raw number or formatted number using these two helper methods:

If you intend to save the raw number to a database when a form is submitted, you could try something like this:

        <form method="post" action="SomePageThatSavesToDb.html">
            <div>
                <label for="inputUSD">US Dollars:</label>
                <input  id="inputUSD" type="number" value="0" placeholder="Please enter an amount" />
                <input  id="otherWay" type="hidden" value="0" />
            </div>
            <div>
                <button id="btnSave"  type="submit" title="Save the raw value">Save</button>
            </div>
        </form>
        
        <script type="text/javascript">
            $(document).ready(function()
            {
                $('#inputUSD').NumBox();
                $('#btnSave').click(function(event)
                {
                    $('#inputUSD').value = $('#inputUSD').NumBox.raw(); // or
                    $('#otherWay').value = $('#inputUSD').NumBox.raw();
                });
            });    
        </script>
    

Setting Values

As long as the input field has it’s value set before you first apply NumBox’s setup method, then you don't necessarily need to use the setRaw method. When .NumBox() is first applied, any existing number found in the field will be formatted according to your configuration options, providing that the number fits the rules you've created. For example, if you specify .NumBox({'integer'}) then you should not have pre-populated the field with an initial value of "0.01".

If you want to set the value after NumBox has been set up for your input, then you should use this method. The number you provide should be a raw number, devoid of any symbol or spacing characters, and it can be provided as either a string, an integer or a decimal. If your value can start with a leading zero, such as a social security number or employee identification number, then you should always pass the “number” in as a string, so you don”t potentially lose any leading zero. You should also ensure that the provided number conforms to the configuration options that you've chosen.

It may be useful to remember that setRaw can be applied to many fields at once if they will all have the same value.

Autoscroll Helper

• Use 'auto' (including quotes) if your web site visitors are using a mix of mobile and desktop
  browsers, and your site has a responsive design that is very well suited to mobile devices.
  (No zooming or panning required.) NumBox will then only use autoScroll if it thinks the device
  is a mobile device. This is the default setting. Stay with it if you’re unsure which is the best option.
   
• Use true if you’re guaranteed to be in a mobile-only environment, or writing a mobile app,
  such as with Apache Cordova, PhoneGap, Titanium and similar HTML5/JavaScript based hybrids.
   
• Use false if your user-base is guaranteed to use only desktop browsers,
  or if your web site layout is totally unsuitable for mobile devices.

1. By providing the appropriate property in NumBox’s Setup Method. For example:
   $('#creditcard').NumBox({type: 'ccard', autoScroll: true});
    
2. By using the autoScroll method after set up has been completed. For example:
   $('#creditcard').NumBox('autoScroll', true);

You’ll probably want to use a consistent autoScroll setting for all NumBox inputs.
Since NumBox adds an HTML class called “NumBox” to all of it’s inputs, you can do this:
$('.NumBox').NumBox('autoScroll', false);

1. A div with a data-role="content" attribute.
2. An element with an id="content" attribute.

If your page doesn't have a fixed header that stays when you scroll, you could try doing this:
<body id="content"> or <body data-role="content">

If you don’t set up a content tag, no error will occur and NumBox will gracefully ignore autoScroll.

Hooking Event Handlers

• blur
• focus
• input
• keydown
• paste
• propertychange

If you'd like to hook any of the above on NumBox inputs, please use the NumBox callback mechanism instead.
NumBox can then hand-off control to your custom JavaScript function once it has finished dealing with an event.
Remember though that if you use NumBox’s Destroy Method on an input, then NumBox will no longer hand-off.

1. By providing the appropriate property in NumBox’s Setup Method. For example:
   $('#creditcard').NumBox({type: 'ccard', onKeydown: 'fnMakeAClickingNoise'});
    
2. By using one of the five NumBox callback methods outlined in the table below. For example:
   $('#creditcard').NumBox('onKeydown', 'fnMakeAClickingNoise');

If you've previously set up a NumBox callback and want to take it down later, you can pass an empty string:
$('#creditcard').NumBox('onKeydown', '');

If you have multiple NumBox inputs on a page that will all use the same callback,
its probably easiest (and DRYer) to go with the second method, so you can
hook them all at once using '.NumBox' as your jQuery selector:
$('.NumBox').NumBox('onKeydown', 'fnMakeAClickingNoise');

Whichever method you use, the function name you provide must be in quotes. (Provided as a string.)
You should only provide the name, without any parentheses, and correctly capitalized!

^† These are parameters/arguments that NumBox passes on to your function.
  An example callback function that consumes these parameters is shown at the top of the page.

Additional Considerations

Consistent Styling

NumBox deliberately does not create any new UI components or attempt to style inputs, which makes it suitable for virtually all layout systems, including Twitter Bootstrap, Zurb Foundation, and jQuery Mobile. It does however, toggle input boxes’ types between type="number" and type="text", depending on the browser and if the mode is input or display. It is therefore suggested that you use the same styling for both input types. For example:

        input[type="number"],
        input[type="text"]
        {
            width: 100%;    // or
            width: 200px;   // etc.
        }
    

.NumBox Class

You also have the option of styling all NumBox inputs in CSS using the .NumBox class, which NumBox adds to all of it’s inputs.
The class can also conveniently be used with JavaScript and in jQuery selectors. For example:

        $('.NumBox').NumBox('setRaw', 0).NumBox('destroy').prop('disabled', true);
    

Disabling Spinners

For the most consistent look, it is typically recommended that the up/down spinners/arrows that appear in some browsers for input type="number" are disabled. On several browsers, even if you've correctly coded your CSS styles for a consistent width, and tinkered with box-sizing etc, numeric inputs that have a focus will be shorter in length than other inputs. This is due to an extra right margin on the spinners. The spinners are also not usually styled by layout libraries, so they can often look pretty awful with miniscule grey button arrows. Finally, spinners are totally impractical unless you're spinning a short range. e.g. 0% to 100%. Try spinning up to $1,000.00! Oh, and do you want to input a credit card number or social security number using spinners? Spinners are great with specialized time pop-ups (0-24, 0-60) but you don't need them for most numeric inputs, which is probably why most browsers made the wise decision not to implement them. Even on a small phone, it is easier and more importantly faster to use the numeric keyboard that NumBox pops-up to enter a number than using a spinner. So, spinners need to die go away! If you don’t agree, please feel free to (politely) debate the subject on the NumBox Community Forums!

If you want to disable the spinners then you can use the contents of the CSS file that was downloaded along with NumBox:

        /* Webkit: Android, Chrome, iOS, Safari */
        input::-webkit-outer-spin-button,
        input::-webkit-inner-spin-button
        {
            -webkit-appearance: none;   /* display: none alt can crash on hover */
            margin: 0px;                /* sometimes margin is left for spinner */
        }
    

Since these are just a few lines of CSS, you might prefer to incorporate them directly into your own CSS file.