Documentation du Widget Select

Aperçu​

Le widget Select est un composant de liste déroulante qui permet aux utilisateurs de choisir une ou plusieurs options parmi une liste prédéfinie. Il prend en charge diverses sources de données et offre de nombreuses options de personnalisation pour différents cas d'usage.

Configuration de Base​

Paramètres Globaux​

Nom​

• Champ: Name
• Description: Nom d'affichage du widget
• Type: Saisie de texte
• Requis: Oui

Variable/Modèle​

• Champ: Variable/Model
• Description: Le nom de la variable qui stockera la ou les valeurs sélectionnées
• Type: Saisie de texte
• Requis: Oui
• Note: Il s'agit de la variable de liaison de données pour le widget

Valeur par Défaut​

• Champ: Default Value
• Description: Valeur présélectionnée lors du chargement du widget
• Type: Saisie de texte
• Prend en charge: Expressions dynamiques utilisant des variables

Options de Sélection​

Sélection Multiple​

• Champ: Multi
• Description: Activer la sélection de plusieurs options
• Type: Interrupteur à bascule
• Défaut: false
• Effet: Lorsqu'il est activé, les utilisateurs peuvent sélectionner plusieurs éléments et le résultat sera stocké sous forme de tableau

Effaçable​

• Champ: Clearable
• Description: Permettre aux utilisateurs d'effacer la ou les valeurs sélectionnées
• Type: Interrupteur à bascule
• Défaut: false
• Effet: Ajoute un bouton d'effacement pour supprimer les sélections

Filtrable​

• Champ: Filterable
• Description: Activer la fonctionnalité de recherche/filtrage dans la liste déroulante
• Type: Interrupteur à bascule
• Défaut: false
• Effet: Ajoute une saisie de recherche pour filtrer les options disponibles

Configuration de la Source de Données​

Le widget Select prend en charge plusieurs types de sources de données :

Données Statiques​

• Type de Source: Static
• Configuration: Custom List
• Description: Utiliser des données statiques prédéfinies à partir de listes personnalisées
• Configuration:
  1. Sélectionner "Static" comme option distante
  2. Choisir ou créer une liste personnalisée
  3. Les options seront chargées à partir de la liste sélectionnée

Données de Collection​

• Type de Source: Collection
• Configuration: Database Collection
• Description: Charger les options à partir d'une collection de base de données
• Configuration:
  1. Sélectionner "Collection" comme option distante
  2. Choisir la collection cible
  3. Configurer les mappings des champs de libellé et de valeur
  4. Définir des filtres de requête optionnels, le tri et les limites

Données de Rapport​

• Type de Source: Report

• Configuration: Report Query

• Description: Charger les options à partir des résultats de rapport

• Configuration:

  1. Sélectionner "Report" comme option distante
  2. Choisir le rapport cible
  3. Configurer les mappings des champs de libellé et de valeur
  4. Définir des filtres de requête optionnels, le tri et les limites

Base de Données Externe (SQL)​

• Type de Source: SQL

• Configuration: External Database Connection

• Description: Charger les options à partir de requêtes de bases de données externes

• Configuration:

  1. Sélectionner "SQL" comme option distante
  2. Choisir la connexion à la base de données
  3. Configurer la requête SQL
  4. Définir les mappings des champs de libellé et de valeur

Mapping des Champs​

Pour les sources de données dynamiques (Collection, Rapport, SQL), configurez les mappings de champs :

Champ de Libellé​

• Objectif: Définit le texte affiché aux utilisateurs
• Utilisation Statique: firstName
• Utilisation Dynamique: $.firstName + ' - ' + $.lastName
• Prend en charge: Expressions utilisant le préfixe $ pour les références de champs

Champ de Valeur​

• Objectif: Définit la valeur stockée lorsqu'une option est sélectionnée
• Utilisation Statique: id
• Utilisation Dynamique: $.id + '-' + $.type
• Prend en charge: Expressions utilisant le préfixe $ pour les références de champs

Configuration des Requêtes​

Requête de Base​

• Objectif: Filtrer et personnaliser la récupération des données
• Langage: JavaScript avec support des variables
• Variables: Utilisez {{variableName}} pour les variables d'interface
• Exemple: {status: "active", category: "{{selectedCategory}}"}

Agrégation​

• Objectif: Utiliser des pipelines d'agrégation pour un traitement de données complexe
• Disponibilité: Sources Collection et Rapport
• Bascule: Interrupteur "Is Aggregation"
• Exemple:

Tri​

