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

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​

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:

Usage Examples​

Basic E-commerce Price Input​

Financial Calculator​

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