Switch Widget Documentation

Overview​

The Switch widget provides a toggle control that allows users to switch between two states (on/off, true/false). It's ideal for boolean settings, feature toggles, and binary choices in forms and interfaces.

Basic Configuration​

Widget Properties​

Name​

• Description: Display label for the switch widget
• Type: Text
• Required: Yes
• Usage: This text appears as the label next to the switch control

Variable/Model​

• Description: The data binding variable that stores the switch state
• Type: String
• Required: Yes
• Format: Use camelCase naming convention (e.g., isEnabled, showDetails)
• Note: This variable will contain true when switch is on, false when off

Value Configuration​

Default Value​

• Description: Initial state of the switch when the interface loads
• Type: Boolean
• Options:
  • true - Switch starts in the "on" position
  • false - Switch starts in the "off" position
• Default: false

Styling Options​

Width​

• Description: Controls the width of the switch container
• Type: String
• Format: CSS width values (px, %, em, rem)
• Examples:
  • 200px - Fixed pixel width
  • 100% - Full container width
  • auto - Automatic sizing

Class Names​

• Description: Custom CSS classes for styling customization
• Type: String
• Format: Space-separated class names
• Examples:
  • custom-switch primary-color
  • large-switch bordered

Interaction & Events​

On Click Action​

• Description: JavaScript code executed when switch state changes
• Type: JavaScript Code
• Available Variables:
  • SF_input.value - The new switch value (true/false)
  • SF_input.SF_currentIndex - Current loop index (if inside a loop)
• Example:

if (SF_input.value) {
    // Switch was turned on
    console.log('Feature enabled');
} else {
    // Switch was turned off
    console.log('Feature disabled');
}

Validation & Rules​

Screen-Based Validation​

The switch widget supports different validation states across multiple screens/contexts:

Visible​

• Description: Controls when the switch is displayed
• Options:
  • Boolean: true (always visible) / false (always hidden)
  • Expression: Dynamic visibility using variables
• Example Expression: {{userRole}} === 'admin'

Required​

• Description: Makes the switch mandatory for form submission
• Options:
  • Boolean: true (required) / false (optional)
  • Expression: Dynamic requirement based on conditions
• Example Expression: {{agreementType}} === 'commercial'

Disabled​

• Description: Controls whether users can interact with the switch
• Options:
  • Boolean: true (disabled) / false (enabled)
  • Expression: Dynamic disable state
• Example Expression: {{isProcessing}} === true

Validation Rules​

Custom Validation​

• Required Rule: Automatically applied when marked as required
• Custom Message: Personalized error message for validation failures
• Format: {field_name} is required (default)

Advanced Features​

Form Integration​

• The switch automatically integrates with parent form validation
• Participates in form submission and validation cycles
• Supports form reset and clear operations

Loop Support​

• Can be used within repeating sections
• Access loop index via SF_currentIndex
• Each instance maintains independent state

Screen Management​

• Supports multiple screen configurations
• Different validation rules per screen
• Responsive behavior across device types

Usage Examples​

Simple Toggle​

// Basic switch for enabling notifications
{
  name: "Enable Notifications",
  model: "notificationsEnabled",
  defaultValue: true
}

Conditional Switch​

// Switch that's only visible for premium users
{
  name: "Advanced Features",
  model: "advancedMode",
  visible: "{{userPlan}} === 'premium'",
  defaultValue: false
}

Action-Triggered Switch​

// Switch with custom action
{
  name: "Dark Mode",
  model: "darkMode",
  onClick: `
    if (SF_input.value) {
      document.body.classList.add('dark-theme');
    } else {
      document.body.classList.remove('dark-theme');
    }
  `
}

Best Practices​

Naming Conventions​

• Use descriptive, action-oriented labels
• Keep labels concise but clear
• Use positive phrasing ("Enable X" rather than "Disable X")

Default Values​

• Set sensible defaults based on most common use case
• Consider user experience and safety
• Document the impact of each state

Validation​

• Use required validation sparingly for switches
• Provide clear feedback for validation errors
• Consider user flow when setting visibility conditions

Accessibility​

• Ensure labels are descriptive and clear
• Test with screen readers
• Maintain adequate contrast for switch states

Common Use Cases​

1. Feature Toggles: Enable/disable application features
2. User Preferences: Theme selection, notification settings
3. Form Options: Agreement checkboxes, optional sections
4. Status Controls: Active/inactive states, publish/draft modes
5. Conditional Display: Show/hide related form sections

Troubleshooting​

Switch Not Changing​

• Verify the model variable is properly bound
• Check for disabled state conditions
• Ensure no conflicting validation rules

Validation Not Working​

• Confirm required rules are properly set
• Check screen-specific validation settings
• Verify form integration is active

Actions Not Executing​

• Validate JavaScript syntax in onClick handler
• Check browser console for errors
• Ensure proper variable references

Integration Notes​

• Compatible with all form validation systems
• Supports real-time value binding
• Integrates with conditional display logic
• Works within complex form structures and loops