Introduction

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

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

---

🎯 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 - afin que vous puissiez les afficher dans votre application. Vous créez des formulaires dans le panneau d'administration OneEntry ; le SDK récupère leur structure (champs, validateurs, étiquettes localisées) de manière dynamique. La collecte des soumissions réelles est gérée par le module FormsData.

🚀 Démarrage rapide

Initialisez le module depuis defineOneEntry :

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

Récupérez un formulaire unique par son marqueur et lisez ses champs :

// Fetch the "contact_form" form structure.
const form = await Forms.getFormByMarker("contact_form", "en_US");

console.log(form.identifier, form.localizeInfos.title);

// Render each field from the form's attributes.
form.attributes.forEach((field) => {
  console.log(field.marker, field.type, field.localizeInfos.title);
});

Pour lister tous les formulaires (paginés), utilisez getAllForms(langCode, offset, limit), qui renvoie un objet { total, items }.

✨ Concepts clés

Qu'est-ce qu'un formulaire ?

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

• Champs (attributes) - éléments de saisie, chacun étant un attribut avec un type (string, text, file, list, …)
• Validateurs (validators) - règles par champ (obligatoire, longueur de chaîne, format d'email)
• Structure - mise en page et étiquettes localisées définies dans l'administration OneEntry
• Soumissions - réponses des utilisateurs, soumises et récupérées via le module FormsData

Types de champs de formulaire

Le type de chaque champ est un AttributeType. Valeurs courantes :

Type (AttributeType)	Description	Exemple d'utilisation
string	Texte court sur une seule ligne	Nom, Titre, Ville
text / textWithHeader	Texte multi-lignes	Message, Commentaires, Bio
integer / real / float	Saisie numérique	Âge, Quantité, Prix
date / dateTime / time	Sélecteurs de date et heure	Date de naissance, Date d'événement
list	Liste déroulante / sélection multiple	Pays, Catégorie
radioButton	Choix unique parmi les options	Taille, Plan
file / image	Téléchargement de fichier / image	CV, Photo, Document
groupOfImages	Images multiples	Galerie
entity	Référence à une autre entité	Produit ou page liée

Remarque : L'email est un champ string avec le emailInspectionValidator activé — il n'y a pas de type de champ email séparé.

📋 Ce que vous devez savoir

Structure du formulaire

Chaque formulaire (IFormsEntity) porte un id, un identifiant (marqueur), un type optionnel ('order' | 'sing_in_up' | 'collection' | 'data' | 'rating' | null), localizeInfos (titre, message de succès, …) et un tableau attributes de champs. Chaque champ a un marker, type, localizeInfos, et un objet validators :

{
  "marker": "email",
  "type": "string",
  "localizeInfos": { "title": "Email" },
  "validators": {
    "requiredValidator": { "strict": true },
    "emailInspectionValidator": true,
    "stringInspectionValidator": { "stringMin": 5, "stringMax": 100, "stringLength": 0 }
  }
}

Validateurs courants :

• requiredValidator — { strict: boolean }, le champ doit être rempli
• stringInspectionValidator — { stringMin, stringMax, stringLength }, contraintes de longueur de texte
• emailInspectionValidator — boolean, impose le format d'email
• defaultValueValidator — valeur par défaut plus texte d'erreur personnalisé optionnel

L'ensemble de validateurs est extensible — des types de validateurs supplémentaires peuvent être renvoyés par l'API.

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

Le SDK est destiné à récupérer des formulaires (et, via le module FormsData, soumettre des données) — pas pour créer ou modifier des formulaires. Pour construire ou modifier un formulaire, utilisez le panneau d'administration OneEntry : ouvrez la section Formulaires, ajoutez des champs, configurez les règles de validation et activez le formulaire.

---

📊 Tableau de référence rapide - Méthodes

Méthode	Ce qu'elle fait	Quand l'utiliser
getAllForms()	Obtenir tous les formulaires (paginés)	Lister tous les formulaires disponibles
getFormByMarker()	Obtenir un formulaire par marqueur	Récupérer un formulaire spécifique dans le code

Les deux méthodes sont publiques — aucune autorisation utilisateur requise.

---

❓ Questions fréquentes (FAQ)

Comment créer ou modifier des formulaires ?

Les formulaires sont créés et modifiés dans le panneau d'administration OneEntry (section Formulaires), pas via le SDK. Le SDK ne fait que récupérer les structures de formulaire et soumettre des données.

---

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

Oui. Ajoutez un champ file / image / groupOfImages à votre formulaire ; les soumissions avec des fichiers sont gérées par FormData.postFormsData(), qui les télécharge automatiquement via le module FileUploading. Consultez le module FormsData.

---

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

Pas directement dans le SDK — implémentez la logique d'affichage/masquage dans votre propre interface utilisateur en fonction des valeurs des champs du formulaire récupéré.

---

🎓 Meilleures pratiques

• Référez-vous aux formulaires par leur identifiant (marqueur), pas par ID numérique.
• Rendu des champs et état requis à partir des validators de chaque champ afin que votre interface utilisateur corresponde à la validation côté serveur.
• Utilisez try/catch autour des récupérations et gérez la forme de retour IError.

---

🔗 Documentation connexe

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

---