Aller au contenu principal

Introduction

Gérez les soumissions de formulaires et récupérez les données des formulaires.

Plus d'informations sur les formulaires dans le panneau d'administration OneEntry : https://doc.oneentry.cloud/docs/category/forms

🎯 Que fait ce module ?​

Le module FormData vous permet de soumettre des formulaires remplis par les utilisateurs (formulaires de contact, enquêtes, inscriptions) à OneEntry et de récupérer, mettre à jour ou supprimer les données soumises pour analyse, reporting et gestion.

Considérez-le comme votre gestionnaire de soumissions de formulaires - les utilisateurs soumettent des formulaires, vous les stockez dans OneEntry, et vous les récupérez chaque fois que vous devez consulter des réponses, générer des rapports ou analyser des données.

🚀 Démarrage rapide​

Initialisez le module depuis defineOneEntry :


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

Construisez le corps à partir de la configuration du formulaire et soumettez-le :

// 1. Fetch the form to read its module config.
const form = await Forms.getFormByMarker("contact_form");
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// 2. Submit the user's input.
const response = await FormData.postFormsData({
  formIdentifier: "contact_form",
  formModuleConfigId,
  moduleEntityIdentifier,
  replayTo: null,
  status: "sent",
  formData: [
    { marker: "name", type: "string", value: "Jack" },
  ],
});

console.log(response);

Pour lire les soumissions plus tard, appelez getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

✨ Concepts clés​

Qu'est-ce que les données de formulaire ?​

Les données de formulaire sont les informations que les utilisateurs soumettent via un formulaire. Chaque soumission est construite à partir d'un tableau formData d'objets de champ (marker, type, value) ainsi que des identifiants de configuration du formulaire.

Structure du corps de soumission​

postFormsData accepte un IBodyPostFormData :

const body = {
  formIdentifier: 'contact_form', // Form marker
  formModuleConfigId: 9,          // Module config ID (from the form)
  moduleEntityIdentifier: 'blog', // Module entity identifier (from the form)
  replayTo: null,                 // Email address to reply to (optional)
  status: 'sent',                 // Submission status (optional)
  formData: [                     // Form fields
    { marker: 'name', type: 'string', value: 'Test' },
  ],
};

📋 Ce que vous devez savoir​

La soumission nécessite la configuration du formulaire​

Avant de soumettre, vous avez besoin de trois valeurs, toutes lues à partir du formulaire lui-même :

  1. Marqueur de formulaire (formIdentifier) — l'identifiant textuel du formulaire
  2. formModuleConfigId — provenant des moduleFormConfigs du formulaire
  3. moduleEntityIdentifier — provenant des moduleFormConfigs du formulaire
const form = await Forms.getFormByMarker('contact_form');
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

Mettez en cache ces valeurs pour ne pas récupérer le formulaire à chaque soumission.

Champs formData​

Chaque entrée dans le tableau formData décrit un champ :

  • marker — doit correspondre à un marqueur de champ de la définition du formulaire
  • type — le type de champ (utilisé pour la validation et la gestion des fichiers)
  • value — l'entrée de l'utilisateur

Les champs de type file / image / groupOfImages sont téléchargés automatiquement via le module FileUploading lorsque vous passez un File/FileList/Blob comme value.

Statut de soumission​

Utilisez le champ status pour suivre l'état de la soumission. "sent" est la valeur typique pour les nouvelles soumissions ; vous pouvez ensuite déplacer une soumission vers un état révisé/archivé avec updateFormsDataStatusByid().

Mise à jour et suppression des soumissions​

Les soumissions ne sont pas immuables. Les utilisateurs authentifiés peuvent les modifier ou les supprimer :

  • updateFormsDataByid(id, body) — éditez une soumission stockée par id 🔐
  • updateFormsDataStatusByid(id, body) — changez uniquement le statut d'une soumission par id 🔐
  • deleteFormsDataByid(id) — supprimez une soumission par id 🔐

Lecture des soumissions​

getFormsDataByMarker renvoie les soumissions pour un formulaire. Parcourez les résultats avec offset / limit, et affinez avec le body de la requête (par exemple, status, dateFrom, dateTo, userIdentifier).

📊 Tableau de référence rapide​

MéthodeDescriptionCas d'utilisation
postFormsData()Soumettre de nouvelles données de formulaireL'utilisateur soumet un formulaire de contact
getFormsDataByMarker()Obtenir les soumissions pour un formulaire spécifiqueVoir toutes les soumissions du formulaire de contact
updateFormsDataByid() 🔐Mettre à jour une soumission de formulaire par idÉditer une soumission stockée
updateFormsDataStatusByid() 🔐Mettre à jour le statut d'une soumission par idMarquer comme traité/archivé
deleteFormsDataByid() 🔐Supprimer une soumission de formulaire par idRetirer une soumission

🔐 Les méthodes nécessitent une autorisation utilisateur — voir AuthProvider. postFormsData() et getFormsDataByMarker() sont publics.

❓ Questions Fréquemment Posées (FAQ)​

Comment soumettre un formulaire ?​

Récupérez le formulaire avec Forms.getFormByMarker(), lisez formModuleConfigId et moduleEntityIdentifier à partir de ses moduleFormConfigs, construisez le corps, puis appelez FormData.postFormsData(body). Voir la section Démarrage rapide ci-dessus.

Puis-je mettre à jour ou supprimer des données de formulaire soumises ?​

Oui. Les soumissions peuvent être modifiées ou supprimées via le SDK (cela nécessite une autorisation utilisateur) :

  • updateFormsDataByid() — éditez une soumission stockée par id
  • updateFormsDataStatusByid() — changez uniquement le statut d'une soumission par id
  • deleteFormsDataByid() — supprimez une soumission par id

Comment gérer les téléchargements de fichiers dans les formulaires ?​

Passez un File / FileList / Blob comme value d'un champ et postFormsData() le télécharge pour vous, ou téléchargez séparément avec le module FileUploading et incluez les URL retournées dans formData.

Comment filtrer les soumissions par date ?​

Passez dateFrom et dateTo dans le body de la requête de getFormsDataByMarker().

Comment paginer à travers toutes les soumissions ?​

Utilisez les arguments offset et limit de getFormsDataByMarker().

🎓 Meilleures pratiques​

  • Mettez en cache la configuration du formulaire (formModuleConfigId, moduleEntityIdentifier) pour éviter de récupérer le formulaire à chaque soumission.
  • Validez les champs requis côté client avant de soumettre ; OneEntry valide également côté serveur.
  • Paginer les lectures avec offset / limit plutôt que de tout récupérer d'un coup.
  • Référez-vous aux formulaires par marqueur, pas par ID numérique.
  • Utilisez le champ status (et updateFormsDataStatusByid) pour organiser les soumissions.
  • Gérez les erreurs avec try/catch et vérifiez la forme de retour IError.

🔗 Documentation Connexe​

  • Module Forms - Récupérer les structures de formulaire à soumettre
  • Module FileUploading - Gérer les téléchargements de fichiers dans les formulaires
  • Module Events - Configurer des notifications basées sur des événements
  • Module Users - Gérer les utilisateurs qui soumettent des formulaires