Radio Widget Documentation

Overview​

The Radio widget allows users to select a single option from a predefined list of choices. It renders as a group of radio buttons where only one option can be selected at a time.

Basic Configuration​

Global Settings​

Name​

• Field: Name
• Description: The display label for the radio group
• Required: Yes
• Example: "Select Priority Level"

Variable/Model​

• Field: Variable/Model
• Description: The data model property that stores the selected value
• Required: Yes
• Format: Must be a valid variable name
• Example: priority_level

Default Value​

• Field: Default Value
• Description: The initial selected value when the form loads
• Required: No
• Type: String
• Example: "medium"

Data Source Configuration​

The radio widget supports multiple data sources for populating the available options:

Static Data​

• Source: Custom Lists
• Description: Use predefined static lists
• Configuration:
  • Select an existing custom list
  • Create a new custom list if none exists
• Data Format: Each item requires label and value properties

Collection Data​

• Source: Database Collections
• Description: Dynamically load options from a collection
• Configuration:
  • Select target collection
  • Configure label and value mappings
  • Set up optional query filters
  • Define sort order and limits

Report Data​

• Source: Reports
• Description: Use report results as data source
• Configuration:
  • Select target report
  • Map result columns to label/value
  • Configure aggregation if needed

SQL/External Database​

• Source: External Database Connection
• Description: Query external databases for options
• Configuration:
  • Select database connection
  • Write SQL query
  • Map result columns

Props Configuration​

For dynamic data sources (Collection, Report, SQL):

Label Property​

• Field: Label
• Description: Field name or expression for display text
• Static Usage: firstName
• Dynamic Usage: $.firstName + ' - ' + $.lastName

Value Property​

• Field: Value
• Description: Field name or expression for stored value
• Static Usage: id
• Dynamic Usage: $.id + '-' + $.category

Query Configuration​

For collection and report data sources:

Basic Query​

• Purpose: Filter and customize data retrieval
• Language: JavaScript with model references
• Variables: Use {{variable_name}} for dynamic values
• Example:

{
  status: "active",
  category: {{selected_category}}
}

Aggregation​

• Purpose: Perform complex data aggregation
• Toggle: Enable "Is Aggregation" switch
• Example:

[
  { $match: { active: true } },
  { $group: { _id: "$category", count: { $sum: 1 } } }
]

Sort Configuration​

• Sort By: Field name for sorting
• Direction:
  • 1 for ascending
  • -1 for descending

Limit​

• Purpose: Restrict number of options
• Type: Number
• Default: No limit

Validation​

Screen-based Validation​

Configure different behaviors across multiple screens:

Available​

• Purpose: Control if widget appears on specific screens
• Type: Boolean per screen
• Default: true

Visible​

• Purpose: Control widget visibility
• Options:
  • Simple: Boolean toggle
  • Advanced: JavaScript condition
• Advanced Example: {{user_role}} === 'admin'

Required​

• Purpose: Make selection mandatory
• Options:
  • Simple: Boolean toggle
  • Advanced: JavaScript condition
• Advanced Example: {{form_type}} === 'official'

Disabled​

• Purpose: Prevent user interaction
• Options:
  • Simple: Boolean toggle
  • Advanced: JavaScript condition

Validation Rules​

Add custom validation rules:

Rule Types​

• Pattern: Regular expression validation
• Custom: JavaScript validation function
• Range: Value range validation
• Required: Built-in required validation

Rule Configuration​

• Rule: Select validation type
• Value: Rule parameter or pattern
• Message: Error message to display

Styling and Layout​

Layout Options​

Display Mode​

• Block: Vertical stack (default)
• Inline: Horizontal arrangement

Border​

• Purpose: Add borders around radio buttons
• Type: Boolean
• Default: false

Width Configuration​

• Field: Width
• Description: CSS width value
• Examples:
  • 100% (full width)
  • 300px (fixed width)
  • 50vw (viewport-based)

CSS Classes​

Static Classes​

• Field: Class
• Description: Space-separated CSS class names
• Example: "custom-radio highlight-group"

Dynamic Classes​

• Purpose: Conditional styling based on data
• Language: JavaScript expressions
• Access: Click "Dynamic classes" button
• Example:

{
  'error-state': {{has_errors}},
  'required-field': {{is_required}}
}

Placeholder​

• Field: Placeholder
• Description: Hint text (if supported by theme)
• Example: "Please select an option"

Events and Interactions​

On Click Event​

• Trigger: When radio option is selected
• Access Variables:
  • SF_input.value: Selected value
  • SF_input.SF_data: Full selected object
  • SF_input.SF_currentIndex: Loop index (if in repeating context)

Simple Event​

• Field: On click
• Type: Function name
• Example: handlePriorityChange

Advanced Event​

• Type: JavaScript code
• Example:

if (SF_input.value === 'urgent') {
  // Show additional fields
  this.comp_model.show_deadline = true;
}

Advanced Features​

Conditional Display​

• Purpose: Show/hide based on other form values
• Configuration: Use advanced visibility conditions
• Example: {{user_type}} === 'premium'

Dynamic Data Refresh​

• Trigger: When query variables change
• Automatic: Yes, when dependencies update
• Manual: Call refresh method in events

Loop Integration​

• Purpose: Use in repeating form sections
• Access: SF_currentIndex for current iteration
• Model: Automatic array handling

Best Practices​

Data Source Selection​

1. Static Lists: For fixed, rarely changing options
2. Collections: For user-managed data
3. Reports: For computed/aggregated options
4. SQL: For complex external data

Performance Optimization​

1. Use limits for large datasets
2. Implement proper indexing for sort fields
3. Cache static data when possible
4. Use aggregation for summary options

User Experience​

1. Provide clear, descriptive labels
2. Use logical ordering (alphabetical, priority-based)
3. Set appropriate default values
4. Include validation with helpful error messages

Validation Strategy​

1. Use required validation for critical fields
2. Implement conditional validation when needed
3. Provide immediate feedback on selection
4. Consider cross-field validation rules

Examples​

Basic Static Radio Group​

Name: "Priority Level"
Model: priority_level
Data Source: Static
Options: 
  - Low (value: "low")
  - Medium (value: "medium") 
  - High (value: "high")
Default Value: "medium"

Dynamic Collection-based Radio Group​

Name: "Department"
Model: selected_department
Data Source: Collection (departments)
Label Property: $.name
Value Property: $.id
Query: { active: true }
Sort: name (ascending)

Conditional Radio Group​

Name: "Subscription Type"
Model: subscription_type
Visibility Condition: {{user_eligible}} === true
Required Condition: {{payment_method}} !== 'free'
On Click: updatePricingDisplay

Troubleshooting​

Common Issues​

Options Not Loading​

• Check data source configuration
• Verify query syntax
• Ensure proper field mappings
• Check network connectivity for external sources

Selection Not Saving​

• Verify model variable name
• Check validation rules
• Ensure proper form submission
• Validate data types

Styling Issues​

• Check CSS class names
• Verify width/height values
• Review responsive design settings
• Test dynamic class conditions

Event Not Triggering​

• Verify function names
• Check JavaScript syntax
• Ensure proper variable access
• Review browser console for errors