View source for Template:ZARConvert/doc

{{Documentation subpage}}
<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata -->
<!-- EDIT TEMPLATE DOCUMENTATION BELOW THIS LINE -->
__NOTOC__

==Purpose==
The purpose of this template is to automatically convert and format [[South African rands]] applying adjustment for inflation where appropriate. Rates of exchange and inflation must be [[#Updating|manually copied by editors]] in the supporting templates therefore this template's output does not necessarily reflect the present exchange rates or price indices but, rather, reflects the rates and indices at the time of the last update.

The default target currency ([[USD]] at present) may change in the future.

The possibility of converting to other target currencies in the future is left open, hence the general name of this template.

==Usage==
<code><nowiki>{{ZARConvert|value|currency_units|year=|to=|r=|force=|lk=|exact=|showdate=|ref=|mode=|convert=}}</nowiki></code>

== Parameters ==
A description of the template's parameters are listed below.  

{|class="wikitable"
|style="background-color: #A52A2A; font-weight: bolder; color: #FFF5EE;" |Field name ||style="background-color: #A52A2A; font-weight: bolder; color: #FFF5EE;"| Usage ||style="background-color: #A52A2A; font-weight: bolder; color: #FFF5EE;"| Example ||style="background-color: #A52A2A; font-weight: bolder; color: #FFF5EE;" | Description

|-
|-
|<code>'''value'''</code> ||mandatory|| 10000.01 ||The value, in the country_code currency, that needs to be converted.  The template will not accept pre-formatted values (i.e. 1,234).
|-
|<code>'''currency_units'''</code>||optional || m || Used to represent smaller or larger numbers. Available options are as follows.
* <code>ct</code> &ndash; to represent cent(s)
* <code>p</code> &ndash; to represent penny (pence)
* <code>pa</code> &ndash; to represent paisa (paise) (generalized to mean cents)
* <code>po</code> &ndash; to represent poysha (generalized to mean cents)
* <code>ba</code> &ndash; to represent baisa(s) (generalized to mean 1/1000)
* <code>k</code> &ndash; to represent thousand(s)
* <code>m</code> &ndash; to represent million(s)
* <code>b</code> &ndash; to represent short scale billion(s)
* <code>t</code> &ndash; to represent short scale trillion(s)
* <code>l</code> &ndash; to represent lakh(s)
* <code>c</code> &ndash; to represent crore(s)
* <code>lc</code> &ndash; to represent lakh crore(s)

* '''Brackets in the sense may be singular (or) plural'''.

The Indian units can be applied to any currency. 

|-
|<code>'''lk'''</code> ||optional || lk=on || This parameter gives you the option of internally linking currency names (paise, which is generalized here to mean cents in the source currency) and/or number names (billion, trillion, lakh, crore).  By default, the parameter is set to "off" (i.e. it is set not to link).  Available options are as follows.
* <code>on</code> &ndash; to link all units
* <code>source</code> &ndash; to link the source value
* <code>original</code> &ndash; to link the values in the original currency
* <code>inflated</code> &ndash; to link the inflated value in the original currency
* <code>result</code> &ndash; to link the inflated and converted vales
* <code>converted</code> &ndash; to link the converted value
* <code>source-converted</code> &ndash; to link the source and converted values
|-
|<code>'''year'''</code> ||optional || year=2002 || This parameter allows entering values from previous years. The year will be displayed and historic values will be inflated to the latest year available in {{t|Inflation}} if <code>'''index'''</code> is also provided then converted by {{t|ToUSD}}. If no index name is present, the conversion will be attempted for the year indicated (but see <code>'''force'''</code>). If <code>'''year'''</code> is not provided, just a conversion will be performed at the most current rate available.
|-
|<code>'''to'''</code> ||optional || to=EUR || This parameter allows for conversion to various different currencies. Currently, the USD (default) and the euro are supported.
|-
|<code>'''r'''</code> ||optional || r=3 || Sets the digits to which the results must be rounded. A negative value indicates rounding to an upper significant digit, and a positive value indicates a [[fractional digit]] including [[trailing zeros]]. Defaults to <code>2</code>.
|-
|<code>'''force'''</code> ||optional || force=yes || This parameter allows to force a conversion at the most current rate available when data is lacking for the provided year when its value is <code>'''yes'''</code>.
|-
|<code>'''exact'''</code> ||optional || exact=source || This provides some control over formatting. <code>'''source'''</code> requests to display the input value normally (in American fashion) after applying the units. <code>'''on'''</code> does this for both the input and result values. Otherwise all values will be displayed as per {{t|Format price}}.
|-
|<code>'''showdate'''</code> ||optional || showdate=no || This allows to disable displaying the original year.
|-
|<code>'''ref'''</code> ||optional || <nowiki>ref=<ref>some wikitext ref</ref></nowiki> || This allows displaying one or more references next to the original value. Each one must consist of a ref wikitext element.
|-
|<code>'''mode'''</code> ||optional || mode=historical || This parameter controls the output mode. Setting it to blank or omitting it results in the default mode. Setting it to <code>historical</code> allows conversion using historical exchange rates.
|-
|<code>'''convert'''</code> ||optional || convert=no|| This parameter controls the currency conversion. Setting it to blank or omitting it results in the default mode. Setting it to <code>no</code> disables it.
|}

==Examples==

{|class="wikitable"
!ZARConvert syntax || Results
|-
| <code><nowiki>{{ZARConvert|1|ct|lk=on}}</nowiki></code> || {{ZARConvert|1|ct|lk=on}}
|-
| <code><nowiki>{{ZARConvert|10|ct}}</nowiki></code> || {{ZARConvert|10|ct}}
|-
| <code><nowiki>{{ZARConvert|1|ct|exact=source}}</nowiki></code> || {{ZARConvert|1|ct|exact=source}}
|-
| <code><nowiki>{{ZARConvert|10|ct|exact=source}}</nowiki></code> || {{ZARConvert|10|ct|exact=source}}
|-
| <code><nowiki>{{ZARConvert|1|ct|exact=on}}</nowiki></code> || {{ZARConvert|1|ct|exact=on}}
|-
| <code><nowiki>{{ZARConvert|10|ct|exact=on}}</nowiki></code> || {{ZARConvert|10|ct|exact=on}}
|-
| <code><nowiki>{{ZARConvert|1|ct|year=2002}}</nowiki></code> || {{ZARConvert|1|ct|year=2002}}
|-
| <code><nowiki>{{ZARConvert|10|ct|year=2002}}</nowiki></code> || {{ZARConvert|10|ct|year=2002}}
|-
| <code><nowiki>{{ZARConvert|1|ct|year=2002|mode=historical}}</nowiki></code> || {{ZARConvert|1|ct|year=2002|mode=historical}}
|-
| <code><nowiki>{{ZARConvert|10|ct|year=2002|mode=historical}}</nowiki></code> || {{ZARConvert|10|ct|year=2002|mode=historical}}
|-
| <code><nowiki>{{ZARConvert|1|ct|year=2002|lk=on}}</nowiki></code> || {{ZARConvert|1|ct|year=2002|lk=on}}
|-
| <code><nowiki>{{ZARConvert|10|ct|year=2002|lk=on}}</nowiki></code> || {{ZARConvert|10|ct|year=2002|lk=on}}
|-
| <code><nowiki>{{ZARConvert|1|ct|year=2002|exact=on}}</nowiki></code> || {{ZARConvert|1|ct|year=2002|exact=on}}
|-
| <code><nowiki>{{ZARConvert|10|ct|year=2002|exact=on}}</nowiki></code> || {{ZARConvert|10|ct|year=2002|exact=on}}
|- 
| ||
|-
| <code><nowiki>{{ZARConvert|1|ct|lk=on|convert=no}}</nowiki></code> || {{ZARConvert|1|ct|lk=on|convert=no}}
|-
| <code><nowiki>{{ZARConvert|10|ct|convert=no}}</nowiki></code> || {{ZARConvert|10|ct|convert=no}}
|-
| <code><nowiki>{{ZARConvert|1|ct|exact=source|convert=no}}</nowiki></code> || {{ZARConvert|1|ct|exact=source|convert=no}}
|-
| <code><nowiki>{{ZARConvert|10|ct|exact=source|convert=no}}</nowiki></code> || {{ZARConvert|10|ct|exact=source|convert=no}}
|-
| <code><nowiki>{{ZARConvert|1|ct|exact=on|convert=no}}</nowiki></code> || {{ZARConvert|1|ct|exact=on|convert=no}}
|-
| <code><nowiki>{{ZARConvert|10|ct|exact=on|convert=no}}</nowiki></code> || {{ZARConvert|10|ct|exact=on|convert=no}}
|-
| <code><nowiki>{{ZARConvert|1|ct|year=2002|convert=no}}</nowiki></code> || {{ZARConvert|1|ct|year=2002|convert=no}}
|-
| <code><nowiki>{{ZARConvert|10|ct|year=2002|convert=no}}</nowiki></code> || {{ZARConvert|10|ct|year=2002|convert=no}}
|-
| <code><nowiki>{{ZARConvert|1|ct|year=2002|mode=historical|convert=no}}</nowiki></code> || {{ZARConvert|1|ct|year=2002|mode=historical|convert=no}}
|-
| <code><nowiki>{{ZARConvert|10|ct|year=2002|mode=historical|convert=no}}</nowiki></code> || {{ZARConvert|10|ct|year=2002|mode=historical|convert=no}}
|-
| <code><nowiki>{{ZARConvert|1|ct|year=2002|lk=on|convert=no}}</nowiki></code> || {{ZARConvert|1|ct|year=2002|lk=on|convert=no}}
|-
| <code><nowiki>{{ZARConvert|10|ct|year=2002|lk=on|convert=no}}</nowiki></code> || {{ZARConvert|10|ct|year=2002|lk=on|convert=no}}
|-
| <code><nowiki>{{ZARConvert|1|ct|year=2002|exact=on|convert=no}}</nowiki></code> || {{ZARConvert|1|ct|year=2002|exact=on|convert=no}}
|-
| <code><nowiki>{{ZARConvert|10|ct|year=2002|exact=on|convert=no}}</nowiki></code> || {{ZARConvert|10|ct|year=2002|exact=on|convert=no}}
|- 
| ||
|-
| <code><nowiki>{{ZARConvert|1}}</nowiki></code> || {{ZARConvert|1}}
|-
| <code><nowiki>{{ZARConvert|1|k}}</nowiki></code> || {{ZARConvert|1|k}}
|-
| <code><nowiki>{{ZARConvert|1|m}}</nowiki></code> || {{ZARConvert|1|m}}
|-
| <code><nowiki>{{ZARConvert|1|b|lk=on}}</nowiki></code> || {{ZARConvert|1|b|lk=on}}
|-
| <code><nowiki>{{ZARConvert|1|t|lk=on}}</nowiki></code> || {{ZARConvert|1|t|lk=on}}

|-
| <code><nowiki>{{ZARConvert|1|exact=source}}</nowiki></code> || {{ZARConvert|1|exact=source}}
|-
| <code><nowiki>{{ZARConvert|1|k|exact=source}}</nowiki></code> || {{ZARConvert|1|k|exact=source}}
|-
| <code><nowiki>{{ZARConvert|1|m|exact=source}}</nowiki></code> || {{ZARConvert|1|m|exact=source}}
|-
| <code><nowiki>{{ZARConvert|1|b|exact=source}}</nowiki></code> || {{ZARConvert|1|b|exact=source}}
|-
| <code><nowiki>{{ZARConvert|1|t|exact=source}}</nowiki></code> || {{ZARConvert|1|t|exact=source}}

|-
| <code><nowiki>{{ZARConvert|1|exact=on}}</nowiki></code> || {{ZARConvert|1|exact=on}}
|-
| <code><nowiki>{{ZARConvert|1|k|exact=on}}</nowiki></code> || {{ZARConvert|1|k|exact=on}}
|-
| <code><nowiki>{{ZARConvert|1|m|exact=on}}</nowiki></code> || {{ZARConvert|1|m|exact=on}}
|-
| <code><nowiki>{{ZARConvert|1|b|exact=on}}</nowiki></code> || {{ZARConvert|1|b|exact=on}}
|-
| <code><nowiki>{{ZARConvert|1|t|exact=on}}</nowiki></code> || {{ZARConvert|1|t|exact=on}}

|-
| <code><nowiki>{{ZARConvert|1|year=2002}}</nowiki></code> || {{ZARConvert|1|year=2002}}
|-
| <code><nowiki>{{ZARConvert|1|k|year=2002}}</nowiki></code> || {{ZARConvert|1|k|year=2002}}
|-
| <code><nowiki>{{ZARConvert|1|m|year=2002}}</nowiki></code> || {{ZARConvert|1|m|year=2002}}
|-
| <code><nowiki>{{ZARConvert|1|b|year=2002}}</nowiki></code> || {{ZARConvert|1|b|year=2002}}
|-
| <code><nowiki>{{ZARConvert|1|t|year=2002}}</nowiki></code> || {{ZARConvert|1|t|year=2002}}

|-
| <code><nowiki>{{ZARConvert|1|year=2002|lk=on}}</nowiki></code> || {{ZARConvert|1|year=2002|lk=on}}
|-
| <code><nowiki>{{ZARConvert|1|k|year=2002|lk=on}}</nowiki></code> || {{ZARConvert|1|k|year=2002|lk=on}}
|-
| <code><nowiki>{{ZARConvert|1|m|year=2002|lk=on}}</nowiki></code> || {{ZARConvert|1|m|year=2002|lk=on}}
|-
| <code><nowiki>{{ZARConvert|1|b|year=2002|lk=on}}</nowiki></code> || {{ZARConvert|1|b|year=2002|lk=on}}
|-
| <code><nowiki>{{ZARConvert|1|t|year=2002|lk=on}}</nowiki></code> || {{ZARConvert|1|t|year=2002|lk=on}}
|-
| ||
|-
| <code><nowiki>{{ZARConvert|3.60}}</nowiki></code> || {{ZARConvert|3.60}}
|-
| <code><nowiki>{{ZARConvert|360}}</nowiki></code> || {{ZARConvert|360}}
|-
| <code><nowiki>{{ZARConvert|3600}}</nowiki></code> || {{ZARConvert|3600}}
|-
| <code><nowiki>{{ZARConvert|360000}}</nowiki></code> || {{ZARConvert|360000}}
|-
| <code><nowiki>{{ZARConvert|3600000}}</nowiki></code> || {{ZARConvert|3600000}}
|-
| <code><nowiki>{{ZARConvert|3.6|m}}</nowiki></code> || {{ZARConvert|3.6|m}}
|- 
| ||
|-
| <code><nowiki>{{ZARConvert|3650000}}</nowiki></code> || {{ZARConvert|3650000}}
|-
| <code><nowiki>{{ZARConvert|3.65|m}}</nowiki></code> || {{ZARConvert|3.65|m}}
|-
| <code><nowiki>{{ZARConvert|3650000|year=1960}}</nowiki></code> || {{ZARConvert|3650000|year=1960}}
|-
| <code><nowiki>{{ZARConvert|3.65|m|year=1960}}</nowiki></code> || {{ZARConvert|3.65|m|year=1960}}
|-
| <code><nowiki>{{ZARConvert|3650000|year=1960|exact=source}}</nowiki></code> || {{ZARConvert|3650000|year=1960|exact=source}}
|-
| <code><nowiki>{{ZARConvert|3.65|m|year=1960|exact=source}}</nowiki></code> || {{ZARConvert|3.65|m|year=1960|exact=source}}
|-
| <code><nowiki>{{ZARConvert|3650000|year=1960|force=yes}}</nowiki></code> || {{ZARConvert|3650000|year=1960|force=yes}}
|-
| <code><nowiki>{{ZARConvert|3.65|m|year=1960|force=yes}}</nowiki></code> || {{ZARConvert|3.65|m|year=1960|force=yes}}
|-
| <code><nowiki>{{ZARConvert|3650000|year=1960|force=yes|exact=on}}</nowiki></code> || {{ZARConvert|3650000|year=1960|force=yes|exact=on}}
|-
| <code><nowiki>{{ZARConvert|3.65|m|year=1960|force=yes|exact=on}}</nowiki></code> || {{ZARConvert|3.65|m|year=1960|force=yes|exact=on}}
|-
| <code><nowiki>{{ZARConvert|3650000|year=2002}}</nowiki></code> || {{ZARConvert|3650000|year=2002}}
|-
| <code><nowiki>{{ZARConvert|3.65|m|year=2002}}</nowiki></code> || {{ZARConvert|3.65|m|year=2002}}
|-
| <code><nowiki>{{ZARConvert|3650000|year=2002|exact=on}}</nowiki></code> || {{ZARConvert|3650000|year=2002|exact=on}}
|-
| <code><nowiki>{{ZARConvert|3.65|m|year=2002|exact=on}}</nowiki></code> || {{ZARConvert|3.65|m|year=2002|exact=on}}
|-
| <code><nowiki>{{ZARConvert|3650000|year=2002|exact=source}}</nowiki></code> || {{ZARConvert|3650000|year=2002|exact=source}}
|-
| <code><nowiki>{{ZARConvert|3.65|m|year=2002|exact=source}}</nowiki></code> || {{ZARConvert|3.65|m|year=2002|exact=source}}
|-
| <code><nowiki>{{ZARConvert|3650000|year=2002|exact=on}}</nowiki></code> || {{ZARConvert|3650000|year=2002|exact=on}}
|-
| <code><nowiki>{{ZARConvert|3.65|m|year=2002|exact=on}}</nowiki></code> || {{ZARConvert|3.65|m|year=2002|exact=on}}
|- 
| ||
|-
| <code><nowiki>{{ZARConvert|3600000|year=1962|ref=<ref name="qv">something1</ref>}}</nowiki></code> || {{ZARConvert|3600000|year=1962|ref=<ref name="qv">something1</ref>}}
|-
| <code><nowiki>{{ZARConvert|3600000|year=1962|ref=<ref name="qv">something1</ref><ref>something2</ref>}}</nowiki></code> || {{ZARConvert|3600000|year=1962|ref=<ref name="qv">something1</ref><ref>something2</ref>}}
|- 
| ||
|-
| <code><nowiki>{{ZARConvert|3600000|year=2011|to=EUR|ref=<ref name="qv">something1</ref>}}</nowiki></code> || {{ZARConvert|3600000|year=2011|to=EUR|ref=<ref name="qv">something1</ref>}}
|-
| <code><nowiki>{{ZARConvert|3600000|year=2011|to=EUR|showdate=no|ref=<ref name="qv">something1</ref>}}</nowiki></code> || {{ZARConvert|3600000|year=2011|to=EUR|showdate=no|ref=<ref name="qv">something1</ref>}}
|}
{{reflist}}

==See also==
*{{tl|FXConvert}}:  Inflates and converts a given currency to US dollars or Euro. It is used by {{tl|ZARConvert}}.

==TemplateData==
{{TemplateDataHeader}}
<templatedata>
{
	"params": {
		"1": {
			"label": "Value",
			"description": "The value, in the source, that needs to be converted. The template will not accept pre-formatted values (i.e. 1,234).",
			"example": "500000000",
                        "type": "number",
			"required": true
		},
		"2": {
			"label": "Currency units",
			"description": "Use this to represent larger numbers such as crores, billions et al.",
			"example": "c, lc, b, m, k, cr, p, pa, po, ba",
                        "type": "line",
			"suggested": true
		},
		"lk": {
			"label": "Linking",
			"description": "Gives option to whether link currency names (paise, etc.) or number names (crores, lakhs, billions, trillions)",
			"example": "on, off, source, original, inflated, result, converted, source-converted",
                        "type": "line",
		        "suggested": true
		},
		"year": {
			"description": "This parameter allows for inflation. Historic values will be inflated to the most current values available then converted.",
			"example": "2015",
			"label": "Year",
                        "type": "number",
			"suggested": true
		},
        "to": {
			"description": "This parameter allows for conversion to various different currencies.  The USD (default) and the euro are currently supported.",
			"example": "EUR",
			"default": "USD",
			"label": "To"
		},
        "r": {
			"label": "Rounding digits",
			"description": "Used to round significant digits. A value of \"0\" will drop paise or cent values from the converted number. By default the conversion will be rounded to two significant figures.",
			"example": "0",
                        "type": "number"
		},
        "force": {
			"label": "Force",
			"description": "This parameter allows to force a conversion at the most current rate available when data is lacking for the provided year when its value is \"yes\".",
			"example": "yes",
                        "type": "line"
		},
        "exact": {
			"label": "Exact",
			"description": "This provides some control over formatting. \"source\" requests to display the input value normally (in American fashion) after applying the units. \"on\" does this for both the input and result values. Otherwise all values will be displayed as per Format price.",
			"example": "source, on",
                        "type": "line"
		},
        "showdate": {
			"label": "Show date",
			"description": "This allows to disable displaying the original year.",
			"example": "no",
                        "type": "line"
		},
        "ref": {
			"label": "References",
			"description": "This allows displaying one or more references next to the original value. Each one must consist of a ref wikitext element.",
			"example": "<ref>some wikitext ref</ref>",
                        "type": "content",
                        "suggested": true
		},
        "mode": {
			"description": "This parameter allows for the control of the output mode. Currently, blank (default) and historical are supported. In historical mode, conversions are performed using a historical exchange rate, for the year supplied.",
			"example": "historical",
			"default": "(blank)",
			"label": "Mode",
                        "type": "line"
		},
                "convert": {
			"description": "This parameter controls the currency conversion. Setting it to blank or omitting it results in the default mode. Setting it to <code>no</code> disables it.",
			"example": "no",
			"default": "(blank)",
			"label": "Convert",
                        "type": "line"
		}
	},
	"paramOrder": [
		"1",
		"2",
        "lk",
		"year",
        "to",
		"r",
        "force",
        "exact",
        "showdate",
        "ref",
        "mode",
        "convert"
	],
	"description": "Template calculates a value of South African rands, which you can enter, to US dollars and then presents the results."
}
</templatedata>

<!-- ADD CATEGORIES BELOW THIS LINE -->
<includeonly>{{Sandbox other||
{{DEFAULTSORT:{{BASEPAGENAME}}}}
[[Category:Currency conversion templates]]
}}</includeonly>