Currency Widget Documentation

Overview​

The Currency widget provides a specialized input field for monetary values with built-in currency formatting, locale support, and validation. It automatically formats numbers according to the selected currency and locale, making it ideal for financial applications, e-commerce platforms, and any interface requiring monetary input.

Features​

• Multiple Currency Support: Supports major international currencies
• Locale Formatting: Automatic number formatting based on locale settings
• Precision Control: Configurable decimal places (0-20)
• Negative Values: Optional support for negative amounts
• Real-time Formatting: Formats input as user types
• Validation: Built-in validation rules with custom messages
• Responsive Design: Adapts to different screen sizes

Basic Configuration​

Widget Properties​

Currency Settings​

Currency Selection​

Choose from supported currencies:

• EUR - Euro
• USD - US Dollar
• GBP - British Pound
• MAD - Moroccan Dirham
• BRL - Brazilian Real
• INR - Indian Rupee
• CNY - Chinese Yuan
• JPY - Japanese Yen
• SAR - Saudi Riyal
• IRR - Iranian Rial

Locale Configuration​

Set the locale for number formatting:

• en-US - English (United States)
• en-GB - English (United Kingdom)
• fr-FR - French (France)
• de-DE - German (Germany)
• es-ES - Spanish (Spain)
• pt-BR - Portuguese (Brazil)
• zh-CN - Chinese (Simplified)
• ja-JP - Japanese
• ar-SA - Arabic (Saudi Arabia)

Precision Settings​

• Precision: Number of decimal places (0-20)
• Allow Negative: Toggle to permit negative values

Configuration Interface​

Global Settings​

1. Name: Enter a descriptive label for your currency field
2. Variable/Model: Define the variable name (e.g., amount, price, total)
3. Default Value: Set an initial currency value (optional)

Currency Configuration​

1. Local: Select the locale for number formatting
   • Affects decimal separators, thousand separators
   • Determines currency symbol placement
2. Currency: Choose the currency type
   • Can be set to "hidden" to hide currency symbol
   • Supports dynamic currency selection via variables
3. Allow Negative: Enable negative value input
   • Useful for discounts, refunds, or adjustments
4. Precision: Set decimal places
   • Range: 0-20
   • Common values: 2 for most currencies, 0 for whole numbers

Validation Rules​

The currency widget supports comprehensive validation:

Built-in Validation​

• Required Field: Mark field as mandatory
• Type Validation: Ensures numeric input only
• Range Validation: Set minimum and maximum values

Custom Validation Rules​

Add custom validation rules with:

• Rule Type: Select from available validation rules
• Value: Set the validation parameter
• Message: Custom error message for validation failure

Style Configuration​

Layout Options​

• Width: Set field width (e.g., "100%", "200px")
• Placeholder: Hint text shown when field is empty
• Class: CSS classes for custom styling

Responsive Behavior​

• Layout: Choose between block and inline display
• Border: Toggle field border visibility

Advanced Features​

Dynamic Currency Settings​

Currency and locale can be set dynamically using variables:

// Dynamic currency from variable
currency: "${variable_name}"

// Dynamic locale from variable  
currency_local: "${locale_variable}"

Event Handling​

onChange Event​

Triggered when the currency value changes:

• Access new value via event parameter
• Useful for calculations, validations, or API calls
• Can trigger custom actions and functions

Validation Screens​

Configure widget behavior across different interface screens:

Screen-based Settings​

• Available: Show/hide widget per screen
• Visible: Control visibility with conditions
• Required: Make field mandatory per screen
• Disabled: Disable input per screen

Advanced Conditions​

Use JavaScript expressions for dynamic behavior:

// Show only if order total > 100
${order_total} > 100

// Required for premium users
${user.type} === 'premium'

Usage Examples​

Basic E-commerce Price Input​

// Configuration
Name: "Product Price"
Variable: "product_price" 
Currency: "USD"
Locale: "en-US"
Precision: 2
Allow Negative: false

Multi-currency Order System​

// Configuration  
Name: "Order Amount"
Variable: "order_amount"
Currency: "${selected_currency}" // Dynamic from dropdown
Locale: "${user_locale}" // Dynamic from user profile  
Precision: 2

Financial Calculator​

// Configuration
Name: "Investment Amount"  
Variable: "investment"
Currency: "USD"
Precision: 2
Allow Negative: false
Validation: {
  min: 1000,
  max: 1000000,
  message: "Amount must be between $1,000 and $1,000,000"
}

Integration Tips​

Form Integration​

• Works seamlessly within form containers
• Inherits form validation behavior
• Supports form submission and reset

API Integration​

• Values stored as numbers for easy API transmission
• Format display vs. stored value handled automatically
• Compatible with REST APIs and GraphQL

Data Binding​

• Two-way data binding with form models
• Real-time updates to connected components
• Automatic type conversion and validation

Best Practices​

User Experience​

1. Clear Labels: Use descriptive field names
2. Helpful Placeholders: Provide example formats
3. Immediate Feedback: Show formatting as user types
4. Error Messages: Clear, actionable validation messages

Performance​

1. Efficient Updates: Use onChange events judiciously
2. Validation Timing: Balance real-time vs. submit validation
3. Currency Loading: Cache currency data when possible

Accessibility​

1. Keyboard Navigation: Ensure full keyboard accessibility
2. Screen Readers: Provide appropriate ARIA labels
3. Color Contrast: Maintain readable text contrast
4. Focus Management: Clear focus indicators

Troubleshooting​

Common Issues​

Currency Not Formatting

• Check locale setting matches expected format
• Verify currency code is supported
• Ensure precision setting is appropriate

Validation Not Working

• Review validation rules configuration
• Check required field settings per screen
• Verify custom validation expressions

Value Not Saving

• Confirm variable/model name is unique
• Check form submission configuration
• Verify data binding is properly configured

Browser Compatibility​

• Modern browsers with JavaScript ES6+ support
• Vue.js 2.x compatibility required
• Currency formatting uses Intl.NumberFormat API

Support​

For additional assistance with currency widget configuration:

1. Check validation error messages for specific guidance
2. Review browser console for JavaScript errors
3. Test with different currency/locale combinations
4. Verify integration with your specific form setup