Select Widget

Overview#Direct link to 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#Direct link to Basic Configuration

Global Settings#Direct link to Global Settings

Name#Direct link to Name

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

Variable/Model#Direct link to 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#Direct link to Default Value

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

Selection Options#Direct link to Selection Options

Multiple Selection#Direct link to 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#Direct link to 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#Direct link to 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#Direct link to Data Source Configuration

The Select widget supports multiple data source types:

Static Data#Direct link to 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#Direct link to 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#Direct link to 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)#Direct link to 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#Direct link to Field Mapping

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

Label Field#Direct link to 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#Direct link to 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#Direct link to Query Configuration

Basic Query#Direct link to 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#Direct link to Aggregation

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

Sorting#Direct link to Sorting

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

Limit#Direct link to Limit

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

Validation Rules#Direct link to Validation Rules

Required Validation#Direct link to 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#Direct link to 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#Direct link to Screen-Based Configuration

Configure widget behavior per screen:

Availability#Direct link to Availability

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

Visibility#Direct link to Visibility

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

Required Status#Direct link to Required Status

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

Disabled State#Direct link to Disabled State

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

Styling and Layout#Direct link to Styling and Layout

Placeholder Text#Direct link to Placeholder Text

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

Width#Direct link to Width

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

CSS Classes#Direct link to 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#Direct link to Event Handling

On Click Event#Direct link to 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#Direct link to 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#Direct link to Working with Actions and SF_input

Attaching Actions to onChange Event#Direct link to 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#Direct link to 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#Direct link to 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#Direct link to 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#Direct link to Understanding SF_input Properties

Practical Examples#Direct link to Practical Examples

Example 1: Access Selected Value#Direct link to 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)#Direct link to 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#Direct link to 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#Direct link to 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#Direct link to Troubleshooting

Common Issues#Direct link to 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