Documentation du Widget Radio

Aperçu​

Le widget Radio permet aux utilisateurs de sélectionner une seule option dans une liste prédéfinie de choix. Il s'affiche sous forme d'un groupe de boutons radio où une seule option peut être sélectionnée à la fois.

Configuration de base​

Paramètres globaux​

Nom​

• Champ : Nom
• Description : Le libellé d'affichage pour le groupe de boutons radio
• Requis : Oui
• Exemple : "Sélectionner le niveau de priorité"

Variable/Modèle​

• Champ : Variable/Modèle
• Description : La propriété du modèle de données qui stocke la valeur sélectionnée
• Requis : Oui
• Format : Doit être un nom de variable valide
• Exemple : priority_level

Valeur par défaut​

• Champ : Valeur par défaut
• Description : La valeur initialement sélectionnée lorsque le formulaire se charge
• Requis : Non
• Type : Chaîne de caractères
• Exemple : "medium"

Configuration de la source de données​

Le widget Radio prend en charge plusieurs sources de données pour remplir les options disponibles :

Données statiques​

• Source : Listes personnalisées
• Description : Utiliser des listes statiques prédéfinies
• Configuration :
  • Sélectionner une liste personnalisée existante
  • Créer une nouvelle liste personnalisée si aucune n'existe
• Format de données : Chaque élément nécessite les propriétés label et value

Données de collection​

• Source : Collections de base de données
• Description : Charger dynamiquement les options depuis une collection
• Configuration :
  • Sélectionner la collection cible
  • Configurer les mappages de libellé et de valeur
  • Configurer des filtres de requête optionnels
  • Définir l'ordre de tri et les limites

Données de rapport​

• Source : Rapports
• Description : Utiliser les résultats de rapport comme source de données
• Configuration :
  • Sélectionner le rapport cible
  • Mapper les colonnes de résultat vers libellé/valeur
  • Configurer l'agrégation si nécessaire

SQL/Base de données externe​

• Source : Connexion à une base de données externe
• Description : Interroger des bases de données externes pour les options
• Configuration :
  • Sélectionner la connexion à la base de données
  • Écrire la requête SQL
  • Mapper les colonnes de résultat

Configuration des propriétés​

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

Propriété Label​

• Champ : Label
• Description : Nom de champ ou expression pour le texte d'affichage
• Utilisation statique : firstName
• Utilisation dynamique : $.firstName + ' - ' + $.lastName

Propriété Value​

• Champ : Value
• Description : Nom de champ ou expression pour la valeur stockée
• Utilisation statique : id
• Utilisation dynamique : $.id + '-' + $.category

Configuration de requête​

Pour les sources de données de collection et de rapport :

Requête de base​

• Objectif : Filtrer et personnaliser la récupération de données
• Langage : JavaScript avec références de modèle
• Variables : Utiliser {{variable_name}} pour les valeurs dynamiques
• Exemple :

Agrégation​

• Objectif : Effectuer une agrégation de données complexe
• Basculement : Activer le commutateur "Is Aggregation"
• Exemple :

Configuration de tri​

• Trier par : Nom de champ pour le tri
• Direction :
  • 1 pour ascendant
  • -1 pour descendant

Limite​

• Objectif : Restreindre le nombre d'options
• Type : Nombre
• Par défaut : Aucune limite

Validation​

Validation basée sur l'écran​

Configurer différents comportements sur plusieurs écrans :

Disponible​

• Objectif : Contrôler si le widget apparaît sur des écrans spécifiques
• Type : Booléen par écran
• Par défaut : true

Visible​

• Objectif : Contrôler la visibilité du widget
• Options :
  • Simple : Commutateur booléen
  • Avancé : Condition JavaScript

Requis​

• Objectif : Rendre la sélection obligatoire
• Options :
  • Simple : Commutateur booléen
  • Avancé : Condition JavaScript

Désactivé​

• Objectif : Empêcher l'interaction utilisateur
• Options :
  • Simple : Commutateur booléen
  • Avancé : Condition JavaScript

Exemple simple​

Exemple avancé​

Règles de validation​

Ajouter des règles de validation personnalisées :

Types de règles​

• Pattern : Validation par expression régulière
• Custom : Fonction de validation JavaScript
• Range : Validation de plage de valeurs
• Required : Validation obligatoire intégrée

Configuration de règle​

