View source for Template:Currency/doc

{{Documentation subpage}}
{{lua|Module:Currency|Module:Currency/Presentation}}
{{Lua sidebar}}

<!-- PLEASE ADD CATEGORIES AND INTERWIKIS AT THE BOTTOM OF THIS PAGE -->
Formats a currency value with the appropriate symbol which is linked to the article about the currency. If no currency is specified, the template will show the amount in [[United States dollar|United States dollars]].

== Usage ==
Using unnamed parameters:
:<code><nowiki>{{</nowiki>currency|{{var|value}}|{{var|code}}|first=|linked=|fmt=}}</code>
Using named parameters:
:<code><nowiki>{{</nowiki>currency|amount={{var|value}}|code={{var|code}}|first=|linked=}}</code>
where:
:{{var|value}} is a number with or without comma separators; may be followed by an optional quantifier: 'thousand', 'million', 'M', 'billion', 'B', or 'trillion'
:{{var|code}} is an [[ISO 4217|ISO 4217 currency code]] or one of the supported non-standard codes listed below
:{{para|first}} when set to any value produces a long-form currency name
:{{para|linked}} when set to <code>no</code> disables wikilinks on the rendered currency symbol or long-form currency name
:{{para|fmt}} specifies how {{var|value}} digit-groups are separated:
::<code>commas</code> (default) separates {{var|value}} digit-groups with commas; this is the default, same as when {{para|fmt}} is empty or omitted
::<code>gaps</code> separates {{var|value}} digit-groups with narrow gaps
::<code>none</code> renders {{var|value}} without digit grouping
Note: Using both named and unnamed parameters may produce unexpected results. In this example, the template expects the first unnamed parameter to be a value number:
::<code><nowiki>{{Currency|amount=1000|GBP}}</nowiki></code>
:::{{Currency|amount=1000|GBP}}
When using parameter names, {{para|amount}} and {{para|code}} are preferred.  The template will also accept {{para|Amount}} and {{para|type}} and {{para|Type}}.

==Supported non-standard currency codes==
===Codes that can be translated to ISO 4217 currencies===
These non-standard codes are aliases of standard ISO 4217 codes.
{{Div col|colwidth=15em}}
*EGE
*EU
*EUMELN
*EURO
*FRW
*KNAAK
*KSH
*NEP
*POUND
*POUND STERLING
*RMB
*TEURO
*THE SINGLE CURRENCY
*TSH
*UK
*UNITED STATES
*US
*U.S.
*USA
*USH
{{Div col end}}

===Other non-standard codes===
These codes either do not have a matching ISO 4217 currency code or are alternate versions of existing ISO 4217 codes or support unique aspects of a currency.
*BITCOIN – no matching ISO 4217 code
*BTC – no matching ISO 4217 code
*DKK2 – alternate version of DKK
*FRF – historical
*GRD – historical
*LSL2 – plural version of LSL
*LTL – historical
*NOK2 – alternate version of NOK
*SEK2 – alternate version of SEK
*SZL2 – plural version of SZL
*XBT – no matching ISO 4217 code

== Examples ==
Currencies other than the [[United States dollar]] can be rendered by using the appropriate [[ISO 4217|ISO 4217 currency code]]
*<nowiki>{{Currency|1000|BMD}}</nowiki> gives: {{Currency|1000|BMD}} for the [[Bermudian dollar]]
*<nowiki>{{Currency|1000|BDT}}</nowiki> gives: {{Currency|1000|BDT}} for the [[Bangladeshi taka]]
*<nowiki>{{Currency|1000|AMD}}</nowiki> gives: {{Currency|1000|AMD}} for the [[Armenian dram]]

Some of the more well known currencies also provide the ability to use common abbreviations or full names.
*<nowiki>{{Currency|1000|US}}</nowiki> gives: {{Currency|1000|us}}
*<nowiki>{{Currency|1000|United States}}</nowiki> gives: {{Currency|1000|United States}}
*<nowiki>{{Currency|1,000|JPY}}</nowiki> gives: {{Currency|1,000|JPY}}

Parameter names can also be used, if preferred:
*<nowiki>{{Currency|amount=1000|code=US}}</nowiki> gives: {{Currency|amount=1000|code=US}}
*<nowiki>{{Currency|1000|code=euro}}</nowiki> gives: {{Currency|1000|code=euro}}

Negative amount:
*<nowiki>{{Currency|amount=-1000|code=US}}</nowiki> gives: {{Currency|amount=-1000|code=US}}

Text quantifiers:
*<nowiki>{{Currency|1000 million|code=euro}}</nowiki> gives: {{Currency|1000 million|code=euro}}
*<nowiki>{{Currency|1000M|code=euro}}</nowiki> gives: {{Currency|1000M|code=euro}}

