Documentation du Widget Autocomplétion

Aperçu​

Le widget Autocomplétion fournit une saisie déroulante dynamique avec fonctionnalité de recherche en temps réel. Il permet aux utilisateurs de rechercher et sélectionner des valeurs à partir d'une source de données distante telle que des collections, des rapports ou des bases de données externes. Le widget supporte les modes de sélection unique et multiple avec filtrage et validation personnalisables.

Configuration de Base​

Propriétés du Widget​

Nom et Modèle​

• Nom: Libellé d'affichage pour le widget
• Variable/Modèle: Le nom de la variable qui stockera la(les) valeur(s) sélectionnée(s)

Support des Types de Données​

Le widget autocomplétion peut gérer divers types de données et formate automatiquement les valeurs sélectionnées en fonction des propriétés d'étiquette et de valeur configurées.

Configuration de la Source de Données​

Sources de Données​

Connectez-vous à une collection de base de données:

• Collection: Sélectionnez parmi les collections disponibles
• Requête: Définissez les critères de filtrage à l'aide de requêtes de style MongoDB
• Trier par: Configurez le tri par nom de champ et direction (-1 pour décroissant, 1 pour croissant)
• Limite: Définissez le nombre maximum de résultats à afficher

Mappage des Données​

Propriétés d'Étiquette et de Valeur​

Configurez la façon dont les données sont affichées et stockées:

• Propriété d'Étiquette: Champ utilisé pour le texte d'affichage (par exemple, name, title)
• Propriété de Valeur: Champ utilisé pour la valeur stockée (par exemple, _id, code)

Configuration des Requêtes​

Requêtes de Base​

Utilisez l'éditeur de requête pour définir les critères de filtrage:

Pour les Collections (style MongoDB):

Requêtes Avancées avec Variables​

Référencez les variables du formulaire dans les requêtes:

Options de Sélection​

Sélection Unique vs Multiple​

• Multiple: Activez pour permettre la sélection de plusieurs valeurs
• Effaçable: Permettez aux utilisateurs d'effacer la sélection
• Filtrable: Activez le filtrage de recherche en temps réel (activé par défaut pour l'autocomplétion)

Valeurs par Défaut​

Définissez les valeurs initiales pour le widget:

• Sélection Unique: Fournissez une seule valeur par défaut
• Sélection Multiple: Fournissez un tableau de valeurs par défaut

Configuration de la Validation​

Validation Basée sur l'Écran​

Configurez le comportement du widget sur différents écrans:

États Disponibles​

• Disponible: Le widget est rendu sur l'écran
• Visible: Le widget est visible pour les utilisateurs
• Requis: Le champ doit être rempli avant la soumission du formulaire
• Désactivé: Le widget est en lecture seule

Modes de Validation​

• Mode Simple: Utilisez des valeurs booléennes pour chaque état
• Mode Avancé: Utilisez des expressions JavaScript pour une validation dynamique

Exemple de validation avancée:

Règles de Validation​

Ajoutez des règles de validation personnalisées avec la configuration des Règles:

Types de Règles Disponibles​

• Requis: Le champ doit avoir une valeur
• Longueur Minimale: Nombre minimum de caractères
• Longueur Maximale: Nombre maximum de caractères
• Motif: Validation par expression régulière
• Personnalisé: Fonction de validation JavaScript

Configuration des Règles​

Gestion des Événements​

Événements On Click​

Configurez les actions lorsque les utilisateurs interagissent avec le widget:

Données d'Événement​

L'événement onClick fournit l'accès à:

• SF_input: Objet contenant:
  • value: Valeur(s) sélectionnée(s)
  • SF_data: Objet(s) sélectionné(s) complet(s)
  • SF_currentIndex: Index de boucle (si à l'intérieur d'une boucle)

Configuration des Actions​

Utilisez l'éditeur d'action pour définir les fonctions JavaScript:

Style et Mise en Page​

Style de Base​

• Placeholder: Texte affiché lorsqu'aucune sélection n'est effectuée
• Largeur: Largeur du widget (unités CSS: px, %, em, etc.)
• Noms de Classe: Classes CSS pour un style personnalisé

Classes Dynamiques​

Utilisez la fonctionnalité de classes dynamiques pour un style conditionnel:

{
  "error": "{{hasValidationError}}",
  "highlighted": "{{isImportant}}",
  "disabled": "{{!isEditable}}"
}

Fonctionnalités Avancées​

Configuration de la Recherche Distante​

Le widget autocomplétion configure automatiquement la recherche distante avec:

• Recherche Débobinée: Performance de recherche optimisée
• Longueur Minimale de Requête: Évite les appels API excessifs
• Mise en Cache des Résultats: Améliore l'expérience utilisateur

Actualisation des Données​

Le widget actualise automatiquement les données lorsque:

• La requête de recherche change
• Les variables du formulaire parent changent
• Le widget obtient le focus

Optimisation des Performances​

• Chargement Paresseux: Les données sont chargées uniquement si nécessaire
• Limitation des Résultats: Limite par défaut de 10 résultats pour des performances optimales
• Optimisation des Requêtes: Requêtes efficaces de base de données avec support d'indexation

Exemples d'Intégration​

Sélection Basique de Produit​

Dépannage​

Problèmes Courants​

Aucun Résultat Affiché​

• Vérifiez la connexion collection/base de données
• Vérifiez la syntaxe de la requête
• Assurez-vous du mappage correct des champs
• Vérifiez les permissions utilisateur

Performances Lentes​

• Ajoutez des index de base de données pour les champs recherchés
• Réduisez la limite de résultats
• Optimisez les filtres de requête
• Vérifiez la connectivité réseau

Erreurs de Validation​

• Vérifiez la configuration des champs requis
• Vérifiez la syntaxe des règles de validation
• Assurez-vous de la gestion appropriée des événements
• Testez avec différents types de données

Meilleures Pratiques​

1. Optimisation des Requêtes: Utilisez des filtres spécifiques pour réduire les ensembles de résultats
2. Mappage des Champs: Choisissez des étiquettes descriptives et des valeurs uniques
3. Gestion des Erreurs: Fournissez des messages de validation clairs
4. Expérience Utilisateur: Définissez des placeholders et des valeurs par défaut appropriés
5. Performance: Utilisez la pagination pour les grands ensembles de données

Référence d'API​

Propriétés du Widget​

• id: Identifiant unique du widget
• model: Liaison du modèle de données
• options: Objet de configuration contenant tous les paramètres du widget
• validation: Règles de validation basées sur l'écran
• events: Configurations des gestionnaires d'événements

Méthodes​

• refresh(keyword): Actualiser manuellement les données avec un terme de recherche optionnel
• setLabels(value): Mettre à jour les étiquettes d'affichage en fonction des valeurs sélectionnées
• clearValue(): Effacer la sélection actuelle
• setValue(value): Définir programmatiquement la valeur du widget

Événements​

• @change: Déclenché lorsque la sélection change
• @focus: Déclenché lorsque le widget obtient le focus
• @blur: Déclenché lorsque le widget perd le focus