Widget Boucle

Aperçu​

Le widget Boucle vous permet de créer des sections dynamiques et répétables dans votre interface où les utilisateurs peuvent ajouter, supprimer et gérer plusieurs instances de la même structure de contenu. Ce widget est particulièrement utile pour les formulaires nécessitant un nombre variable d'entrées, tels que les listes de contacts, les inventaires d'articles ou les questionnaires dynamiques.

Fonctionnalités​

• Gestion Dynamique des Lignes : Ajoutez et supprimez des lignes de manière dynamique
• Contenu Personnalisable : Chaque ligne contient une disposition de grille configurable
• Contrôles Utilisateur : Boutons d'ajout/suppression intégrés avec texte personnalisable
• Support de Validation : Règles de validation complètes pour la visibilité, les exigences et les états désactivés
• Conception Réactive : Ajustement automatique de la disposition en fonction de la taille de l'écran

Options de Configuration​

Paramètres Globaux​

Configuration de Base​

Nom

• Champ : Name
• Description : Nom d'affichage du widget
• Type : Saisie de texte
• Utilisation : Utilisé pour l'identification et l'étiquetage

Variable/Modèle

• Champ : Variable/Model
• Description : Le modèle de données qui stocke les données du tableau de la boucle
• Type : Saisie de texte
• Requis : Oui
• Utilisation : Définit le nom de la variable qui contiendra le tableau des données de ligne

Gouttière

• Champ : Gutter
• Description : Espacement entre les colonnes en pixels
• Type : Saisie numérique
• Utilisation : Contrôle l'espacement horizontal entre les colonnes de la grille

Paramètres Spécifiques à la Boucle​

Longueur par Défaut

• Champ : Default length
• Description : Nombre initial de lignes à afficher lors du chargement du widget
• Type : Saisie numérique
• Par défaut : 0
• Minimum : 0
• Utilisation : Définit combien de lignes apparaissent initialement

Afficher le Bouton

• Champ : Show Button (Always Show)
• Description : Contrôle si le bouton d'ajout est toujours visible
• Type : Interrupteur à bascule
• Par défaut : Faux
• Utilisation : Lorsqu'il est activé, le bouton d'ajout reste visible même lorsque des lignes existent

Texte du Bouton Ajouter

• Champ : Add Text
• Description : Texte personnalisé pour le bouton d'ajout
• Type : Saisie de texte
• Par défaut : "Add"
• Utilisation : Personnalise le libellé affiché sur le bouton d'ajout

Structure du Contenu​

Le widget boucle contient une disposition de grille où vous pouvez ajouter divers éléments et composants de formulaire. Chaque ligne de la boucle contiendra la même structure d'éléments.

Colonnes

• Description : Définit la structure des colonnes pour chaque ligne
• Configuration : Chaque colonne peut avoir :
  • Span : Largeur de la colonne (1-24)
  • Paramètres Réactifs : Points de rupture xs, sm, md, lg, xl
  • Contenu : Widgets et composants imbriqués

Règles de Validation​

Validation Basée sur l'Écran​

Le widget boucle prend en charge la validation sur différents écrans/contextes :

Disponible

• Description : Contrôle si le widget est disponible sur des écrans spécifiques
• Type : Booléen par écran
• Utilisation : Masquer/afficher l'ensemble du widget boucle en fonction du contexte

Visible

• Description : Contrôle la visibilité du widget avec des conditions avancées
• Type : Booléen ou expression JavaScript
• Utilisation : Visibilité dynamique basée sur les données du formulaire ou l'interaction de l'utilisateur

Requis

• Description : Rend le widget boucle obligatoire
• Type : Booléen ou expression JavaScript
• Utilisation : Impose que les utilisateurs doivent ajouter au moins une ligne

Désactiver

• Description : Désactive la fonctionnalité du widget
• Type : Booléen ou expression JavaScript
• Utilisation : Empêche les utilisateurs d'ajouter/supprimer des lignes

Validation Avancée​

Vous pouvez utiliser des expressions JavaScript pour une validation dynamique :

Mise en Page et Stylisation​

Classes Personnalisées

1. Classes Statiques

• Champ : Class
• Type : Saisie de texte
• Utilisation : Ajoutez des noms de classes CSS séparés par des virgules
• Exemple : custom-grid, highlighted

2. Classes Dynamiques

• Accès : Cliquez sur l'icône de pinceau à côté du champ Class
• Utilisation : Écrivez des expressions JavaScript qui renvoient des noms de classe
• Contexte : Accédez aux données du modèle en utilisant le préfixe models.
• Exemple : models.status === 'active' ? 'active-grid' : 'inactive-grid'

Noms de Classe

• Champ : Class
• Description : Classes CSS personnalisées pour la stylisation
• Type : Saisie de texte
• Utilisation : Appliquez des styles personnalisés ou des classes de framework

Justifier

• Options : Start, End, Center, Space Around, Space Between
• Description : Alignement horizontal du contenu dans chaque ligne
• Utilisation : Contrôle la distribution du contenu horizontalement

Aligner

• Options : Top, Middle, Bottom
• Utilisation : Contrôle l'alignement vertical du contenu dans les colonnes
• Par défaut : Top

Ombré

• Description : Ajoute un effet d'ombre au conteneur de grille
• Type : Interrupteur à bascule
• Utilisation : Améliore la séparation visuelle

