Aller au contenu principal

Soumettre un formulaire avec un type de champ d'entité (pages, produits...)

Dans cet exemple, nous démontrons comment soumettre un formulaire qui inclut un type de champ d'entité, tel que des pages ou des produits, en utilisant l'API OneEntry.

✅ Objectif du scénario :

  • Obtenir la configuration du formulaire depuis la plateforme OneEntry
  • L'utilisateur sélectionne l'un des éléments de l'entité
  • Soumettre les données collectées à l'API OneEntry.

✅ Ce dont vous avez besoin :

  • Un PROJECT_URL et un APP_TOKEN valides pour l'authentification avec l'API OneEntry.
  • Un formulaire préconfiguré dans OneEntry avec un marqueur (par exemple, entité) et des champs incluant un de type "entité".
  • Des champs de formulaire préconfigurés incluant un de type "entité".

📌 Important :

  • Ces exemples n'incluent pas la gestion des erreurs.
  • Vous pouvez gérer les erreurs en utilisant un bloc try-catch ou en employant une construction comme await Promise.catch((error) => error).

📚 Voir dans la documentation :

📦 Référence SDK :

Essayez-le en direct​

Exécutez cette méthode de manière interactive dans le bac à sable JS SDK — connectez votre Project URL et App Token lors de votre première visite, puis ouvrez :

Scénario​

1. Importer defineOneEntry depuis le SDK et définir PROJECT_URL et APP_TOKEN​

Exemple :

import { defineOneEntry } from 'oneentry';

const PROJECT_URL = 'your-project-url';
const APP_TOKEN = 'your-app-token';

2. Créer un client API avec defineOneEntry()​

Exemple :

const { Forms, FormData } = defineOneEntry(PROJECT_URL, {
  token: APP_TOKEN,
});

3. Obtenir le formulaire avec Forms.getFormByMarker()​

Exemple :

useEffect(() => {
  Forms.getFormByMarker('entity').then((data: any) => {
    setForm(data);
    const initial: Record<string, string> = {};
    data?.attributes?.forEach((a: any) => { initial[a.marker] = ''; });
    setValues(initial);

    console.log('Form Entity ', data);
  }).catch(console.error);
}, []);

if (!form) return <div>Loading...</div>;

const sortedFields = [...(form.attributes || [])].sort(
  (a: any, b: any) => a.position - b.position,
);

const handleSubmit = async (e: any) => {
  e.preventDefault();
  if (!form) return;
  setStatus('loading');

4. Obtenir des paramètres supplémentaires pour la soumission du formulaire​

Exemple :

const moduleFormConfig = form.moduleFormConfigs?.[0];
if (!moduleFormConfig) {
  setErrorMsg('Form has no moduleFormConfigs');
  setStatus('error');
  return;
}
Résultat :
{
  "id": 1,
  "moduleIdentifier": "content",
  "isGlobal": false,
  "isClosed": false,
  "viewOnlyUserData": false,
  "commentOnlyUserData": false,
  "entityIdentifiers": [
    {
      "id": "services",
      "isNested": false
    }
  ],
  "ratingCalculation": "average",
  "allowHalfRatings": null,
  "maxRatingScale": null,
  "isAnonymous": null,
  "allowRerating": null,
  "isRating": null
}

5. Obtenir les données des champs depuis le formulaire frontend — choisir une option d'entité par champ de type entité (la sélection de l'utilisateur dans le select rendu)​

Exemple :

const fieldsData = sortedFields
  .filter((f: any) => values[f.marker])
  .map((f: any) => ({
    marker: f.marker,
    type: f.type,
    value: prepareValue(f.type, values[f.marker] || ''),
  }));
Résultat :
[
  {
    "marker": "entity",
    "type": "entity",
    "value": [
      "p-2-7"
    ]
  }
]

6. poster FormsData avec FormData.postFormsData()​

Exemple :

const response = await FormData.postFormsData({
  formIdentifier: 'entity',
  formData: fieldsData,
  formModuleConfigId: moduleFormConfig.id,
  moduleEntityIdentifier: moduleFormConfig.entityIdentifiers?.[0]?.id || '',
  replayTo: null,
  status: 'sent',
}).catch((e: any) => e);
Résultat :
{
  "formData": {
    "formIdentifier": "entity",
    "time": "2026-06-06T10:21:42.166Z",
    "formData": [
      {
        "marker": "entity",
        "type": "entity",
        "value": [
          "p-2-7"
        ]
      }
    ],
    "entityIdentifier": "services",
    "fingerprint": "UQ_zhfcsr_mpdtr691jq7d",
    "isUserAdmin": false,
    "formModuleId": 1,
    "userIdentifier": null,
    "parentId": null,
    "id": 174
  },
  "actionMessage": ""
}

Exemple final​

import React from 'react';

// Note: React is a sandbox global — in your project use named imports from 'react'
const { useState, useEffect } = React;

// 1. Import defineOneEntry from SDK and define PROJECT_URL and APP_TOKEN
import { defineOneEntry } from 'oneentry';