• Trier Par: Nom du champ par lequel trier
• Direction:
  • 1 pour ascendant
  • -1 pour descendant
• Tri par Objet: Tri avancé utilisant des objets de tri

Limite​

• Objectif: Restreindre le nombre d'options chargées
• Type: Saisie numérique
• Défaut: Aucune limite
• Cas d'usage: Optimisation des performances pour de grands ensembles de données

Règles de Validation​

Validation Obligatoire​

• Configuration: Par écran
• Options:
  • Bascule booléenne pour requis/non requis simple
  • Conditions avancées utilisant des expressions JavaScript
• Message: Message de validation personnalisé

Règles Personnalisées​

Ajoutez des règles de validation supplémentaires :

• Longueur Min: Exigence de sélection minimale
• Longueur Max: Limite de sélection maximale
• Modèle: Validation par expression régulière
• Personnalisée: Fonctions de validation JavaScript

Configuration Basée sur l'Écran​

Configurez le comportement du widget par écran :

Disponibilité​

• Objectif: Contrôler si le widget existe sur des écrans spécifiques
• Options: Booléen ou expression conditionnelle

Visibilité​

• Objectif: Contrôler si le widget est visible sur des écrans spécifiques
• Options: Booléen ou expression conditionnelle
• Avancé: Conditions JavaScript utilisant {{variables}}

Statut Requis​

• Objectif: Contrôler si le widget est requis sur des écrans spécifiques
• Options: Booléen ou expression conditionnelle

État Désactivé​

• Objectif: Contrôler si le widget est désactivé sur des écrans spécifiques
• Options: Booléen ou expression conditionnelle

Style et Mise en Page​

Texte de l'Espace Réservé​

• Champ: Placeholder
• Objectif: Texte d'aide affiché lorsqu'aucune option n'est sélectionnée
• Exemple: "Veuillez sélectionner une option"

Largeur​

• Champ: Width
• Objectif: Contrôler la largeur du widget
• Format: Valeurs de largeur CSS (px, %, em, etc.)
• Exemple: "300px", "100%"

Classes CSS​

• Champ: Class
• Objectif: Ajouter un style CSS personnalisé
• Types:
  • Classes Statiques: Noms de classes séparés par des espaces
  • Classes Dynamiques: Classes conditionnelles basées sur l'état des données

Gestion des Événements​

Événement On Click​

• Objectif: Exécuter des actions personnalisées lorsque la sélection change
• Langage: JavaScript
• Variables Disponibles:
  • SF_input.value: Valeur sélectionnée
  • SF_input.SF_data: Objet sélectionné complet
  • SF_input.SF_currentIndex: Index de la boucle (si dans une boucle)

Intégration des Actions​

• Interface V2: Utiliser le générateur d'actions visuel
• Ancienne Version: Appels directs de fonctions JavaScript
• Paramètres: Accès aux données de sélection et au contexte

Travailler avec les Actions et SF_input​

Attacher des Actions à l'Événement onChange​

L'événement onChange (ou onClick) du widget select vous permet d'exécuter du JavaScript personnalisé chaque fois que l'utilisateur modifie sa sélection. Ceci est essentiel pour :

• Remplir automatiquement les champs de formulaire associés avec les données de l'option sélectionnée
• Déclencher des listes déroulantes en cascade ou des mises à jour de champs dépendants
• Récupérer des informations supplémentaires du backoffice en fonction de la sélection
• Implémenter un comportement de formulaire dynamique et des calculs

Comment Attacher une Action​

1. Naviguez vers la section Global dans la configuration du widget select
2. Localisez le champ d'événement On Click ou On Change
3. Écrivez du code JavaScript directement dans le champ d'action
4. Le code s'exécute automatiquement lorsque l'utilisateur effectue une sélection

Accéder aux Valeurs avec SF_input​

Le widget select fournit un accès complet aux données via l'objet SF_input. L'avantage clé est que vous obtenez à la fois la valeur sélectionnée ET l'objet de données complet de votre source de données.

Structure de SF_input pour le Widget Select​

Pour le mode de sélection simple :

{
  value: /* La valeur sélectionnée basée sur votre "Value Property" */,
  SF_data: /* Objet JSON complet de l'élément sélectionné */,
  SF_currentIndex: /* Index de la boucle si le widget est dans une boucle */
}

Pour le mode de sélection multiple (lorsque "Multi" est activé) :

{
  value: [/* Tableau des valeurs sélectionnées */],
  SF_data: [/* Tableau des objets sélectionnés complets */],
  SF_currentIndex: /* Index de la boucle si le widget est dans une boucle */
}

