Select Widget

Overview​

The Select widget is a dropdown component that allows users to choose one or multiple options from a predefined list. It supports various data sources and provides extensive customization options for different use cases.

Basic Configuration​

Global Settings​

Name​

• Field: Name
• Description: Display name for the widget
• Type: Text input
• Required: Yes

Variable/Model​

• Field: Variable/Model
• Description: The variable name that will store the selected value(s)
• Type: Text input
• Required: Yes
• Note: This is the data binding variable for the widget

Default Value​

• Field: Default Value
• Description: Pre-selected value when the widget loads
• Type: Text input
• Supports: Dynamic expressions using variables

Selection Options​

Multiple Selection​

• Field: Multi
• Description: Enable selection of multiple options
• Type: Toggle switch
• Default: false
• Effect: When enabled, users can select multiple items and the result will be stored as an array

Clearable​

• Field: Clearable
• Description: Allow users to clear the selected value(s)
• Type: Toggle switch
• Default: false
• Effect: Adds a clear button to remove selections

Filterable​

• Field: Filterable
• Description: Enable search/filter functionality within the dropdown
• Type: Toggle switch
• Default: false
• Effect: Adds a search input to filter available options

Data Source Configuration​

The Select widget supports multiple data source types:

Static Data​

• Source Type: Static
• Configuration: Custom List
• Description: Use predefined static data from custom lists
• Setup:
  1. Select "Static" as remote option
  2. Choose or create a custom list
  3. Options will be loaded from the selected list

Collection Data​

• Source Type: Collection
• Configuration: Database Collection
• Description: Load options from a database collection
• Setup:
  1. Select "Collection" as remote option
  2. Choose the target collection
  3. Configure label and value field mappings
  4. Set optional query filters, sorting, and limits

Report Data​

• Source Type: Report

• Configuration: Report Query

• Description: Load options from report results

• Setup:

  1. Select "Report" as remote option
  2. Choose the target report
  3. Configure label and value field mappings
  4. Set optional query filters, sorting, and limits

External Database (SQL)​

• Source Type: SQL

• Configuration: External Database Connection

• Description: Load options from external database queries

• Setup:

  1. Select "SQL" as remote option
  2. Choose the database connection
  3. Configure the SQL query
  4. Set label and value field mappings

Field Mapping​

For dynamic data sources (Collection, Report, SQL), configure field mappings:

Label Field​

• Purpose: Defines what text is displayed to users
• Static Use: firstName
• Dynamic Use: $.firstName + ' - ' + $.lastName
• Support: Expressions using $ prefix for field references

Value Field​

• Purpose: Defines what value is stored when an option is selected
• Static Use: id
• Dynamic Use: $.id + '-' + $.type
• Support: Expressions using $ prefix for field references

Query Configuration​

Basic Query​

• Purpose: Filter and customize data retrieval
• Language: JavaScript with variable support
• Variables: Use {{variableName}} for interface variables
• Example: {status: "active", category: "{{selectedCategory}}"}

Aggregation​

• Purpose: Use aggregation pipelines for complex data processing
• Availability: Collection and Report sources
• Toggle: "Is Aggregation" switch
• Example:

Sorting​

• Sort By: Field name to sort by
• Direction:
  • 1 for ascending
  • -1 for descending
• Object Sort: Advanced sorting using sort objects

Limit​

• Purpose: Restrict number of options loaded
• Type: Number input
• Default: No limit
• Use Case: Performance optimization for large datasets

Validation Rules​

Required Validation​

• Configuration: Per screen basis
• Options:
  • Boolean toggle for simple required/not required
  • Advanced conditions using JavaScript expressions
• Message: Custom validation message

Custom Rules​

Add additional validation rules:

• Min Length: Minimum selection requirement
• Max Length: Maximum selection limit
• Pattern: Regular expression validation
• Custom: JavaScript validation functions

Screen-Based Configuration​

Configure widget behavior per screen:

Availability​

• Purpose: Control if widget exists on specific screens
• Options: Boolean or conditional expression

Visibility​

• Purpose: Control if widget is visible on specific screens
• Options: Boolean or conditional expression
• Advanced: JavaScript conditions using {{variables}}

Required Status​

• Purpose: Control if widget is required on specific screens
• Options: Boolean or conditional expression

Disabled State​

• Purpose: Control if widget is disabled on specific screens
• Options: Boolean or conditional expression

Styling and Layout​

Placeholder Text​

• Field: Placeholder
• Purpose: Help text displayed when no option is selected
• Example: "Please select an option"

Width​

• Field: Width
• Purpose: Control widget width
• Format: CSS width values (px, %, em, etc.)
• Example: "300px", "100%"

CSS Classes​

• Field: Class
• Purpose: Add custom CSS styling
• Types:
  • Static Classes: Space-separated class names
  • Dynamic Classes: Conditional classes based on data state