Fixe

• Description : Rend la position de la grille fixe
• Type : Interrupteur à bascule
• Utilisation : Maintient la grille dans une position fixe pendant le défilement

Interaction Utilisateur​

Ajouter des Lignes​

Les utilisateurs peuvent ajouter de nouvelles lignes de deux manières :

1. Bouton Plus : Chaque ligne existante possède un bouton plus (+) qui ajoute une nouvelle ligne après la ligne actuelle
2. Bouton d'État Vide : Lorsqu'aucune ligne n'existe ou que "Toujours Afficher" est activé, un bouton principal apparaît pour ajouter la première/ligne supplémentaire

Supprimer des Lignes​

Chaque ligne contient un bouton moins (-) qui permet aux utilisateurs de supprimer cette ligne spécifique. La suppression affecte :

• Le tableau de données (supprime l'élément correspondant)
• L'interface utilisateur (supprime la ligne immédiatement)
• La validation (revalide les lignes restantes)

Gestion des Lignes​

• Clés Uniques : Chaque ligne se voit attribuer une clé unique pour un suivi approprié
• Gestion des Index : Les indices de ligne sont gérés automatiquement
• Liaison des Données : Les données de chaque ligne sont liées à l'indice du tableau correspondant

Structure des Données​

Liaison au Modèle​

Le widget boucle stocke les données sous forme de tableau dans la variable de modèle spécifiée :

// Example data structure
loopData: [
  {
    // Row 1 data
    field1: "value1",
    field2: "value2",
    SF_row_key: "generated_unique_key",
  },
  {
    // Row 2 data
    field1: "value3",
    field2: "value4",
    SF_row_key: "generated_unique_key",
  },
];

Propriétés Spéciales​

• SF_row_key : Identifiant unique généré automatiquement pour chaque ligne
• Index du Tableau : Accessible via SF_currentIndex dans les modèles
• Données de Ligne : Accessibles via SF_currentRow dans les modèles

Exemples d'Implémentation​

Liste de Contacts de Base​

Cet exemple démontre comment utiliser le widget Boucle pour afficher une liste de contacts simple et épurée.

La première image ci-dessous montre l'étape de configuration, où vous définissez la structure d'une entrée de contact unique et configurez le comportement de boucle.

La deuxième image montre le résultat final — comment la boucle affiche la liste de manière dynamique en utilisant les données réelles du modèle.

Bonnes Pratiques​

Performance​

1. Limiter les Lignes par Défaut : Commencez avec 0-1 lignes par défaut pour améliorer le temps de chargement initial
2. Optimiser les Composants Imbriqués : Utilisez des composants légers dans les lignes de boucle
3. Implémenter la Validation Efficacement : Utilisez des vérifications booléennes simples lorsque possible

Expérience Utilisateur​

1. Libellés Clairs : Utilisez un texte descriptif pour les boutons d'ajout
2. Confirmation : Envisagez des dialogues de confirmation pour la suppression de lignes
3. Retour Visuel : Fournissez une indication claire des limites de ligne
4. Conception Réactive : Testez sur différentes tailles d'écran

Gestion des Données​

1. Validation : Implémentez une validation côté client et serveur
2. Nettoyage des Données : Supprimez les lignes vides ou invalides avant la soumission
3. Gestion de l'État : Gérez correctement les changements d'état du formulaire
4. Gestion des Erreurs : Affichez des messages d'erreur significatifs

Dépannage​

Problèmes Courants​

Les Lignes ne s'Ajoutent Pas

• Vérifiez que la liaison au modèle est correctement configurée
• Vérifiez que le bouton d'ajout n'est pas désactivé par les règles de validation
• Assurez-vous que les expressions de validation JavaScript sont syntaxiquement correctes

Les Données ne se Sauvegardent Pas

• Confirmez que la variable de modèle correspond à la structure de soumission du formulaire
• Vérifiez les erreurs de validation empêchant la soumission du formulaire
• Vérifiez les configurations des composants imbriqués

Problèmes de Mise en Page

• Examinez les valeurs de span des colonnes (doivent totaliser 24 ou moins)
• Vérifiez les paramètres des points de rupture réactifs
• Vérifiez les conflits de classes CSS

La Validation ne Fonctionne Pas

• Testez les expressions de validation dans la console du navigateur
• Vérifiez que les noms de variables correspondent à la structure des données du formulaire
• Assurez-vous que les règles de validation sont appliquées aux écrans corrects

Conseils de Débogage​

1. Journalisation Console : Utilisez la console du navigateur pour inspecter les données de boucle
2. Test de Validation : Testez les expressions avec des données d'exemple
3. Inspection de Composants : Utilisez Vue DevTools pour examiner l'état des composants
4. Flux de Données : Tracez les données du modèle à l'affichage à la soumission

Intégration avec d'Autres Widgets​

Le widget boucle fonctionne de manière transparente avec :

• Widgets de formulaire (entrées, sélections, etc.)
• Widgets d'affichage (texte, images, etc.)
• Widgets de mise en page (grilles, onglets, etc.)
• Widgets d'action (boutons, liens, etc.)

Cette configuration complète permet des formulaires dynamiques flexibles et puissants qui s'adaptent aux besoins des utilisateurs tout en maintenant l'intégrité des données et les normes d'expérience utilisateur.