Group Picker Widget

Overview#Direct link to Overview

The Group Picker widget is a searchable dropdown component that allows users to select one or multiple groups from your system. It provides real-time search functionality with remote data loading and supports various configuration options for validation, styling, and user interaction.

Basic Configuration#Direct link to Basic Configuration

Global Settings#Direct link to Global Settings

Name#Direct link to Name

• Label: Name
• Description: The display label for the group picker field
• Type: Text input
• Usage: This text appears as the field label in forms

Variable/Model#Direct link to Variable/Model

• Label: Variable/Model
• Description: The data model property name where selected values will be stored
• Type: Text input
• Required: Yes
• Usage: Defines the variable name for accessing selected group data
• Example: selectedGroups, userGroups

Selection Options#Direct link to Selection Options

Multiple Selection#Direct link to Multiple Selection

• Label: Multi
• Description: Enable selection of multiple groups
• Type: Toggle switch
• Default: false
• Usage: When enabled, users can select multiple groups from the dropdown

Clearable#Direct link to Clearable

• Label: Clearable
• Description: Allow users to clear their selection
• Type: Toggle switch
• Default: false
• Usage: Adds a clear button to remove all selected values

Filterable#Direct link to Filterable

• Label: Filterable
• Description: Enable search/filter functionality
• Type: Toggle switch
• Default: true (always enabled for Group Picker)
• Usage: Allows users to type and search for groups by name

Default Value#Direct link to Default Value

• Label: Default Value
• Description: Set a default selected group or groups
• Type: Text input
• Usage: Specify default group name(s). For multiple selection, separate with commas

Data Source Configuration#Direct link to Data Source Configuration

The Group Picker automatically connects to your system's group API endpoint (/api/v1/group) and provides:

• Real-time search: Groups are loaded dynamically as users type
• Pagination support: Loads 10 groups per request for optimal performance
• Automatic label mapping: Uses group name property for display
• Value mapping: Uses group name property as the stored value

Value Storage#Direct link to Value Storage

The Group Picker stores data in multiple formats for flexibility:

1. Primary Value (model): Group name(s) as string or array
2. Display Label (model_label): Human-readable group name(s)
3. Full Object (model_vb): Complete group object(s) with all properties

Events and Actions#Direct link to Events and Actions

On Click Action#Direct link to On Click Action

• Label: On click
• Description: Define custom JavaScript code to execute when a group is selected
• Type: Code input or Action builder
• Available Variables:
  • SF_input.value: Selected group name(s)
  • SF_input.SF_data: Complete group object(s)
  • SF_input.SF_currentIndex: Current loop index (if within a loop)

Example Actions#Direct link to Example Actions

Validation Configuration#Direct link to Validation Configuration

Screen-based Validation#Direct link to Screen-based Validation

Configure validation rules for different screens (Create, Edit, View, etc.):

Available#Direct link to Available

• Description: Control whether the widget appears on specific screens
• Type: Toggle switch per screen

Visible#Direct link to Visible

• Description: Control widget visibility with dynamic conditions
• Type: Toggle switch or JavaScript expression
• Advanced: Use JavaScript expressions for dynamic visibility
• Example: {{user.role === 'admin'}}

Required#Direct link to Required

• Description: Make group selection mandatory
• Type: Toggle switch or JavaScript expression
• Validation: Displays error message if no group is selected

Disabled#Direct link to Disabled

• Description: Disable the widget to prevent user interaction
• Type: Toggle switch or JavaScript expression

Custom Validation Rules#Direct link to Custom Validation Rules

Add custom validation rules beyond basic required validation:

Rule Types Available#Direct link to Rule Types Available

• Minimum selection: Require minimum number of groups (for multiple selection)
• Maximum selection: Limit maximum number of groups
• Pattern matching: Validate group names against specific patterns
• Custom validation: Write custom JavaScript validation logic

Adding Rules#Direct link to Adding Rules

1. Navigate to the "Rules" section
2. Click "Add rule"
3. Select rule type from dropdown
4. Enter validation value
5. Provide custom error message

Styling and Layout#Direct link to Styling and Layout

Appearance Options#Direct link to Appearance Options

Placeholder#Direct link to Placeholder

• Label: Placeholder
• Description: Hint text displayed when no group is selected
• Type: Text input
• Example: "Select a group...", "Choose groups..."

Width#Direct link to Width

• Label: Width
• Description: Control the width of the dropdown
• Type: Text input
• Values: CSS width values
• Examples: 100%, 300px, 50rem

CSS Classes#Direct link to CSS Classes

• Label: Class
• Description: Add custom CSS classes for styling
• Type: Text input
• Usage: Space-separated class names
• Dynamic Classes: Use the dynamic classes button for conditional styling

Usage Examples#Direct link to Usage Examples

Basic Single Group Selection#Direct link to Basic Single Group Selection

Dynamic Visibility Based on User Role#Direct link to Dynamic Visibility Based on User Role

Best Practices#Direct link to Best Practices

1. Performance: Use appropriate limits for large group lists
2. User Experience: Provide clear placeholder text and labels
3. Validation: Implement proper validation for required fields
4. Accessibility: Ensure proper labeling for screen readers
5. Error Handling: Provide meaningful error messages for validation failures

Troubleshooting#Direct link to Troubleshooting

Common Issues#Direct link to Common Issues

1. Groups not loading: Check API endpoint accessibility and authentication
2. Search not working: Verify network connectivity and API response format
3. Selection not saving: Ensure proper model binding and form configuration
4. Validation errors: Check required field settings and custom validation rules

Debugging#Direct link to Debugging

Access the browser's developer console to:

• Monitor API calls to /api/v1/group
• Check stored values in comp_model
• Verify event triggers and validation states