Event Handling​

On Click Event​

• Purpose: Execute custom actions when selection changes
• Language: JavaScript
• Available Variables:
  • SF_input.value: Selected value
  • SF_input.SF_data: Complete selected object
  • SF_input.SF_currentIndex: Loop index (if in a loop)

Action Integration​

• V2 Interface: Use visual action builder
• Legacy: Direct JavaScript function calls
• Parameters: Access to selection data and context

Working with Actions and SF_input​

Attaching Actions to onChange Event​

The select widget's onChange (or onClick) event enables you to execute custom JavaScript whenever the user changes their selection. This is essential for:

• Auto-filling related form fields with data from the selected option
• Triggering cascading dropdowns or dependent field updates
• Fetching additional information from the backoffice based on selection
• Implementing dynamic form behavior and calculations

How to Attach an Action​

1. Navigate to the Global section in the select widget configuration
2. Locate the On Click or On Change event field
3. Write plain JavaScript code directly in the action field
4. The code executes automatically when the user makes a selection

Accessing Values with SF_input​

The select widget provides comprehensive data access through the SF_input object. The key advantage is that you get both the selected value AND the complete data object from your data source.

SF_input Structure for Select Widget​

For single selection mode:

{
  value: /* The selected value based on your "Value Property" */,
  SF_data: /* Complete JSON object of the selected item */,
  SF_currentIndex: /* Loop index if widget is inside a loop */
}

For multiple selection mode (when "Multi" is enabled):

{
  value: [/* Array of selected values */],
  SF_data: [/* Array of complete selected objects */],
  SF_currentIndex: /* Loop index if widget is inside a loop */
}

Understanding SF_input Properties​

Practical Examples​

Example 1: Access Selected Value​

// Get the selected value (single select)
console.log(SF_input.value);
// Output: 'CUST001'

// For multiple select
console.log(SF_input.value);
// Output: ['CUST001', 'CUST002', 'CUST003']

// Store the selected value in another field
model.selected_customer_id = SF_input.value;

Example 2: Access Complete JSON Object (SF_data)​

This is the most powerful feature - accessing the full data object, not just the value:

// Access the complete data object for the selected item
console.log(SF_input.SF_data);
// Output: {
//   id: 'CUST001',
//   name: 'John Doe',
//   email: 'john@example.com',
//   phone: '+1234567890',
//   address: {
//     street: '123 Main St',
//     city: 'New York',
//     country: 'USA'
//   },
//   credit_limit: 5000,
//   status: 'active'
// }

// Access any property from the selected object
model.customer_email = SF_input.SF_data.email;
model.customer_phone = SF_input.SF_data.phone;
model.customer_status = SF_input.SF_data.status;

// Access nested properties
model.customer_city = SF_input.SF_data.address?.city;
model.customer_country = SF_input.SF_data.address?.country;

Best Practices​

1. Always Check SF_data Exists: Before accessing SF_data properties, verify it's not null

   if (SF_input.SF_data) {
     // Your code here
   }
   

2. Use Optional Chaining: For nested properties, use optional chaining to avoid errors

   const city = SF_input.SF_data?.address?.city || 'Unknown';
   

3. Handle Both Single and Multi Select: If your widget might switch between modes, handle both cases

   const selectedData = Array.isArray(SF_input.SF_data) ? SF_input.SF_data : [SF_input.SF_data];
   

4. Leverage SF_data for Rich Data: Always use SF_data when you need more than just the value - it contains the complete record

5. Clear Previous Data: When selection changes, clear dependent fields to avoid stale data

   model.related_field_1 = null;
   model.related_field_2 = null;
   // Then populate with new data
   

6. Error Handling: Wrap data fetching in try-catch blocks

   try {
     const data = await SF_executeAction('fetchData', { id: SF_input.value });
     // Process data
   } catch (error) {
     console.error('Error fetching data:', error);
     model.error_message = 'Failed to load data';
   }
   

7. Performance: For expensive operations, consider debouncing or showing loading indicators

Best Practices​

1. Performance: Use limits for large datasets
2. User Experience: Enable filtering for lists with 10+ items
3. Validation: Provide clear error messages
4. Accessibility: Use descriptive labels and placeholders
5. Data Integrity: Validate selected values against available options
6. Responsive Design: Set appropriate widths for different screen sizes

Troubleshooting​

Common Issues​

1. No Options Displayed

   • Check data source configuration
   • Verify query syntax and variables
   • Ensure proper field mappings

2. Performance Issues

   • Add appropriate limits
   • Use filtering instead of loading all data
   • Consider pagination for very large datasets

3. Validation Errors

   • Check required field configuration
   • Verify custom validation rules
   • Ensure proper screen-based settings

4. Selection Not Saving

   • Verify variable/model configuration
   • Check data type compatibility
   • Ensure proper form submission handling