Currency

What it does

The currency component is an input field specialized to capture amounts in a particular currency.

When the input field doesn't have the focus, it shows a formatted currency, such as 1,234.00. When the control has the focus, it shows the plain number, such as 1234 to facilitate input.

While working with currency amounts, the component is careful not to do any manipulation that relies on how numbers are represented on a particular platform, to avoid any possibility of rounding or precision error.

Basic usage

You use the number component like a regular input field, for example:

<fr:currency ref="my-amount">
  <xf:label>Amount</xf:label>
</fr:currency>

Parameters

fr:currency supports parameters, which you can set via properties or directly on fr:currency:

• prefix: optional prefix shown before the number ( by default the dollar sign)

• suffix: optional suffix shown after the number

• digits-after-decimal: digits to show after the decimal point (by default 2)

• decimal-separator: single character to use as decimal separator

• grouping-separator: single character to use as thousands separator separator (can be blank)

• round-when-formatting: when formatting the number for display, whether to round the value to digits-after-decimal if there are more digits after the decimal point or not. The default is false.

  • SINCE Orbeon Forms 2016.1

  • UNTIL Orbeon Forms 2017.2: Rounding uses the half to even method.

  • SINCE Orbeon Forms 2018.1: Rounding uses the half up method.

• round-when-storing: when storing the number entered by the user, whether to round the value to digits-after-decimal if there are more digits after the decimal point or not. The default is false.

  • SINCE Orbeon Forms 2016.1

  • UNTIL Orbeon Forms 2017.2: Rounding uses the half to even method.

  • SINCE Orbeon Forms 2018.1: Rounding uses the half up method.

These are the default values of the properties:

<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.currency.prefix"
    value="$"/>
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.currency.suffix"
    value=""/>
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.currency.digits-after-decimal"
    value="2"/>
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.currency.decimal-separator"
    value="."/>
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.currency.grouping-separator"
    value=","/>
<property
    as="xs:boolean"
    name="oxf.xforms.xbl.fr.currency.round-when-formatting"
    value="false"/>
<property
    as="xs:boolean"
    name="oxf.xforms.xbl.fr.currency.round-when-storing"
    value="false"/>

Currency prefix

By default the dollar sign ("$") is used as a currency prefix. You can override this either:

• Globally for all your forms in your ‘properties-local.xml’ by setting the following property:

<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.currency.prefix"
    value="£"/>

• For a particular instance of the component:

  • With the prefix attribute, for static values.

  • With the <fr:prefix> element, for dynamic values.

Digits after the decimal sign

By default, the component shows the value to 2 digits after the decimal sign. You can override this either:

• Globally for all your forms in your properties-local.xml by setting the following property:

<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.currency.digits-after-decimal"
    value="3"/>

• For a particular instance of the component:

  • With the digits-after-decimal attribute, for static values.

  • With the <fr:digits-after-decimal> element, for dynamic values.

If you set digits-after-decimal to 0, then the decimal separator isn't shown. The component truncates any additional digits beyond the specified number; it doesn't perform rounding.

Examples

Control without focus

<fr:currency ref="value"/>

Setting a static prefix with the prefix attribute

<fr:currency ref="value" prefix="£"/>

Setting a dynamic prefix with the fr:prefix element

<fr:currency ref="value">
    <fr:prefix ref="/config/prefix"/>
</fr:currency>

Showing 3 digits after decimal sign

<fr:currency
    ref="value"
    digits-after-decimal="3/>

Showing 0 digits after the decimal sign

<fr:currency
    ref="value"
    digits-after-decimal="0/>

Read-only input field, because bound to node set as read-only with a MIP

<xforms:bind ref="readonly-node" readonly="true()"/>

<fr:currency ref="readonly-node"/>

Rounding

[SINCE Orbeon Forms 2016.1]

For examples of rounding, see the fr:number component.