Introduction

Récupérez des formulaires dynamiques avec des soumissions en temps réel et la collecte de données.

🎯 Que fait ce module ?

Le module Forms vous permet de récupérer des formulaires - formulaires de contact, enquêtes, inscriptions, formulaires de retour d'expérience - et de collecter les soumissions des utilisateurs avec validation, téléchargements de fichiers et notifications automatisées.

Considérez-le comme votre constructeur de formulaires - vous créez des formulaires dans le panneau d'administration de OneEntry, les affichez dans votre application et collectez les réponses automatiquement.

📖 Explication Simple

Imaginez que vous devez collecter des informations auprès des utilisateurs :

• 📞 Formulaire de Contact - nom, email, message, téléphone
• 📋 Enquête - questions à choix multiples, évaluations
• 👤 Formulaire d'Inscription - détails de l'utilisateur, préférences
• 💼 Candidature - téléchargement de CV, lettre de motivation
• 📝 Formulaire de Retour d'Expérience - évaluations, commentaires, suggestions
• 🎟️ Inscription à un Événement - informations sur les participants, sélection de billets

Au lieu de créer des formulaires à partir de zéro :

• ✅ Créez des formulaires dans le panneau d'administration de OneEntry (glisser-déposer des champs)
• ✅ Récupérez la structure du formulaire dynamiquement
• ✅ Soumettez des données à OneEntry (stockage automatique)
• ✅ Validez les champs (obligatoires, format email, types de fichiers)
• ✅ Recevez des notifications lorsque les formulaires sont soumis
• ✅ Consultez les réponses dans le tableau de bord d'administration

Exemple du monde réel :

Sans le Module Forms (manuel) :
- Construire le HTML/validation du formulaire manuellement ❌
- Configurer le backend pour stocker les soumissions ❌
- Créer des tables de base de données ❌
- Construire un panneau d'administration pour voir les réponses ❌
- Écrire le code de notification par email ❌

Avec le Module Forms (automatisé) :
- Créer un formulaire dans le panneau d'administration ✅
- Récupérer la structure du formulaire via l'API ✅
- Soumettre des données → Stockage automatique ✅
- Voir les réponses dans le tableau de bord ✅
- Notifications par email automatiques ✅

✨ Concepts Clés

Qu'est-ce qu'un Formulaire ?

Un formulaire est un moyen structuré de collecter des informations auprès des utilisateurs :

• Champs - Éléments d'entrée (texte, email, cases à cocher, téléchargement de fichiers)
• Validation - Règles (obligatoire, format, longueur min/max)
• Soumissions - Réponses des utilisateurs stockées dans la base de données
• Structure - Mise en page du formulaire définie dans OneEntry
• Dynamique - Récupérer la structure du formulaire depuis l'API, rendre dans votre application

Cycle de Vie du Formulaire

1. Créer un formulaire dans l'administration de OneEntry
   ↓
2. Définir les champs (nom, email, message, etc.)
   ↓
3. Définir les règles de validation
   ↓
4. Récupérer la structure du formulaire via le SDK
   ↓
5. Rendre le formulaire dans votre application
   ↓
6. L'utilisateur remplit le formulaire
   ↓
7. Soumettre les données à OneEntry
   ↓
8. La validation se produit
   ↓
9. Les données sont stockées dans la base de données
   ↓
10. Notifications envoyées (email, webhook)

Types de Champs de Formulaire

Types de champs courants que vous pouvez utiliser :

Type de Champ	Description	Utilisation Exemple
texte	Saisie de texte courte	Nom, Titre, Ville
email	Adresse email avec validation	Email de contact
textarea	Texte multi-lignes	Message, Commentaires, Bio
nombre	Saisie numérique	Âge, Quantité, Téléphone
checkbox	Case à cocher unique ou multiple	Accord des conditions, Préférences
radio	Choix unique parmi les options	Genre, Taille, Plan
select	Menu déroulant	Pays, Catégorie, Statut
file	Téléchargement de fichier	CV, Photo, Document
date	Sélecteur de date	Date de naissance, Date de l'événement

📋 Ce Que Vous Devez Savoir

Structure du Formulaire

Chaque formulaire a ces champs clés :

{
  id: 123,
  marker: "contact_form",   // Identifiant unique
  localizeInfos: {
    title: "Contactez-nous", // Titre du formulaire
    description: "Prenez contact" // Description du formulaire
  },
  fields: [   // Champs du formulaire
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "Nom" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
  ],
  statusId: 1,                 // 1 = actif, 0 = brouillon
  isActive: true,              // Le formulaire est-il activé
  successMessage: "Merci !"    // Message après soumission
}

Validation des Champs

Chaque champ peut avoir des règles de validation :