The first use of a currency should show the value and the full name of the currency, so if the "first" parameter is defined then that is what will be given.
*<nowiki>{{Currency|1000|cve|first=yes}}</nowiki> gives: {{Currency|1000|cve|first=yes}}
*<nowiki>{{Currency|1000|cve}}</nowiki> gives: {{Currency|1000|cve}}

Because the symbol for the currencies DKK, NOK, and SEK may be ambiguous, these may be represented in two ways:
*For DKK:
*:<nowiki>{{Currency|1000|dkk}}</nowiki> gives: {{Currency|1000|dkk}}
*:<nowiki>{{Currency|1000|dkk2}}</nowiki> gives: {{Currency|1000|dkk2}}
*For NOK:
*:<nowiki>{{Currency|1000|NOK}}</nowiki> gives: {{Currency|1000|NOK}}
*:<nowiki>{{Currency|1000|NOK2}}</nowiki> gives: {{Currency|1000|NOK2}}
*For SEK:
*:<nowiki>{{Currency|1000|SEK}}</nowiki> gives: {{Currency|1000|SEK}}
*:<nowiki>{{Currency|1000|SEK2}}</nowiki> gives: {{Currency|1000|SEK2}}

Similarly, some currencies use different symbols for single and plural amounts:
*:<nowiki>{{Currency|1|LSL}}</nowiki> gives: {{Currency|1|LSL}}
*:<nowiki>{{Currency|1000|LSL2}}</nowiki> gives: {{Currency|1000|LSL2}}
*::''The template does not currently make this distinction automatically so it is the responsibility of the editor using these kinds of codes to get the code right.''

Digit grouping:
*{{para|fmt|commas}}
*:<nowiki>{{Currency|1000 million|code=euro|fmt=commas}}</nowiki> gives: {{Currency|1000 million|code=euro|fmt=commas}}
*{{para|fmt|gaps}}
*:<nowiki>{{Currency|1000 million|code=euro|fmt=gaps}}</nowiki> gives: {{Currency|1000 million|code=euro|fmt=gaps}}
*{{para|fmt|none}}
*:<nowiki>{{Currency|1000 million|code=euro|fmt=none}}</nowiki> gives: {{Currency|1000 million|code=euro|fmt=none}}

==Error messages==
{{tld|currency}} can produce several error message.  These are:
*<span style="font-size:inherit" class="error"><nowiki>{{currency}}</nowiki> – invalid code</span> – the value in the second unnamed parameter or assigned to {{para|code}} cannot be found in the template's list of codes.  Make sure that the assigned code is a correct ISO 4217 currency code or one of the supported non-standard codes listed above.
*<span style="font-size:inherit" class="error"><nowiki>{{currency}}</nowiki> – invalid amount</span> – the value in the first unnamed parameter or assigned to {{para|amount}} contains one or more characters that is not a minus sign, a digit, comma, or decimal point, or has some text that is not one of the permitted quantifiers.  Make sure that comma separators group three digits and that the number has only one decimal point.  Make sure that the amount and code parameters are either both named ({{para|amount}} and {{para|code}}) or both unnamed.
*<span style="font-size:inherit" class="error"><nowiki>{{currency}}</nowiki> – definition missing position</span> – an internal error that should only occur when an editor is mucking about in [[Module:Currency/Presentation]].  It indicates that [[Module:Currency]] doesn't know where to place the currency's symbol in relation to its value.
*<span style="font-size:inherit" class="error"><nowiki>{{currency}}</nowiki> – definition missing page</span> – an internal error that should only occur when an editor is mucking about in Module:Currency/Presentation.  It indicates that Module:Currency doesn't have a page that it can use to link the currency's symbol or name.

==TemplateData==
{{TemplateData header}}
<templatedata>
{
	"params": {
		"amount": {
			"aliases": [
				"Amount"
			],
			"description": "the value in the given currency",
			"default": "1",
			"suggested": true,
			"type": "string"
		},
		"code": {
			"aliases": [
				"type",
				"Type"
			],
			"description": "The currency represented",
			"example": "USD",
			"default": "USD",
			"suggested": true,
			"type": "string"
		},
		"first": {
			"description": "when set to any value, produces a long-form currency name"
		},
		"linked": {
			"description": "Whether to link to the article on that currency",
			"example": "no",
			"default": "yes",
			"type": "string"
		},
		"fmt": {
			"description": "specifies how value digit-groups are separated (commas, spaces, etc.)",
			"example": "gaps",
			"default": "commas",
			"type": "string"
		}
	}
}
</templatedata>
== See also ==
* [[Wikipedia:Manual of Style (dates and numbers)#Currencies]] for important usage pattern instructions.
* {{tl|Format price}}, a template that handles rounding and "big number" formatting
* {{tl|Inflation}}, a template that adjusts historical costs to current (or other-year) equivalent value
* {{tlx|Infobox currency}}
<includeonly>{{sandbox other||
[[Category:Currency templates]]
[[Category:Finance templates]]

}}</includeonly>