NumberPlugin

Localized Number Formatter and Currency Converter

This plugin allows to format

• numbers,
• currencies and
• percentages

in a localized way using the Unicode CLDR.

It also allows to convert currencies using an online exchange rates service. Supported services are:

• Fixer.IO
• Open Exchange Rates
• CurrencyLayer

All of these services require an API key/id to be downloaded by registering for an appropriate service level. Up-to-date exchange rates will then be downloaded and cached for a specific time, e.g. refreshing rates once a day.

Usage

For example, a number such as 1234 is formatted differently depending on the locales

Number	Type	Locale	Parameter	Output
1234.00	number	en_US		1,234
		de_DE		1.234
		ar		١٬٢٣٤
		es		1234
1234.00	currency	en_US	currency="USD"	$1,234.00
	currency	de_DE	currency="EUR"	1.234,00 €
	currency	ar	currency="AED"	د.إ.‏ ١٬٢٣٤٫٠٠
	currency	ar	currency="USD"	US$ ١٬٢٣٤٫٠٠
	currency	es	currency="EUR"	1234,00 €
0.1234	percent	en_US		12%
		de_DE		12 %
		ar		١٢٪
		es		12 %
		en_US	minimum_fraction_digits="1"	12.3%
12.34	currency	de_DE	currency="EUR" from="USD"	10,32 €

Syntax

NUMBER

By default, numbers are formatted by the %NUMBER{"value" param="..."}% macro

Parameter	Description	Default
type	specifies what kind of number this is and will use the related formatter for it, can be number, currency, percent or bytes	number
locale	unicode locale identifiers, for example es (Spanish), es_ES (European Spanish), es_419 (Latin American Spanish), zh_Hant (Traditional Chinese), zh_Hans (Simplified Chinese), chr (Cherokee)	current locale of the user's session
decimal_sign	delimiter of fraction	see current locale
group_sign	delimiter every three digits in large numbers	see current locale
plus_sign	example +	see current locale
minus_sign	-	see current locale
infinity	∞	see current locale
nan	NaN	see current locale
pattern	pattern how to format a number, for example #,##0.###	see current locale
minimum_integer_digits		see current locale
minimum_fraction_digits
maximum_fraction_digits
primary_grouping_size
secondary_grouping_size
minimum_grouping_digits
rounding_increment
Parameters for currency:
currency / currency_code / to	this parameter is required when the type is set to currency; possible values are any 3-letter digits according to ISO 4217, such as EUR or USD
currency_sign	the sign that is used to identify the currency	see current locale
cash	for boolean switch to enable rendering of "cash money" which may be formatted differently for some locales	off
from	specify the source currency which is converted to the target currency as specified in the currency parameter using an online exchange rates service	same as source currency
Parameters for percent:
permil		0
percent_sign		%
permil_sign		‰

Further documentation is available at CLDR::Number, the perl library being used underneath.

In addition to the %NUMBER macro you may specify a list of currency codes as a shortcut for the given type of number. The configuration setting stored in $Foswiki::cfg{NumberPlugin}{Currencies} will specify the list of those which a macro should be created for. For example a setting such as

$Foswiki::cfg{NumberPlugin}{Currencies} = "EUR, USD";

will create the macros %EUR{...}% and %USD{...}% as a shortcut for

%NUMBER{"..." type="currency" currency="<code>"}%

CURRENCIES

This macro lists all available currencies as well as their exchange rate using an online exchange rates service.

Parameter	Description	Default
"..." / total	the total amount that the rates are computed for	1
base	base currency to with all rates are calculated	base rate of the currency provider
header	format string preceeding the output list
footer	format string appended to the output list
separator	list separator	,
format	format string used for every item in the list of available currencies	$code
include	regular expression that a currency code must match to be included in the output
exclude	regular expression that a currency code must not match to be included in the output

The format parameter accepts a couple of variables that are expanded accordingly:

• $code the international currency code (USD, EUR, ...)
• $rate exchange rate vs the base currency
• $total total value of the currency converted to the current currency in the loop

Formfield types

This plugin defines three additional formfield types that may be used defining DataForms.

• currency
• number
• percent

Parameters are specified in the Values column of the formfield, i.e. the formfield type "currency" requires a currency="..." parameter such as in:

| *Name*           | *Type*   | *Size* | *Values*            | *Description* | *Attributes* | *Default* |
| Advance Payments | currency | 30     | currency="EUR" |               |              | 0         |

Formfield types "number" and "percent" may specify additional parameters as in:

| *Name*           | *Type*   | *Size* | *Values*            | *Description* | *Attributes* | *Default* |
| Percentage | percent | 5 | fraction="2" placeholder="enter value" |               |              | 0         |
| Some Number | number | 5 | fraction="2" placeholder="enter value" |               |              | 0         |

There are additional parameters for a "number" as documented in https://metacpan.org/pod/CLDR::Number::Format::Decimal and in https://metacpan.org/pod/CLDR::Number::Format::Percent for "percent" formfields.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Contrib::CacheContrib	>=0	Required
Foswiki::Contrib::JQIMaskContrib	>0	Required
Scalar::Util	>=0	Required
CLDR::Number	>=0	Required
HTTP::Message	>=0	Required
JSON	>=0	Required
REST::Client	>=0	Required
URI	>=0	Required

Change History

26 Jan 2024	add better support for fractions in numerical values; added placeholder parameter for input fields; use JQIMaskContrib for masked input
20 Oct 2022	improved caching of exchange rates
05 May 2022	reimplement caching using Foswiki:Extensions/CacheContrib; default to no currency provider for exchange rates; load currencies lazily for better init performace; improved number format "bytes"
15 Mar 2021	added back {Currencies} setting as documented
05 Mar 2018	added support for CurrencyLayer
18 Sep 2017	added support for exchange rates; made compatible with SpreadsheetPlugin
03 Jan 2017	initial release