mirror of
https://github.com/invoiceninja/invoiceninja.git
synced 2024-11-14 07:02:34 +01:00
433 lines
18 KiB
HTML
433 lines
18 KiB
HTML
<!doctype html>
|
|
<html lang="en" class="no-js">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>accounting.js - format money / currency in JavaScript</title>
|
|
<link href="demo-resources/style.css" rel="stylesheet"/>
|
|
<link rel="canonical" href="http://josscrowcroft.github.com/accounting.js/" />
|
|
<script type="text/javascript">
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-17884149-3']);
|
|
_gaq.push(['_trackPageview']);
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
</script>
|
|
</head>
|
|
|
|
<body>
|
|
<section>
|
|
<h1>accounting.js</h1>
|
|
<p><strong>accounting.js</strong> is a tiny JavaScript library for number, money and currency formatting, with optional excel-style column rendering (to line up symbols and decimals). It's lightweight, fully localisable and has zero dependencies.</p>
|
|
<p><a href="http://twitter.com/share" class="twitter-share-button" data-count="horizontal" data-via="josscrowcroft" data-url="http://josscrowcroft.github.com/accounting.js" data-text="accounting.js - JavaScript library for money/currency formatting">Tweet</a> <g:plusone size="medium"></g:plusone></p>
|
|
<ul>
|
|
<li><a href="#methods" title="library methods overvew">methods & examples</a>
|
|
<li><a href="#demo" title="demo">demo</a>
|
|
<li><a href="#instructions" title="instructions">instructions</a>
|
|
<li><a href="#documentation" title="documentation">documentation</a>
|
|
<li><a href="#roadmap" title="roadmap">roadmap</a>
|
|
<li><a href="#support" title="support">feedback / support</a>
|
|
<li><a href="#download" title="download">download</a>
|
|
<li><a href="#moar" title="moar info">moar info</a>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="methods">
|
|
<h2>Library Methods</h2>
|
|
<h4><strong>formatMoney()</strong> - format any number into currency</h4>
|
|
<p>The most basic function of this library is money-formatting numbers, with currency symbol, precision (places), and thousand/decimal separators:</p>
|
|
<pre class="prettyprint lang-js">// Default usage:
|
|
accounting.formatMoney(12345678); // $12,345,678.00
|
|
|
|
// European formatting (custom symbol and separators), could also use options object as second param:
|
|
accounting.formatMoney(4999.99, "€", 2, ".", ","); // €4.999,99
|
|
|
|
// Negative values are formatted nicely, too:
|
|
accounting.formatMoney(-500000, "£ ", 0); // £ -500,000
|
|
|
|
// Simple `format` string allows control of symbol position [%v = value, %s = symbol]:
|
|
accounting.formatMoney(5318008, { symbol: "GBP", format: "%v %s" }); // 5,318,008.00 GBP</pre>
|
|
<h4><strong>formatColumn()</strong> - format a list of values for column-display</h4>
|
|
<p>This table demonstrates how <strong>accounting.js</strong> can take a list of numbers and money-format them with padding to line up currency symbols and decimal places (NB: <code>white-space:pre</code> is needed for the browser to render the padded spaces):</p>
|
|
<table id="demo-table">
|
|
<thead>
|
|
<tr>
|
|
<th>Original Number:</th>
|
|
<th>With accounting.js:</th>
|
|
<th>Different settings:</th>
|
|
<th>European format:</th>
|
|
<th>Symbol after value:</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody></tbody>
|
|
</table>
|
|
<pre class="prettyprint lang-js">// Format list of numbers for display:
|
|
accounting.formatColumn([123.5, 3456.49, 777888.99, 12345678, -5432], "$ ");</pre>
|
|
|
|
<h4><strong>formatNumber()</strong> - format a number with custom precision and localisation</h4>
|
|
<p>The base function of the library, which takes any number or array of numbers, runs <code>accounting.unformat()</code> to remove any formatting, and returns the number(s) formatted with separated thousands and custom precision:</p>
|
|
<pre class="prettyprint lang-js">accounting.formatNumber(5318008); // 5,318,008
|
|
accounting.formatNumber(9876543.21, 3, " "); // 9 876 543.210</pre>
|
|
|
|
<h4><strong>toFixed()</strong> - better rounding for floating point numbers</h4>
|
|
<p>Implementation of toFixed() that treats floats more like decimal values than binary, fixing inconsistent precision rounding in JavaScript (where some .05 values round up, while others round down):</p>
|
|
<pre class="prettyprint lang-js">(0.615).toFixed(2); // "0.61"
|
|
accounting.toFixed(0.615, 2); // "0.62"</pre>
|
|
|
|
<h4><strong>unformat()</strong> - get a value from any formatted number/currency string</h4>
|
|
<p>Takes any number and removes all currency formatting:</p>
|
|
<pre class="prettyprint lang-js">accounting.unformat("£ 12,345,678.90 GBP"); // 12345678.9</pre>
|
|
</section>
|
|
|
|
<section id="demo">
|
|
<h2>Demo / Try it out</h2>
|
|
|
|
<h4>Money formatting:</h4>
|
|
<div class="well">
|
|
<p>Enter any number into the box and choose currency. Uses <code>accounting.formatMoney()</code>:</p>
|
|
<p>
|
|
<select id="demo-number-symbol">
|
|
<option value="$ ">$</option>
|
|
<option value="£ ">£</option>
|
|
<option value="HK$ ">HK$</option>
|
|
<option data-locale="european" value="€ ">€ </option>
|
|
</select>
|
|
<input type="text" maxlength="20" class="" id="demo-number-value" value="" />
|
|
</p>
|
|
<p>Result: <strong><span id="demo-number-result">$ 0.00</span></strong></p>
|
|
</div>
|
|
|
|
<h4>Column formatting:</h4>
|
|
<div class="well">
|
|
<p>Edit the values in the table to see how <strong>formatColumn()</strong> keeps them aligned:</p>
|
|
<table id="demo-column">
|
|
<tbody>
|
|
<tr>
|
|
<td><input type="text" value="1000000" maxlength="20" /></td>
|
|
<td class="output">$ 1,000,000.00</td>
|
|
<td class="output2">GBP 1,000,000</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="text" value="-5000" maxlength="20" /></td>
|
|
<td class="output">$ -5,000.00</td>
|
|
<td class="output2">GBP (5,000)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="text" value="0" maxlength="20" /></td>
|
|
<td class="output">$ 0.00</td>
|
|
<td class="output2">GBP --</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</section>
|
|
|
|
|
|
<section id="instructions">
|
|
<h2>Instructions / How to use</h2>
|
|
<p>1. Download the script and put it somewhere, then do this:</p>
|
|
<pre class="prettyprint"><script src="path/to/accounting.js"></script>
|
|
|
|
<script type="text/javascript">
|
|
// You can do this now:
|
|
accounting.formatMoney(5318008);
|
|
</script></pre>
|
|
<p>2. Check out the documentation and source-code for full method/parameter info if you get stuck.</p>
|
|
</section>
|
|
|
|
|
|
<section id="documentation">
|
|
<h2>Documentation</h2>
|
|
<p>Information on the parameters of each method. See <a href="#methods" title="accounting.js library methods">library methods</a> above for more examples. Optional parameters are in <code><em>[italics]</em></code>, with the default value indicated.</p>
|
|
|
|
|
|
<h4><strong>accounting.settings</strong></h4>
|
|
<pre class="prettyprint lang-js">// Settings object that controls default parameters for library methods:
|
|
accounting.settings = {
|
|
currency: {
|
|
symbol : "$", // default currency symbol is '$'
|
|
format: "%s%v", // controls output: %s = symbol, %v = value/number (can be object: see below)
|
|
decimal : ".", // decimal point separator
|
|
thousand: ",", // thousands separator
|
|
precision : 2 // decimal places
|
|
},
|
|
number: {
|
|
precision : 0, // default precision on numbers is 0
|
|
thousand: ",",
|
|
decimal : "."
|
|
}
|
|
}
|
|
|
|
// These can be changed externally to edit the library's defaults:
|
|
accounting.settings.currency.format = "%s %v";
|
|
|
|
// Format can be an object, with `pos`, `neg` and `zero`:
|
|
accounting.settings.currency.format = {
|
|
pos : "%s %v", // for positive values, eg. "$ 1.00" (required)
|
|
neg : "%s (%v)", // for negative values, eg. "$ (1.00)" <em>[optional]</em>
|
|
zero: "%s -- " // for zero values, eg. "$ --" <em>[optional]</em>
|
|
};
|
|
|
|
// Example using underscore.js - extend default settings (also works with $.extend in jQuery):
|
|
accounting.settings.number = _.defaults({
|
|
precision: 2,
|
|
thousand: " "
|
|
}, accounting.settings.number);</pre>
|
|
|
|
|
|
<h4><strong>accounting.formatMoney()</strong></h4>
|
|
<pre class="prettyprint lang-js">// Standard usage and parameters (returns string):
|
|
accounting.formatMoney(number<em>,[symbol = "$"],[precision = 2],[thousand = ","],[decimal = "."],[format = "%s%v"]</em>)
|
|
|
|
// Second parameter can be an object:
|
|
accounting.formatMoney(number<em>, [options]</em>)
|
|
|
|
// Available fields in options object, matching `settings.currency`:
|
|
var options = {
|
|
symbol : "$",
|
|
decimal : ".",
|
|
thousand: ",",
|
|
precision : 2,
|
|
format: "%s%v"
|
|
};
|
|
|
|
// Example usage:
|
|
accounting.formatMoney(12345678); // $12,345,678.00
|
|
accounting.formatMoney(4999.99, "€", 2, ".", ","); // €4.999,99
|
|
accounting.formatMoney(-500000, "£ ", 0); // £ -500,000
|
|
|
|
// Example usage with options object:
|
|
accounting.formatMoney(5318008, {
|
|
symbol: "GBP",
|
|
precision: 0,
|
|
thousand: "·",
|
|
format: {
|
|
pos : "%s %v",
|
|
neg : "%s (%v)",
|
|
zero: "%s --"
|
|
}
|
|
});
|
|
|
|
// Will recursively format an array of values:
|
|
accounting.formatMoney([123, 456, [78, 9]], "$", 0); // ["$123", "$456", ["$78", "$9"]]</pre>
|
|
|
|
|
|
|
|
<h4><strong>accounting.formatColumn()</strong></h4>
|
|
<pre class="prettyprint lang-js">// Standard usage and parameters (returns array):
|
|
accounting.formatColumn(list<em>, [symbol = "$"],[precision = 2],[thousand = ","],[decimal = "."],[format = "%s%v"]</em>)
|
|
|
|
// Second parameter can be an object (see formatNumber for available options):
|
|
accounting.formatColumn(list, <em>[options]</em>)
|
|
|
|
// Example usage (NB. use a space after the symbol to add arbitrary padding to all values):
|
|
var list = [123, 12345];
|
|
accounting.formatColumn(list, "$ ", 0); // ["$ 123", "$ 12,345"]
|
|
|
|
// List of numbers can be a multi-dimensional array (formatColumn is applied recursively):
|
|
var list = [[1, 100], [900, 9]];
|
|
accounting.formatColumn(list); // [["$ 1.00", "$100.00"], ["$900.00", "$ 9.00"]]</pre>
|
|
|
|
|
|
<h4><strong>accounting.formatNumber()</strong></h4>
|
|
<pre class="prettyprint lang-js">// Standard usage and parameters (returns string):
|
|
accounting.formatNumber(number<em>, [precision = 0], [thousand = ","], [decimal = "."]</em>)
|
|
|
|
// Second parameter can also be an object matching `settings.number`:
|
|
accounting.formatNumber(number<em>, [object]</em>)
|
|
|
|
// Example usage:
|
|
accounting.formatNumber(9876543); // 9,876,543
|
|
accounting.formatNumber(4999.99, 2, ".", ","); // 4.999,99
|
|
|
|
// Example usage with options object:
|
|
accounting.formatNumber(5318008, {
|
|
precision : 3,
|
|
thousand : " "
|
|
});
|
|
|
|
// Will recursively format an array of values:
|
|
accounting.formatNumber([123456, [7890, 123]]); // ["123,456", ["7,890", "123"]]</pre>
|
|
|
|
|
|
<h4><strong>accounting.toFixed()</strong></h4>
|
|
<pre class="prettyprint lang-js">// Standard usage and parameters (returns string):
|
|
accounting.toFixed(number<em>, [precision = 0]</em>);
|
|
|
|
// Example usage:
|
|
accounting.toFixed(0.615, 2); // "0.62"
|
|
|
|
// Compare to regular JavaScript `Number.toFixed()` method:
|
|
(0.615).toFixed(2); // "0.61"</pre>
|
|
|
|
|
|
<h4><strong>accounting.unformat()</strong></h4>
|
|
<pre class="prettyprint lang-js">// Standard usage and parameters (returns number):
|
|
accounting.unformat(string<em>, [decimal]</em>);
|
|
|
|
// Example usage:
|
|
accounting.unformat("GBP £ 12,345,678.90"); // 12345678.9
|
|
|
|
// If a non-standard decimal separator was used (eg. a comma) unformat() will need it in order to work out
|
|
// which part of the number is a decimal/float:
|
|
accounting.unformat("€ 1.000.000,00", ","); // 1000000</pre>
|
|
|
|
</section>
|
|
|
|
|
|
<section id="roadmap">
|
|
<h2>Roadmap</h2>
|
|
<p>See the <a href="https://github.com/josscrowcroft/accounting.js/issues" title="accounting.js issues">Github Issues page</a> for up-to-date progress.</p>
|
|
<h4>Next Version:</h4>
|
|
<ul>
|
|
<li><s>Add more fine-grained control of formatting, with negatives and zero-values</s></li>
|
|
<li><s>Implement <code>map()</code> and type-checking helper methods to clean up API methods</s></li>
|
|
<li>Find performance bottlenecks and work on speed optimisations</li>
|
|
<li>Write more tests, docs and examples, add FAQ</li>
|
|
<li>Implement <a href="https://github.com/josscrowcroft/accounting.js/issues/" title="accounting.js issues">feedback</a></li>
|
|
</ul>
|
|
<h4>Later:</h4>
|
|
<ul>
|
|
<li>Add padding parameter to override amount of space between currency symbol and value.</li>
|
|
<li>Add digit-grouping control, to allow eg. "$10,0000"</li>
|
|
<li>Add choice of rounding method for precision (up, down or nearest-neighbour).</li>
|
|
<li>Add several other general and excel-style money formatting methods.</li>
|
|
<li>Create NPM package, if there's demand for it.</li>
|
|
<li>Create wrapper for jQuery as a separate plugin (not in core) to allow eg. <code>$('td.accounting').formatMoney()</code></li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="support">
|
|
<h2>Feedback / Support</h2>
|
|
<p>Please create issues on the <a href="https://github.com/josscrowcroft/accounting.js" title="accounting.js Github repository">accounting.js Github repository</a> if you have feedback or need support, or comment on <a href="http://www.josscrowcroft.com" title="Joss">Joss's blog</a>.</p>
|
|
</section>
|
|
|
|
<section id="download">
|
|
<h2>Download</h2>
|
|
<ul>
|
|
<li><strong><a href="https://raw.github.com/josscrowcroft/accounting.js/master/accounting.js" title="accounting.js">accounting.js</a></strong> - Latest version from Github (12kb)</li>
|
|
<li><strong><a href="https://raw.github.com/josscrowcroft/accounting.js/master/accounting.min.js" title="accounting.min.js">accounting.min.js</a></strong> - Latest version from Github (3kb, minified)</li>
|
|
<li>Or check out the <a href="https://github.com/josscrowcroft/accounting.js" title="accounting.js Github repository">accounting.js Github repository</a> for the full package.</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="moar">
|
|
<br />
|
|
<hr />
|
|
<p><a href="http://twitter.com/share" class="twitter-share-button" data-count="horizontal" data-via="josscrowcroft" data-url="http://josscrowcroft.github.com/accounting.js" data-text="accounting.js - JavaScript library for money/currency formatting">Tweet</a> <g:plusone size="medium"></g:plusone></p>
|
|
<h3>Moar Info</h3>
|
|
<p><small><strong>accounting.js</strong> was made by <a href="http://www.josscrowcroft.com" title="Joss">Joss</a> (that's me) in Hong Kong, for internal use in our enterprise analytics application at <a href="http://demandanalytics.com" title="Demand Analytics">Demand Analytics</a>. It seemed to be working pretty well, so I'm releasing it in the hope that other people and apps can make use of and contribute to it.</small></p>
|
|
<p><small>You can follow me on Twitter at <a href="http://twitter.com/josscrowcroft" title="@josscrowcroft on Twitter">@josscrowcroft</a>, I mostly post about JS, HTML5, startups, Hong Kong and things I've built.</small></p>
|
|
<p><small>Any questions? Just email me <a href="http://www.josscrowcroft.com/contact/" title="Contact Joss">here</a> or post on the <a href="https://github.com/josscrowcroft/accounting.js" title="accounting.js Github repository">accounting.js Github repository</a>.</small></p>
|
|
</section>
|
|
|
|
|
|
<script src="accounting.js"></script>
|
|
<script src="demo-resources/js/libs/jquery.min.js"></script>
|
|
<script src="demo-resources/js/prettify.js"></script>
|
|
|
|
<script type="text/javascript">
|
|
|
|
// demo thangs:
|
|
jQuery(document).ready(function($) {
|
|
var numbers = [123.5, 3456.615, 777888.99, -5432, -1234567, 0];
|
|
// Use accounting.js to format the list of numbers several ways:
|
|
var formatted = accounting.formatColumn(numbers, "$ "),
|
|
different = accounting.formatColumn(numbers, {
|
|
symbol:"HK$",
|
|
precision:0,
|
|
format: {
|
|
pos : "%s %v",
|
|
neg : "%s (%v)",
|
|
zero : "%s --"
|
|
}
|
|
}),
|
|
european = accounting.formatColumn(numbers, {
|
|
symbol: '€ ',
|
|
thousand:'.',
|
|
decimal:','
|
|
}),
|
|
symbolAfter = accounting.formatColumn(numbers, {
|
|
symbol : "GBP",
|
|
format : "%v %s"
|
|
});
|
|
|
|
// Concat some nasty demo HTML:
|
|
for ( var i = 0; i < numbers.length; i++ ) {
|
|
$('<tr><td>'+numbers[i]+'</td><td>'+formatted[i]+'</td><td>'+different[i]+'</td><td>'+european[i]+'</td><td>'+symbolAfter[i]+'</td></tr>').appendTo('table#demo-table tbody');
|
|
}
|
|
|
|
|
|
// Try it yourself clicky demo:
|
|
var $demoValue = $('#demo-number-value'),
|
|
$demoSymbol = $('#demo-number-symbol'),
|
|
$demoResult = $('#demo-number-result');
|
|
|
|
$demoValue.add($demoSymbol).bind('keydown keyup keypress focus blur paste change', function() {
|
|
var symbol = $demoSymbol.find(':selected').val(),
|
|
result = accounting.formatMoney(
|
|
$demoValue.val(),
|
|
symbol,
|
|
2,
|
|
($demoSymbol.find(':selected').data('locale') === 'european') ? "." : ",",
|
|
($demoSymbol.find(':selected').data('locale') === 'european') ? "," : "."
|
|
);
|
|
$demoResult.text(result);
|
|
});
|
|
|
|
|
|
// Try it yourself clicky column/list demo:
|
|
var $columnValues = $('#demo-column').find('input'),
|
|
$columnOutputs = $('#demo-column').find('.output'),
|
|
$columnOutputs2 = $('#demo-column').find('.output2');
|
|
|
|
$columnValues.bind('keydown keyup keypress focus blur paste', function() {
|
|
var list = $.map( $columnValues, function(each) { return $(each).val(); } ),
|
|
formatted = accounting.formatColumn(list, {
|
|
format : "%s %v"
|
|
}),
|
|
formatted2 = accounting.formatColumn(list, {
|
|
symbol : "GBP",
|
|
precision : 0,
|
|
format : {
|
|
pos : "%s %v",
|
|
neg : "%s (%v)",
|
|
zero: "%s --"
|
|
}
|
|
});
|
|
|
|
$.each($columnOutputs, function(i, each) {
|
|
$(each).text(formatted[i]);
|
|
});
|
|
$.each($columnOutputs2, function(i, each) {
|
|
$(each).text(formatted2[i]);
|
|
});
|
|
});
|
|
|
|
});
|
|
|
|
// prettify:
|
|
prettyPrint();
|
|
|
|
// twitter:
|
|
(function(d, t) {
|
|
var g = d.createElement(t),
|
|
s = d.getElementsByTagName(t)[0];
|
|
g.async = true;
|
|
g.src = 'http://platform.twitter.com/widgets.js';
|
|
s.parentNode.insertBefore(g, s);
|
|
})(document, 'script');
|
|
|
|
// google plus:
|
|
window.___gcfg = {lang: 'en-GB'};
|
|
(function() {
|
|
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
|
po.src = 'https://apis.google.com/js/plusone.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
|
})();
|
|
</script>
|
|
</body>
|
|
</html>
|