Widget UserPicker

The UserPicker widget provides a searchable dropdown interface for selecting one or multiple users from your application's user base. It supports remote search, group filtering, and flexible display options.

Overview​

The UserPicker widget renders as an Element UI select component with remote search capabilities. Users can search and select from the application's user directory with real-time filtering and group-based restrictions.

Configuration Properties​

Basic Properties​

Name​

• Description: Display label for the widget
• Type: String
• Default: "Select a user"
• Usage: Appears as the form label above the selection field

Variable/Model​

• Description: The data model variable name that will store the selected user(s)
• Type: String
• Required: Yes
• Format: Must be a valid variable name (e.g., selectedUser, assignedUsers)

Selection Options​

Multiple Selection​

• Property: multiple
• Type: Boolean
• Default: false
• Description: Enable selection of multiple users
• When enabled: Returns an array of selected user emails
• When disabled: Returns a single user email string

Clearable​

• Property: clearable
• Type: Boolean
• Default: false
• Description: Adds a clear button to remove all selections

User Filtering​

Groups Filter​

• Property: groupes
• Type: Array of Group Objects
• Description: Restrict user selection to specific groups
• Configuration: Select one or more groups from the dropdown
• API Behavior: Only users belonging to the selected groups will appear in search results

Label Display​

• Property: label
• Type: String
• Options:
  • "name": Display user's first name + last name
  • "Email": Display user's email address
• Default: "Email"
• Description: Determines how users are displayed in the dropdown options

Validation and Behavior​

Required Field​

• Property: required
• Type: Boolean
• Default: false
• Description: Makes user selection mandatory for form submission
• Validation: Shows error message if no user is selected when required

Disabled State​

• Property: disabled
• Type: Boolean
• Default: false
• Description: Disables the widget preventing user interaction

Visibility​

• Property: visible
• Type: Boolean
• Default: true
• Description: Controls widget visibility on the interface

Style and Appearance​

Placeholder Text​

• Property: placeholder
• Type: String
• Default: "Search for a user..."
• Description: Placeholder text displayed when no selection is made

Width​

• Property: width
• Type: String
• Default: "100%"
• Examples: "300px", "50%", "auto"
• Description: Controls the width of the selection field

CSS Classes​

• Property: classNames
• Type: String
• Description: Custom CSS classes for styling
• Format: Space-separated class names

Dynamic Classes​

• Property: classes
• Type: JavaScript Object
• Description: Conditional CSS classes based on form state
• Usage: Advanced styling based on data conditions

Advanced Configuration​

Screen-Based Validation​

Configure different behaviors across multiple screens/views:

Available​

• Description: Control widget availability per screen
• Type: Boolean per screen
• Usage: Hide/show widget on specific application screens

Visible​

• Description: Advanced visibility conditions
• Type: Boolean or JavaScript expression
• Examples:
  • true - Always visible
  • {{userRole}} === 'admin' - Visible only for admin users

Required​

• Description: Screen-specific requirement rules
• Type: Boolean or JavaScript expression
• Examples:
  • true - Always required
  • {{formType}} === 'assignment' - Required only for assignment forms

Disabled​

• Description: Conditional disable states
• Type: Boolean or JavaScript expression
• Examples:
  • {{currentUser.role}} !== 'manager' - Disabled for non-managers

Validation Rules​

Add custom validation rules beyond basic required validation:

Rule Types​

• Pattern: Regular expression validation
• Custom: JavaScript function validation
• Length: Minimum/maximum selection count (for multiple selection)

Rule Configuration​

{
  "rule": "pattern",
  "value": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
  "message": "Please select a valid user"
}

Usage Examples​

Basic Single User Selection​

{
  "type": "userPicker",
  "name": "Assigned User",
  "model": "assignedUser",
  "placeholder": "Select an assigned user...",
  "required": true,
  "label": "name"
}

Multiple User Selection with Group Filter​

{
  "type": "userPicker",
  "name": "Team Members",
  "model": "teamMembers",
  "multiple": true,
  "placeholder": "Select team members...",
  "groupes": [
    {"_id": "dev_team", "name": "Development Team"},
    {"_id": "qa_team", "name": "QA Team"}
  ],
  "label": "name",
  "clearable": true
}

Advanced Configuration with Validation​

{
  "type": "userPicker",
  "name": "Project Manager",
  "model": "projectManager",
  "placeholder": "Choose project manager...",
  "required": true,
  "groupes": [
    {"_id": "managers", "name": "Managers"}
  ],
  "label": "name",
  "width": "400px",
  "validation": {
    "screen1": {
      "visible": true,
      "required": true,
      "disabled": false
    },
    "screen2": {
      "visible": "{{project.status}} === 'active'",
      "required": "{{project.type}} === 'enterprise'",
      "disabled": false
    }
  }
}

Events and Interactions​

onChange Event​

• Trigger: When user selection changes
• Data Available:
  • SF_input.value: Selected user email(s)
  • SF_input.SF_data: Complete user object(s)
  • SF_input.SF_currentIndex: Current loop index (if in a loop)

Event Handling Example​

// On selection change
function handleUserSelection(eventData) {
  const selectedEmail = eventData.value;
  const selectedUserData = eventData.SF_data;
  
  console.log('Selected user:', selectedUserData);
  // Additional logic here
}

Data Structure​

Input Data (Selected Values)​

// Single selection
"user@example.com"

// Multiple selection
["user1@example.com", "user2@example.com", "user3@example.com"]

Complete User Objects (Available in SF_data)​

{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "_id": "user_id_123",
  // Additional user properties
}

API Integration​

User Search Endpoint​

• URL: /api/v1/user
• Method: GET
• Parameters:
  • limit: Maximum results (default: 10)
  • groups: Comma-separated group IDs for filtering
  • key: Search query string
  • SF_mode: Application mode parameter

Group Filtering​

When groups are configured, the API request automatically includes group filters to restrict results to users belonging to the specified groups.

Best Practices​

Performance Optimization​

• Use group filtering to reduce search result size
• Set appropriate search limits for large user bases
• Consider caching frequently accessed user data

User Experience​

• Provide clear placeholder text indicating the selection purpose
• Use descriptive labels that match your use case
• Enable clearable option for better user control
• Choose appropriate label format (name vs email) based on context

Validation Strategy​

• Use required validation for critical selections
• Implement conditional validation based on form context
• Provide meaningful error messages for validation failures

Accessibility​

• Ensure proper labeling for screen readers
• Maintain keyboard navigation support
• Use semantic HTML through Element UI components

Troubleshooting​

Common Issues​

No Users Appearing​

• Check group filter configuration
• Verify user API endpoint availability
• Ensure users exist in the specified groups

Selection Not Saving​

• Verify model/variable name is correctly configured
• Check for form validation errors
• Ensure proper data binding in parent form

Performance Issues​

• Reduce group scope if too many users
• Implement pagination for large datasets
• Optimize search query parameters