const PROJECT_URL = 'your-project-url';
const APP_TOKEN = 'your-app-token';

// 2. Creating an API client with [defineOneEntry()](/docs/index/#Installation)
const { Forms, FormData } = defineOneEntry(PROJECT_URL, {
  token: APP_TOKEN,
});

// Prepare value for API submission by field type.
function prepareValue(type: string, value: string) {
  if (type === 'text') return [{ plainValue: value }];
  if (type === 'list' || type === 'radioButton') return [value];
  if (type === 'entity') return [/^\d+$/.test(value) ? Number(value) : value];
  return value;
}

const EntityForm = () => {
  const [form, setForm] = useState<any>(null);
  const [values, setValues] = useState<Record<string, string>>({});
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
  const [errorMsg, setErrorMsg] = useState('');

  // 3. Get form with [Forms.getFormByMarker()](/docs/forms/getFormByMarker)
  useEffect(() => {
    Forms.getFormByMarker('entity').then((data: any) => {
      setForm(data);
      const initial: Record<string, string> = {};
      data?.attributes?.forEach((a: any) => { initial[a.marker] = ''; });
      setValues(initial);

      console.log('Form Entity ', data);
    }).catch(console.error);
  }, []);

  if (!form) return <div>Loading...</div>;

  const sortedFields = [...(form.attributes || [])].sort(
    (a: any, b: any) => a.position - b.position,
  );

  const handleSubmit = async (e: any) => {
    e.preventDefault();
    if (!form) return;
    setStatus('loading');

    // 4. Get additional settings for the form submission
    const moduleFormConfig = form.moduleFormConfigs?.[0];
    if (!moduleFormConfig) {
      setErrorMsg('Form has no moduleFormConfigs');
      setStatus('error');
      return;
    }

    // 5. Get fields data from the frontend form — pick one entity option per entity-typed field (the user's selection from the rendered select)
    const fieldsData = sortedFields
      .filter((f: any) => values[f.marker])
      .map((f: any) => ({
        marker: f.marker,
        type: f.type,
        value: prepareValue(f.type, values[f.marker] || ''),
      }));

    // 6. post FormsData with [FormData.postFormsData()](/docs/forms-data/postFormsData)
    const response = await FormData.postFormsData({
      formIdentifier: 'entity',
      formData: fieldsData,
      formModuleConfigId: moduleFormConfig.id,
      moduleEntityIdentifier: moduleFormConfig.entityIdentifiers?.[0]?.id || '',
      replayTo: null,
      status: 'sent',
    }).catch((e: any) => e);

    if (response?.statusCode >= 400) {
      setErrorMsg(response.message || 'Submission failed');
      setStatus('error');
    } else {
      setStatus('success');
      console.log('Submit response: ', response);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <h2>{form.localizeInfos?.title || 'Entity Form'}</h2>

      {sortedFields.map((field: any) => {
        const label = field.localizeInfos?.title || field.marker;
        const value = values[field.marker] || '';
        const required = !!field.validators?.requiredValidator?.strict;
        const placeholder = field.additionalFields?.placeholder?.value || '';
        const onChange = (val: string) =>
          setValues((prev) => ({ ...prev, [field.marker]: val }));

        if (field.type === 'entity') {
          const options = field.listTitles || [];
          if (options.length > 0) {
            return (
              <div key={field.marker}>
                <label htmlFor={field.marker}>{label}</label>
                <select
                  id={field.marker}
                  value={value}
                  required={required}
                  onChange={(e: { target: { value: string; }; }) => onChange(e.target.value)}
                >
                  <option value="">— Select —</option>
                  {options.map((opt: any) => {
                    // For entity fields, listTitles[].value is an object ({ id, depth, ... }),
                    // so use its primitive `id` for the key/value (a page id like 25 or product like "p-1-123").
                    const optValue = opt.value && typeof opt.value === 'object' ? opt.value.id : opt.value;
                    return (
                      <option key={optValue} value={optValue}>{opt.title}</option>
                    );
                  })}
                </select>
              </div>
            );
          }
          return (
            <div key={field.marker}>
              <label htmlFor={field.marker}>{label}</label>
              <input
                id={field.marker}
                type="text"
                value={value}
                placeholder={placeholder || 'Page id (e.g. 25) or product (e.g. p-1-123)'}
                required={required}
                onChange={(e: { target: { value: string; }; }) => onChange(e.target.value)}
              />
            </div>
          );
        }

        return (
          <div key={field.marker}>
            <label htmlFor={field.marker}>{label}</label>
            <input
              id={field.marker}
              type="text"
              value={value}
              placeholder={placeholder}
              required={required}
              onChange={(e: { target: { value: string; }; }) => onChange(e.target.value)}
            />
          </div>
        );
      })}

      {status === 'error' && <p role="alert">{errorMsg}</p>}
      {status === 'success' && <p role="status">Form submitted successfully!</p>}

      <button type="submit" disabled={status === 'loading'}>
        {status === 'loading' ? 'Submitting...' : 'Submit'}
      </button>
    </form>
  );
};

export default EntityForm;