Documentation du Widget Sélecteur de Groupe

Aperçu​

Le widget Sélecteur de Groupe est un composant déroulant interrogeable qui permet aux utilisateurs de sélectionner un ou plusieurs groupes de votre système. Il fournit une fonctionnalité de recherche en temps réel avec chargement de données à distance et supporte diverses options de configuration pour la validation, le style et l'interaction utilisateur.

Configuration de Base​

Paramètres Globaux​

Nom​

• Libellé: Nom
• Description: Libellé d'affichage du champ sélecteur de groupe
• Type: Saisie de texte
• Utilisation: Ce texte s'affiche comme libellé de champ dans les formulaires

Variable/Modèle​

• Libellé: Variable/Modèle
• Description: Nom de la propriété du modèle de données où les valeurs sélectionnées seront stockées
• Type: Saisie de texte
• Requis: Oui
• Utilisation: Définit le nom de la variable pour accéder aux données de groupe sélectionnées
• Exemple: selectedGroups, userGroups

Options de Sélection​

Sélection Multiple​

• Libellé: Multi
• Description: Activer la sélection de plusieurs groupes
• Type: Commutateur à bascule
• Par défaut: false
• Utilisation: Lorsqu'activé, les utilisateurs peuvent sélectionner plusieurs groupes dans la liste déroulante

Effaçable​

• Libellé: Effaçable
• Description: Permettez aux utilisateurs d'effacer leur sélection
• Type: Commutateur à bascule
• Par défaut: false
• Utilisation: Ajoute un bouton pour effacer pour supprimer toutes les valeurs sélectionnées

Filtrable​

• Libellé: Filtrable
• Description: Activez la fonctionnalité de recherche/filtrage
• Type: Commutateur à bascule
• Par défaut: true (toujours activé pour le sélecteur de groupe)
• Utilisation: Permet aux utilisateurs de taper et rechercher des groupes par nom

Valeur par Défaut​

• Libellé: Valeur par Défaut
• Description: Définissez un groupe ou des groupes sélectionnés par défaut
• Type: Saisie de texte
• Utilisation: Spécifiez le(s) nom(s) du groupe par défaut. Pour la sélection multiple, séparez par des virgules

Configuration de la Source de Données​

Le Sélecteur de Groupe se connecte automatiquement au point de terminaison API de groupe de votre système (/api/v1/group) et fournit:

• Recherche en temps réel: Les groupes sont chargés dynamiquement au fur et à mesure que les utilisateurs tapent
• Support de la pagination: Charge 10 groupes par requête pour des performances optimales
• Mappage automatique des étiquettes: Utilise la propriété name du groupe pour l'affichage
• Mappage des valeurs: Utilise la propriété name du groupe comme valeur stockée

Stockage des Valeurs​

Le Sélecteur de Groupe stocke les données dans plusieurs formats pour la flexibilité:

1. Valeur Primaire (model): Nom(s) du groupe sous forme de chaîne ou de tableau
2. Étiquette d'Affichage (model_label): Nom(s) du groupe lisible par l'homme
3. Objet Complet (model_vb): Objet(s) de groupe complet(s) avec toutes les propriétés

Événements et Actions​

Action On Click​

• Libellé: On click
• Description: Définissez du code JavaScript personnalisé à exécuter lorsqu'un groupe est sélectionné
• Type: Saisie de code ou générateur d'action
• Variables Disponibles:
  • SF_input.value: Nom(s) du groupe sélectionné
  • SF_input.SF_data: Objet(s) de groupe complet(s)
  • SF_input.SF_currentIndex: Index de boucle actuel (si dans une boucle)

Exemple Actions​

Configuration de la Validation​

Validation Basée sur l'Écran​

Configurez les règles de validation pour différents écrans (Créer, Éditer, Afficher, etc.):

Disponible​

• Description: Contrôlez si le widget apparaît sur des écrans spécifiques
• Type: Commutateur à bascule par écran

Visible​

• Description: Contrôlez la visibilité du widget avec des conditions dynamiques
• Type: Commutateur à bascule ou expression JavaScript
• Avancé: Utilisez des expressions JavaScript pour une visibilité dynamique
• Exemple: {{user.role === 'admin'}}

Requis​

• Description: Rendre la sélection de groupe obligatoire
• Type: Commutateur à bascule ou expression JavaScript
• Validation: Affiche un message d'erreur si aucun groupe n'est sélectionné

Désactivé​

• Description: Désactivez le widget pour empêcher l'interaction utilisateur
• Type: Commutateur à bascule ou expression JavaScript

Règles de Validation Personnalisées​

Ajoutez des règles de validation personnalisées au-delà de la validation requise de base:

Types de Règles Disponibles​

• Sélection minimale: Exiger un nombre minimum de groupes (pour la sélection multiple)
• Sélection maximale: Limiter le nombre maximum de groupes
• Correspondance de motif: Valider les noms de groupes par rapport à des motifs spécifiques
• Validation personnalisée: Écrivez une logique de validation JavaScript personnalisée

Ajout de Règles​

1. Accédez à la section "Règles"
2. Cliquez sur "Ajouter une règle"
3. Sélectionnez le type de règle dans la liste déroulante
4. Entrez la valeur de validation
5. Fournissez un message d'erreur personnalisé

Style et Mise en Page​

Options d'Apparence​

Placeholder​

• Libellé: Placeholder
• Description: Texte d'indice affiché lorsqu'aucun groupe n'est sélectionné
• Type: Saisie de texte
• Exemple: "Sélectionnez un groupe...", "Choisissez des groupes..."

Largeur​

• Libellé: Largeur
• Description: Contrôlez la largeur de la liste déroulante
• Type: Saisie de texte
• Valeurs: Valeurs de largeur CSS
• Exemples: 100%, 300px, 50rem

Classes CSS​

• Libellé: Classe
• Description: Ajoutez des classes CSS personnalisées pour le style
• Type: Saisie de texte
• Utilisation: Noms de classes séparés par des espaces
• Classes Dynamiques: Utilisez le bouton des classes dynamiques pour un style conditionnel

Exemples d'Utilisation​

Sélection Basique d'un Seul Groupe​

Visibilité Dynamique Basée sur le Rôle Utilisateur​

Meilleures Pratiques​

1. Performance: Utilisez des limites appropriées pour les grandes listes de groupes
2. Expérience Utilisateur: Fournissez un texte placeholder clair et des étiquettes
3. Validation: Mettez en œuvre une validation appropriée pour les champs requis
4. Accessibilité: Assurez-vous d'un étiquetage approprié pour les lecteurs d'écran
5. Gestion des Erreurs: Fournissez des messages d'erreur significatifs pour les échecs de validation

Dépannage​

Problèmes Courants​

1. Les groupes ne se chargent pas: Vérifiez l'accessibilité du point de terminaison API et l'authentification
2. La recherche ne fonctionne pas: Vérifiez la connectivité réseau et le format de réponse de l'API
3. La sélection ne s'enregistre pas: Assurez-vous de la liaison de modèle appropriée et de la configuration du formulaire
4. Erreurs de validation: Vérifiez les paramètres de champs requis et les règles de validation personnalisées

Débogage​

Accédez à la console de développement du navigateur pour:

• Surveiller les appels API à /api/v1/group
• Vérifier les valeurs stockées dans comp_model
• Vérifier les déclencheurs d'événements et les états de validation