• Règle : Sélectionner le type de validation
• Valeur : Paramètre de règle ou pattern
• Message : Message d'erreur à afficher

Style et mise en page​

Options de mise en page​

Mode d'affichage​

• Block : Empilement vertical (par défaut)
• Inline : Disposition horizontale

Bordure​

• Objectif : Ajouter des bordures autour des boutons radio
• Type : Booléen
• Par défaut : false

Configuration de largeur​

• Champ : Largeur
• Description : Valeur de largeur CSS
• Exemples :
  • 100% (pleine largeur)
  • 300px (largeur fixe)
  • 50vw (basé sur le viewport)

Classes CSS​

Classes statiques​

• Champ : Class
• Description : Noms de classes CSS séparés par des espaces
• Exemple : "custom-radio highlight-group"

Classes dynamiques​

• Objectif : Style conditionnel basé sur les données
• Langage : Expressions JavaScript
• Accès : Cliquer sur le bouton "Classes dynamiques"
• Exemple :

{
  'error-state': {{has_errors}},
  'required-field': {{is_required}}
}

Événements et interactions​

Événement On Click​

• Déclencheur : Lorsqu'une option radio est sélectionnée
• Accès aux variables :
  • SF_input.value : Valeur sélectionnée
  • SF_input.SF_data : Objet complet sélectionné
  • SF_input.SF_currentIndex : Index de boucle (si dans un contexte répétitif)

Événement simple​

• Champ : On click
• Type : Nom de fonction
• Exemple :

Travailler avec les actions et SF_input​

Attacher des actions à l'événement onChange​

L'événement onChange (ou onClick) du widget Radio vous permet d'exécuter des actions personnalisées lorsque l'utilisateur sélectionne une option. Cette fonctionnalité est puissante pour :

• Remplir automatiquement les champs de formulaire avec les données de l'option sélectionnée
• Créer des relations de champs dépendants et des mises à jour en cascade
• Récupérer des informations liées depuis la base de données du backoffice
• Implémenter une logique conditionnelle basée sur la sélection

Comment attacher une action​

1. Naviguer vers la section Global dans la configuration du widget Radio
2. Trouver le champ d'événement On Click ou On Change
3. Écrire directement du code JavaScript dans le champ d'action
4. Le code s'exécute automatiquement chaque fois que l'utilisateur sélectionne une option radio

Accéder aux valeurs avec SF_input​

Le widget Radio fournit un accès riche aux données via l'objet SF_input. Contrairement au simple stockage de valeur, vous avez accès à 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 Radio​