{
  "marker": "email",
  "type": "email",
  "isRequired": true, // Doit être rempli
  "validation": {
    "format": "email",  // Doit être un email valide
    "minLength": 5,     // Min 5 caractères
    "maxLength": 100,   // Max 100 caractères
    "pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // Regex personnalisée
  }
}

Règles de validation courantes :

• isRequired - Le champ doit être rempli
• minLength - Longueur minimale du texte
• maxLength - Longueur maximale du texte
• format - Format email, téléphone, URL
• pattern - Modèle regex personnalisé
• min / max - Plage de nombres
• fileTypes - Extensions de fichiers autorisées
• maxFileSize - Taille maximale du fichier

---

📊 Tableau de Référence Rapide - Méthodes

Méthode	Ce Qu'elle Fait	Quand l'utiliser
getAllForms()	Récupérer tous les formulaires (paginé)	Lister tous les formulaires disponibles
getFormByMarker()	Récupérer un formulaire par son identifiant	Récupérer un formulaire spécifique dans le code

Remarque : Pour créer/modifier des formulaires, utilisez le panneau d'administration de OneEntry. Le SDK est destiné à récupérer des formulaires et à soumettre des données.

---

❓ Questions Fréquemment Posées (FAQ)

Comment créer ou modifier des formulaires ?

Les formulaires sont créés dans le panneau d'administration de OneEntry :

1. Connectez-vous à l'administration de OneEntry
2. Allez dans la section Formulaires
3. Créez un nouveau formulaire ou modifiez un existant
4. Ajoutez des champs (glisser-déposer)
5. Configurez les règles de validation
6. Activez le formulaire

Le SDK est destiné à récupérer des formulaires et à soumettre des données, pas à créer des formulaires.

---

Comment valider les données du formulaire avant de soumettre ?

Utilisez la validation du navigateur + vérifications manuelles :

---

Puis-je télécharger des fichiers avec des formulaires ?

Oui ! Utilisez le module FileUploading et ajoutez file à votre champ :

En savoir plus : FormsData Module

---

Puis-je envoyer des notifications personnalisées lorsque le formulaire est soumis ?

Oui, configurez dans le panneau d'administration de OneEntry :

• Notifications par email à l'administrateur/utilisateur
• Notifications webhook à votre serveur
• Intégration avec le module Events

---

Comment gérer les erreurs de soumission de formulaire ?

Utilisez toujours try/catch

---

Les formulaires peuvent-ils avoir des champs conditionnels (afficher/masquer en fonction d'autres champs) ?

Pas directement dans le SDK, mais vous pouvez l'implémenter dans votre interface utilisateur

---

💡 Notes Importantes

Les Formulaires sont Créés dans le Panneau d'Administration

Rappelez-vous : Le SDK est destiné à récupérer des formulaires et à soumettre des données, pas à créer des formulaires.

Pour créer/modifier des formulaires : Utilisez le panneau d'administration de OneEntry ou l'API Admin.

---

Validez Toujours les Données

✅ La validation côté client n'est pas suffisante :

• Validez côté client (meilleure expérience utilisateur)
• Validez côté serveur (OneEntry le fait automatiquement)

---

Gérez les Téléchargements de Fichiers avec Précaution

✅ Meilleures pratiques pour les téléchargements de fichiers :

• Validez le type de fichier avant le téléchargement
• Vérifiez les limites de taille de fichier
• Affichez la progression du téléchargement
• Gérez les erreurs de téléchargement

---

🎓 Meilleures Pratiques

✅ À faire :

• Utilisez des marqueurs pour référencer les formulaires (pas d'ID)
• Validez les données côté client et serveur
• Affichez des états de chargement pendant la soumission
• Fournissez des messages d'erreur clairs
• Désactivez le bouton de soumission après une soumission réussie
• Effacez le formulaire après une soumission réussie
• Gérez les erreurs de téléchargement de fichiers avec soin
• Utilisez try/catch pour la gestion des erreurs

❌ À ne pas faire :

• Hardcoder les ID de formulaire dans le code
• Soumettre des formulaires sans validation
• Ignorer la gestion des erreurs
• Autoriser les soumissions en double
• Télécharger des fichiers sans validation de taille/type
• Afficher des erreurs techniques aux utilisateurs
• Oublier de fournir un retour d'information à l'utilisateur
• Sauter les états de chargement

---

Plus d'informations sur l'interface utilisateur du module https://doc.oneentry.cloud/docs/forms/introduction

Définition du module Forms

const { Forms } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Des exemples d'utilisation avancée peuvent être trouvés dans l'Introduction aux Formulaires.

---

🔗 Documentation Connexe

• FormsData Module - Voir et gérer les soumissions de formulaires
• Events Module - Configurer des notifications automatisées lors de la soumission de formulaires
• FileUploading Module - Gérer les téléchargements de fichiers dans les formulaires
• Users Module - Gérer les utilisateurs qui soumettent des formulaires

---