JarCastingAngular Numeral.js filter
This is an Angular.js filter that applies Numeral.js formatting.
The latest version of this library uses Numeral.js 2.x branch. There are several breaking changes in Numeral.js, as well as breaking changes in this library. If you depend on Numeral.js 1.x and cannot upgrade, please use the latest 1.x release (and corresponding 1.x branch).
Breaking Changes in 2.x
For details on breaking changes in Numeral.js itself, please see its changelog.
In addition, angular-numeraljs has the following breaking changes from in 1.3.0 to 2.0.0:
$numeraljsConfigProvider.setCurrentLanguage(lang)has been renamed tolocale(locale)$numeraljsConfigProvider.setDefaultFormat(format)has been renamed todefaultFormat(format)$numeraljsConfigProvider.setFormat(name, formatString)has been renamed tonamedFormat(name, formatString)$numeraljsConfigProvider.setLanguage(lang, def)has been renamed toregister('locale', name, def)
How to Use
-
Include Numeral.js in your project
-
Include either the minified or non-minified javascript file from the
/dist/folder:<script src="angular-numeraljs.js"></script>
-
Inject the
ngNumeraljsfilter into your app module:var myApp = angular.module('myApp', ['ngNumeraljs']);
-
Apply the filter with the desired format string:
<p> {{ price | numeraljs:'$0,0.00' }} </p>
Advanced Usage
You can configure ngNumeraljs during Angular's configuration phase using the $numeraljsConfigProvider:
var app = angular.module('exampleApp', ['ngNumeraljs']);
app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
// place configuration here
}]);
Numeral.js must be already loaded in the browser prior to using $numeraljsConfigProvider.
Named Formats
$numeraljsConfigProvider.namedFormat(name, formatString) - defines a named format which can be used in place of the format string in the filter.
app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
$numeraljsConfigProvider.namedFormat('currency', '$ 0,0.00');
}]);
In markup,
<p>
{{ price | numeraljs:'currency' }}
</p>
Default Format
Numeral.js defines the default format as '0,0', so this format is used if none is provided to the filter.
$numeraljsConfigProvider.defaultFormat(format) - overrides the built-in default format.
app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
$numeraljsConfigProvider.defaultFormat('0.0 $');
}]);
In markup,
<p>
{{ price | numeraljs }} <!-- will produce 15.5 $ -->
</p>
Custom Locales and Formats
$numeraljsConfigProvider.register(type, name, definition) - adds new locale or format definitions to Numeral.js. type must be either 'locale' or 'format'. For complete details, please refer to the Numeral.js documentation.
app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
// Register a new Locale
$numeraljsConfigProvider.register('locale', 'de', {
delimiters: {
thousands: ' ',
decimal: ','
},
abbreviations: {
thousand: 'k',
million: 'm',
billion: 'b',
trillion: 't'
},
ordinal: function (number) {
return '.';
},
currency: {
symbol: '€'
}
});
// Register a new Format
$numeraljsConfigProvider.register('format', 'percentage', {
regexps: {
format: /(%)/,
unformat: /(%)/
},
format: function(value, format, roundingFunction) {
var space = numeral._.includes(format, ' %') ? ' ' : '',
output;
value = value * 100;
// check for space before %
format = format.replace(/\s?\%/, '');
output = numeral._.numberToFormat(value, format, roundingFunction);
if (numeral._.includes(output, ')')) {
output = output.split('');
output.splice(-1, 0, space + '%');
output = output.join('');
} else {
output = output + space + '%';
}
return output;
},
unformat: function(string) {
return numeral._.stringToNumber(string) * 0.01;
}
});
$numeraljsConfigProvider.defaultFormat('0%');
$numeraljsConfigProvider.locale('de');
}]);
Please note that registering a new format will add new formatting functionality, e.g. adding a new character to the format string. If you want to add a short name for a specific format string, see namedFormat() above.
See a list of available locales here: locale.
Locales or formats can be loaded directly into Numeral.js as well, e.g. by loading the locale files after Numeral.js is loaded. Angular-numeraljs can use these locales or formats even if they are not set via this provider.
Select Locale
$numeraljsConfigProvider.locale(locale) - selects the current locale. The locale must be loaded either by $numeraljsConfigProvider.register() or by loading the Numeral.js locale file.
app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
$numeraljsConfigProvider.locale('de');
}]);
Runtime Configuration
It is possible to change all of the configurations at runtime by injecting $numeraljsConfig:
app.controller('numeralExample', function ($scope, $numeraljsConfig) {
$numeraljsConfig.defaultFormat('0,0.0');
$numeraljsConfig.locale($scope.locale);
});
This may be useful for websites with a language switcher, saved user preferences, etc.
Examples
There are several examples in the example/ folder which can be used for reference:
- Simple: using this library in the most basic way possible
- Config: using $numeraljsConfigProvider to configure this library
- ChangingLanguages: changing languages (or other properties) at runtime (vs initialization)
- Bower: adding a dependency through Bower
- Browserify: adding a dependency through Browserify
Bower
This filter can be installed via Bower with the following dependency in the bower.json file.
"dependencies": {
"angular-numeraljs": "^2.0"
}
Browserify
This project is published in NPM as angular-numeraljs.
"dependencies": {
"angular-numeraljs": "^2.0"
}
The example/browserify folder has a working example with Browserify and Grunt. To build this project, install Grunt and Browserify and run the following:
cd example/browserify
npm install
grunt build
Then open example/browserify/dist/index.html in a browser.