Group Picker Widget

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​

Global Settings​

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​

• 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​

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​

• 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​

• 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​

• 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​

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

API Response Format​

The widget expects groups to have the following structure:

{
  "_id": "group_id",
  "name": "Group Name",
  "email": "group@example.com"
}

Events and Actions​

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​

// Log selected group information
console.log('Selected group:', SF_input.SF_data);

// Navigate to group details page
window.location.href = `/groups/${SF_input.SF_data._id}`;

// Update other form fields based on selection
this.comp_model.department = SF_input.SF_data.department;

Validation Configuration​

Screen-based Validation​

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

Available​

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

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​

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

Disabled​

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

Custom Validation Rules​

Add custom validation rules beyond basic required validation:

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​

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​

Appearance Options​

Placeholder​

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

Width​

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

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

Layout Options​

Inline vs Block​

• Label: Layout
• Description: Control whether the widget displays inline or as a block element
• Type: Radio buttons (Block/Inline)

Data Management​

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

Single Selection Example​

// Stored values
comp_model.selectedGroup = "Administrators"
comp_model.selectedGroup_label = "Administrators"
comp_model.selectedGroup_vb = [{
  _id: "admin_group_id",
  name: "Administrators",
  email: "admin@company.com"
}]

Multiple Selection Example​

// Stored values
comp_model.userGroups = ["Administrators", "Managers"]
comp_model.userGroups_label = ["Administrators", "Managers"]
comp_model.userGroups_vb = [
  { _id: "admin_id", name: "Administrators", email: "admin@company.com" },
  { _id: "manager_id", name: "Managers", email: "managers@company.com" }
]

Advanced Features​

Remote Data Loading​

• Automatic loading: Groups load automatically when dropdown opens
• Search debouncing: Optimized search with 300ms delay
• Cache management: Previously loaded groups are cached for better performance

Error Handling​

• Network errors: Graceful handling of API failures
• Loading states: Visual feedback during data loading
• Fallback behavior: Maintains previously loaded groups if new search fails

Integration with Forms​

• Form validation: Integrates with parent form validation
• Reset functionality: Supports form reset operations
• Dirty state tracking: Tracks changes for form submission

Usage Examples​

Basic Single Group Selection​

// Configuration
{
  name: "Project Group",
  model: "projectGroup",
  multiple: false,
  clearable: true,
  placeholder: "Select project group"
}

Multiple Group Selection with Validation​

// Configuration
{
  name: "User Groups",
  model: "userGroups",
  multiple: true,
  clearable: true,
  required: true,
  placeholder: "Select user groups",
  validation: {
    rules: [
      {
        type: "minSelection",
        value: 1,
        message: "At least one group must be selected"
      }
    ]
  }
}

Dynamic Visibility Based on User Role​

// Advanced visibility condition
{
  visible: "{{user.role === 'admin' || user.permissions.includes('manage_groups')}}"
}

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​

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​

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