NumBox Quick-Start Guide

~ For Web Developers New to jQuery Plugins ~

First Steps

Before you can use the NumBox jQuery Plugin, you should load jQuery and NumBox:

            <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js" type="text/javascript"></script>
            <script src="/inc/jquery.numbox-1.1.0.min.js"                             type="text/javascript"></script>

As with other jQuery plug-ins, you need to load jQuery first, before you load any plug-ins. In the example above, the free googleapis.com CDN is being used for jQuery, and you would have had to download NumBox and save the NumBox .js file to a sub-directory on your web site called “inc”. Alternatively, you could host NumBox on a free public CDN if you prefer. Either way, both of these script lines can go in either the <head> or <body> sections of your page.

Optional: We also recommend that you include the CSS code to disable numeric input spinners in your own CSS file. Or, if you don't have your own CSS, or prefer to use the CSS file we've provided, you could include something like the following, which must go in the <head> section of your page, if you choose to include it:

            <link href="/incjquery.numbox-1.1.0.css" rel="stylesheet" type="text/css" />

Converting an Input Into a NumBox

Once you've loaded jQuery and NumBox, you can easily start adapting your existing numeric inputs. Say you have an input on your page with an id of “myInput”:

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

Let’s convert that to a basic NumBox when the page is first loaded, and before it's displayed. NumBox customizations should only be applied after the jQuery and NumBox scripts have loaded and the rest of the page is ready. We can ensure everything is ready first by wrapping our customization inside the standard jQuery document ready event:

            <script type="text/javascript">
                $(document).ready(function()
                {
                    $('#myInput').NumBox();
                });    
            </script>

$('#myInput').NumBox(); is our simple customization example, which takes an HTML input with an id of “myInput” and converts it into a NumBox with a default configuration. NumBox’s default configuration is a US Dollar currency format, but there are a wide range of NumBox customization options to pick from. Here is another example that modifies the NumBox configuration to display a British pound sign instead of a US dollar sign:

            <script type="text/javascript">
                $(document).ready(function()
                {
                    $('#myInput').NumBox({symbol: '£'});
                });    
            </script>

There are a lot of other examples you can follow on this site. Please take a look at the NumBox Quick Taste Test on the NumBox home page, and click on the See Source Code button for nine easy-to-follow examples of the many different ways you can use NumBox. Not sure how to do something? Take a look around this site first, and if you still can't find what you're looking for, you can try asking a question on the NumBox Community Forums.

Converting NumBox into an Angular Directive

            app.directive('numbox', function()
            {
                var service = {};

                service.restrict = 'A';
                service.link     = function(scope, element, attributes)
                {
                    $(element).NumBox(scope.$eval(attributes.numbox));
                };

                return service;
            });

If you're already using AngularJS, (requires some expertise,) then this couldn't be much easier. Just include the above JavaScript, (inside script tags or a referenced .js file,) once you've finished with your Angular .module, .config and .run calls. You also need to remember to load jQuery first of course, prior to loading Angular. To then consume the NumBox directive in an Angular view, (HTML template,) you only need to include a lowercase numbox property. There is no need for any JavaScript in your view in order to set up NumBox on an input. For example:

            <input type="number" ng-model="whatever" numbox="{type: 'decimal', min: 1.25, max: 1.75}" />

A Common Gotcha…

You’ve probably used JavaScript’s value or jQuery’s .val() function to grab the value from an <input type="text" /> input.
However, for an <input type="number" /> value or .val(), you may not get any value at all, if the input isn’t a valid number.
(Varies by browser.) Instead, use NumBox’s getRaw or getFormatted functions to always get the most recent valid value.