{
  value: /* La valeur sélectionnée basée sur votre configuration "Value Property" */,
  SF_data: /* Objet JSON complet de l'élément sélectionné */,
  SF_currentIndex: /* Index de 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
console.log(SF_input.value);
// Sortie : 'high'

// Stocker la valeur sélectionnée
model.selected_priority = SF_input.value;

// Utiliser la valeur dans une logique conditionnelle
if (SF_input.value === 'urgent') {
  model.requires_immediate_action = true;
}

Exemple 2 : Accéder à l'objet JSON complet (SF_data)​

La fonctionnalité la plus puissante - accéder à l'objet de données complet avec toutes ses propriétés :

// Accéder à l'objet de données complet
console.log(SF_input.SF_data);
// Sortie : {
//   id: 'PRIORITY_HIGH',
//   value: 'high',
//   label: 'High Priority',
//   sla_hours: 4,
//   escalation_level: 2,
//   notification_required: true,
//   color_code: '#FF5733',
//   description: 'Requires immediate attention'
// }

// Accéder à n'importe quelle propriété de l'option sélectionnée
model.sla_hours = SF_input.SF_data.sla_hours;
model.escalation_level = SF_input.SF_data.escalation_level;
model.priority_color = SF_input.SF_data.color_code;
model.priority_description = SF_input.SF_data.description;

// Utiliser les indicateurs booléens des données
if (SF_input.SF_data.notification_required) {
  model.send_notification = true;
  model.notification_type = 'urgent';
}

Exemple 3 : Remplir plusieurs champs à partir des données du backoffice​

Lorsque vous connectez un widget Radio à une source de données Collection, Rapport ou SQL, chaque option contient un enregistrement complet. Utilisez SF_data pour remplir les champs associés :

// Lorsque l'utilisateur sélectionne un département depuis les options radio connectées à la collection Departments
if (SF_input.SF_data) {
  const department = SF_input.SF_data;

  // Remplir automatiquement les informations du département
  model.department_id = department.id;
  model.department_name = department.name;
  model.department_code = department.code;
  model.department_location = department.location;

  // Remplir les informations de gestion
  model.department_head = department.manager_name;
  model.department_head_email = department.manager_email;
  model.department_head_phone = department.manager_phone;

  // Remplir les informations budgétaires
  model.department_budget = department.annual_budget;
  model.budget_spent = department.budget_utilized;
  model.budget_remaining = department.annual_budget - department.budget_utilized;

  // Remplir les détails opérationnels
  model.employee_count = department.total_employees;
  model.office_location = department.office?.building + ', Floor ' + department.office?.floor;
  model.cost_center = department.cost_center_code;

  // Définir les champs conditionnels
  if (department.requires_approval) {
    model.approval_required = true;
    model.approver_id = department.approval_authority;
  }
}

Bonnes pratiques​

1. Toujours valider SF_data : Vérifier si SF_data existe avant d'accéder à ses propriétés

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

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

   const managerEmail = SF_input.SF_data?.manager?.email || 'Non disponible';
   

3. Exploiter SF_data pour des informations riches : Toujours utiliser SF_data lorsque vous avez besoin de plus que la simple valeur - cela vous donne accès à l'enregistrement complet de votre source de données

4. Effacer les champs dépendants : Lorsque la sélection change, effacer les champs qui dépendent de la sélection précédente

   // Effacer les données précédentes
   model.related_field_1 = null;
   model.related_field_2 = null;
   // Puis remplir avec les nouvelles données de SF_input.SF_data
   

5. Gérer les cas limites : Vérifier les valeurs null/undefined et fournir des valeurs par défaut

   model.field = SF_input.SF_data?.property || 'valeur par défaut';
   

6. Utiliser des noms de variables descriptifs : Rendre votre code lisible et maintenable

   const selectedDepartment = SF_input.SF_data;
   const departmentBudget = selectedDepartment.budget;
   

7. Documenter la logique complexe : Ajouter des commentaires pour expliquer les règles métier

   // Appliquer une remise VIP si la valeur vie client dépasse le seuil
   if (SF_input.SF_data.lifetime_value > 10000) {
     model.vip_discount = 20;
   }
   

8. Gestion des erreurs : Envelopper les opérations asynchrones dans un try-catch

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

Bonnes pratiques​

Sélection de la source de données​

1. Listes statiques : Pour les options fixes, rarement modifiées
2. Collections : Pour les données gérées par l'utilisateur
3. Rapports : Pour les options calculées/agrégées
4. SQL : Pour les données externes complexes

Optimisation des performances​

1. Utiliser des limites pour les grands ensembles de données
2. Implémenter une indexation appropriée pour les champs de tri
3. Mettre en cache les données statiques lorsque possible
4. Utiliser l'agrégation pour les options récapitulatives

Expérience utilisateur​

1. Fournir des libellés clairs et descriptifs
2. Utiliser un ordre logique (alphabétique, basé sur la priorité)
3. Définir des valeurs par défaut appropriées
4. Inclure une validation avec des messages d'erreur utiles

Stratégie de validation​

1. Utiliser la validation obligatoire pour les champs critiques
2. Implémenter une validation conditionnelle si nécessaire
3. Fournir un retour immédiat lors de la sélection
4. Considérer les règles de validation inter-champs

Exemples​

Groupe radio statique de base​

Dépannage​

Problèmes courants​

Les options ne se chargent pas​

• Vérifier la configuration de la source de données
• Vérifier la syntaxe de la requête
• Assurer les mappages de champs appropriés
• Vérifier la connectivité réseau pour les sources externes

La sélection ne s'enregistre pas​

• Vérifier le nom de la variable du modèle
• Vérifier les règles de validation
• Assurer la soumission correcte du formulaire
• Valider les types de données

Problèmes de style​

• Vérifier les noms de classes CSS
• Vérifier les valeurs de largeur/hauteur
• Examiner les paramètres de design responsive
• Tester les conditions de classes dynamiques

L'événement ne se déclenche pas​

• Vérifier les noms de fonction
• Vérifier la syntaxe JavaScript
• Assurer l'accès approprié aux variables
• Consulter la console du navigateur pour les erreurs