Currency

Currency Field Type

Description:
The currency field type is designed to capture monetary values, allowing users to enter amounts with proper formatting, precision, and currency symbols. This field ensures that financial data is accurately recorded and presented consistently throughout your application.

YAML Definition

- name: total_amount
  type: currency
  display_name: "Total Amount"
  symbol: "$"
  precision: 2
  guidance: "Enter the total amount in USD."
  required: true
  default_value: 0.00

Attributes

name (string): Required.
The unique identifier for the field.
type (string): Required.
Must be set to currency for currency fields.
display_name (string): Optional.
The label displayed in the user interface. If not provided, a formatted version of name is used.
symbol (string): Optional.
The currency symbol to display alongside the amount (e.g., $, €, £). This helps users recognize the currency in which the amount is denominated.
precision (number): Optional.
The number of decimal places to use. Defaults to 2, which is standard for most currencies.
guidance (string): Optional.
Help text or instructions for the field to assist users in providing the correct information.
required (boolean): Optional.
If true, the field must be filled before submission.
default_value (number): Optional.
The default amount displayed when the form is first loaded.
readonly (boolean): Optional.
If true, the field is read-only and cannot be edited by the user.
hidden (boolean): Optional.
If true, the field is hidden from the user interface.
display_currency_selector (boolean): Optional.
If true, a dropdown is displayed allowing users to select from a list of predefined currencies.
options (string[]): Optional.
An array of currency codes (e.g., ["USD", "EUR", "GBP"]) to be used when display_currency_selector is true.

Example

- name: invoice_total
  type: currency
  display_name: "Invoice Total"
  symbol: "€"
  precision: 2
  guidance: "Enter the total amount for the invoice."
  required: true
  default_value: 0.00
  display_currency_selector: true
  options:
    - "USD"
    - "EUR"
    - "GBP"
    - "AUD"
    - "CAD"

In this example:

invoice_total: The field captures the total amount of an invoice.
symbol: Set to €, indicating the default currency is Euro.
precision: Amounts will display with two decimal places.
display_currency_selector: Enabled to allow users to select a different currency from the provided options.
options: Users can choose from USD, EUR, GBP, AUD, or CAD currencies.

Usage Notes

Currency Symbol: Use the symbol attribute to match the default currency. This symbol appears next to the amount, providing clear context.
Precision: Adjust the precision based on the currency’s smallest unit. While most currencies use two decimal places, some may require zero or three.
Default Values: Providing a default_value can enhance user experience by pre-filling the field with a common amount, such as 0.00.
Required Fields: If the amount is mandatory, set required to true to enforce validation.
Currency Selection:
- Enable display_currency_selector to support multiple currencies.
- Use the options array to specify which currencies are available for selection.
- Ensure that the symbol updates dynamically based on the selected currency, if applicable.
Read-Only Fields: Set readonly to true for calculated amounts that should not be edited directly by users, such as totals derived from other fields.
Formatting: The field should automatically handle formatting, including thousands separators and decimal points, according to the specified precision.
Internationalization: Consider user locale settings for currency symbols and formats to provide a localized experience.
Validation:
- Ensure that the input is a valid number within any specified constraints.
- Implement server-side validation to prevent injection of invalid or malicious data.
Guidance: Use the guidance attribute to provide users with instructions or examples, reducing input errors.

By integrating the currency field type into your schema, you facilitate precise and user-friendly input of financial data. This is crucial for applications involving transactions, budgeting, invoicing, and financial reporting, where accuracy and clarity are paramount.