Comprendre les Propriétés de SF_input​

Exemples Pratiques​

Exemple 1 : Accéder à la Valeur Sélectionnée​

// Obtenir la valeur sélectionnée (sélection simple)
console.log(SF_input.value);
// Sortie: 'CUST001'

// Pour la sélection multiple
console.log(SF_input.value);
// Sortie: ['CUST001', 'CUST002', 'CUST003']

// Stocker la valeur sélectionnée dans un autre champ
model.selected_customer_id = SF_input.value;

Exemple 2 : Accéder à l'Objet JSON Complet (SF_data)​

C'est la fonctionnalité la plus puissante - accéder à l'objet de données complet, pas seulement à la valeur :

// Accéder à l'objet de données complet pour l'élément sélectionné
console.log(SF_input.SF_data);
// Sortie: {
//   id: 'CUST001',
//   name: 'John Doe',
//   email: 'john@example.com',
//   phone: '+1234567890',
//   address: {
//     street: '123 Main St',
//     city: 'New York',
//     country: 'USA'
//   },
//   credit_limit: 5000,
//   status: 'active'
// }

// Accéder à n'importe quelle propriété de l'objet sélectionné
model.customer_email = SF_input.SF_data.email;
model.customer_phone = SF_input.SF_data.phone;
model.customer_status = SF_input.SF_data.status;

// Accéder aux propriétés imbriquées
model.customer_city = SF_input.SF_data.address?.city;
model.customer_country = SF_input.SF_data.address?.country;

Bonnes Pratiques​

1. Toujours Vérifier que SF_data Existe: Avant d'accéder aux propriétés de SF_data, vérifiez qu'il n'est pas null

   if (SF_input.SF_data) {
     // Votre code ici
   }
   

2. Utiliser le Chaînage Optionnel: Pour les propriétés imbriquées, utilisez le chaînage optionnel pour éviter les erreurs

   const city = SF_input.SF_data?.address?.city || 'Inconnu';
   

3. Gérer la Sélection Simple et Multiple: Si votre widget peut basculer entre les modes, gérez les deux cas

   const selectedData = Array.isArray(SF_input.SF_data) ? SF_input.SF_data : [SF_input.SF_data];
   

4. Exploiter SF_data pour des Données Riches: Utilisez toujours SF_data lorsque vous avez besoin de plus que la simple valeur - il contient l'enregistrement complet

5. Effacer les Données Précédentes: Lorsque la sélection change, effacez les champs dépendants pour éviter les données obsolètes

   model.related_field_1 = null;
   model.related_field_2 = null;
   // Puis remplir avec les nouvelles données
   

6. Gestion des Erreurs: Enveloppez la récupération de données dans des blocs try-catch

   try {
     const data = await SF_executeAction('fetchData', { id: SF_input.value });
     // Traiter les données
   } catch (error) {
     console.error('Erreur lors de la récupération des données:', error);
     model.error_message = 'Échec du chargement des données';
   }
   

7. Performance: Pour les opérations coûteuses, envisagez le debouncing ou l'affichage d'indicateurs de chargement

Bonnes Pratiques​

1. Performance: Utilisez des limites pour les grands ensembles de données
2. Expérience Utilisateur: Activez le filtrage pour les listes de plus de 10 éléments
3. Validation: Fournissez des messages d'erreur clairs
4. Accessibilité: Utilisez des libellés et des espaces réservés descriptifs
5. Intégrité des Données: Validez les valeurs sélectionnées par rapport aux options disponibles
6. Conception Responsive: Définissez des largeurs appropriées pour différentes tailles d'écran

Dépannage​

Problèmes Courants​

1. Aucune Option Affichée

   • Vérifiez la configuration de la source de données
   • Vérifiez la syntaxe de la requête et les variables
   • Assurez-vous que les mappings de champs sont corrects

2. Problèmes de Performance

   • Ajoutez des limites appropriées
   • Utilisez le filtrage au lieu de charger toutes les données
   • Envisagez la pagination pour les très grands ensembles de données

3. Erreurs de Validation

   • Vérifiez la configuration du champ requis
   • Vérifiez les règles de validation personnalisées
   • Assurez-vous que les paramètres basés sur l'écran sont corrects

4. La Sélection ne se Sauvegarde Pas

   • Vérifiez la configuration de la variable/modèle
   • Vérifiez la compatibilité des types de données
   • Assurez-vous que la gestion de la soumission du formulaire est correcte