Soumission de formulaire sans tête avec l'API WordPress REST

Si vous construisez un site WordPress, vous avez besoin d'une bonne raison de ne pas choisir un plugin de formulaire WordPress. Ils sont pratiques et offrent de nombreuses personnalisations qui prendraient une tonne d'efforts à construire à partir de zéro. Ils rendent le HTML, valident les données, stockent les soumissions et fournissent l'intégration avec des services tiers.

Mais supposons que nous prévoyons d'utiliser WordPress comme CMS sans tête. Dans ce cas, nous interagirons principalement avec l'API REST (ou GraphQL). La partie frontale devient entièrement notre responsabilité, et nous ne pouvons plus compter sur les plugins de formulaires pour faire le levage lourd dans ce domaine. Maintenant, nous sommes sur le siège du conducteur en ce qui concerne l'avant.

Les formulaires étaient un problème résolu, mais maintenant nous devons décider quoi faire à leur sujet. Nous avons quelques options:

• Utilisons-nous notre propre API personnalisée si nous avons une telle chose? Sinon, et nous ne voulons pas en créer un, nous pouvons aller avec un service. Il existe de nombreux bons fournisseurs de formulaires statiques, et les nouveaux apparaissent constamment.
• Pouvons-nous continuer à utiliser le plugin WordPress que nous utilisons déjà et exploitez sa validation, son stockage et son intégration?

Le plugin de formulaire gratuit le plus populaire, le formulaire de contact 7, a un point de terminaison de l'API REST de soumission, tout comme le plugin payant bien connu, les formulaires de gravité, entre autres.

D'un point de vue technique, il n'y a pas de réelle différence entre la soumission des données du formulaire à un point final fourni par un service ou un plugin WordPress. Nous devons donc décider en fonction de différents critères. Le prix est évident; Après cela est la disponibilité de l'installation WordPress et de son API REST. La soumission à un point final suppose qu'elle est toujours disponible publiquement. C'est déjà clair en ce qui concerne les services, car nous les payons pour qu'ils soient disponibles. Certaines configurations peuvent limiter l'accès WordPress aux processus d'édition et de construction. Une autre chose à considérer est l'endroit où vous souhaitez stocker les données, en particulier d'une manière qui adhère aux réglementations GPDR.

En ce qui concerne les fonctionnalités au-delà de la soumission, les plugins de formulaire WordPress sont difficiles à égaler. Ils ont leur écosystème, les modules complémentaires capables de générer des rapports, des PDF, une intégration facilement disponible avec les newsletters et les services de paiement. Peu de services offrent autant dans un seul package.

Même si nous utilisons WordPress de la manière «traditionnelle» avec le frontal basé sur un thème WordPress, l'utilisation de l'API REST d'un plugin de formulaire pourrait avoir un sens dans de nombreux cas. Par exemple, si nous développons un thème en utilisant un cadre CSS d'abord utilitaire, le style de la forme rendue avec un balisage fixe structuré avec une convention de classe BEM laisse un goût aigre dans la bouche de tout développeur.

Le but de cet article est de présenter les deux points de terminaison de soumission des plugins de formulaire WordPress et de montrer un moyen de recréer les comportements typiques liés au formulaire que nous avons habitués à sortir de la boîte. Lors de la soumission d'un formulaire, en général, nous devons faire face à deux problèmes principaux. L'un est la soumission des données elle-même, et l'autre fournit des commentaires significatifs à l'utilisateur.

Alors, commençons là.

Les points de terminaison

La soumission de données est la partie la plus simple. Les deux points de terminaison s'attendent à une demande de poste, et la partie dynamique de l'URL est l'ID de formulaire.

L'API du formulaire de contact 7 est disponible immédiatement lorsque le plugin est activé, et cela ressemble à ceci:

 https: //your-site.tld/wp-json/contact-for-7/v1/contact-formes/ <form_id> / feedback</form_id>

Si nous travaillons avec des formulaires de gravité, le point de terminaison prend cette forme:

 https: //your-site.tld/wp-json/gf/v2/forms/ <form_id> / soumissions</form_id>

L'API REST des formulaires de gravité est désactivé par défaut. Pour l'activer, nous devons aller aux paramètres du plugin, puis à la page API REST et vérifier l'option «Activer l'accès à l'API». Il n'est pas nécessaire de créer une clé API, car le point de terminaison de soumission de formulaire ne le nécessite pas.

Mise à jour (10 septembre 2024): Les ID sont hachées dans le formulaire de contact 7 version 5.8, mais peuvent toujours être trouvés dans l'URL de la page d'édition du formulaire.

Le corps de la demande

Notre formulaire d'exemple a cinq champs avec les règles suivantes:

• un champ de texte requis
• un champ de messagerie requis
• Un champ de date requis qui accepte les dates avant le 4 octobre 1957
• une TextArea facultative
• une case à cocher requise

Pour les clés corporelles de la demande du formulaire de contact 7, nous devons les définir avec la syntaxe de formulaire de formulaire:

 {
  "Somebodys-name": "Marian Kenney",
  "any-email": "[e-mail protégé]",
  "Avant-space-age": "1922-03-11",
  "Message facultatif": "",
  "faux termes": "1"
}

Les formulaires de gravité attendent les clés dans un format différent. Nous devons utiliser un ID de champ incrémentiel généré automatiquement avec le préfixe Input_. L'ID est visible lorsque vous modifiez le champ.

 {
  "Input_1": "Marian Kenney",
  "input_2": "[e-mail protégé]",
  "Input_3": "1922-03-11",
  "input_4": "",
  "input_5_1": "1"
}

Soumettre les données

Nous pouvons nous sauver beaucoup de travail si nous utilisons les clés attendues pour les attributs de nom des entrées. Sinon, nous devons mapper les noms d'entrée aux touches.

Aménagement tout, nous obtenons une structure HTML comme celle-ci pour le formulaire de contact 7:

Nom de quelqu'un label> Soumettre form>

Dans le cas des formulaires de gravité, nous devons seulement changer l'action et les attributs de nom:

Nom de quelqu'un label> Soumettre form>

Étant donné que toutes les informations requises sont disponibles dans le HTML, nous sommes prêts à envoyer la demande. Une façon de le faire est d'utiliser le formdata en combinaison avec le fetch:

 const FormSubmissionHandler = (événement) => {
  event.PreventDefault ();

  const Formement = event.target,
    {action, méthode} = formation,
    Body = new FormData (formation);

  fetch (action, {
    méthode,
    corps
  })
    .Then ((réponse) => réponse.json ())
    .Then ((réponse) => {
      // déterminer si la soumission n'est pas valide
      if (isformSubmissionError (réponse)) {
        // gérer le cas lorsqu'il y a des erreurs de validation
      }
      // gérer le chemin heureux
    })
    .Catch ((error) => {
      // gérer le cas lorsqu'il y a un problème avec la demande
    });
};

const FormElement = document.QuerySelector ("form");

FormElement.AddeventListener ("Soumider", FormSubmissionHandler);

Nous pouvons envoyer la soumission avec peu d'effort, mais l'expérience utilisateur est pour le moins. Nous devons aux utilisateurs autant de conseils que possible pour soumettre le formulaire avec succès. À tout le moins, cela signifie que nous devons:

• afficher un message d'erreur ou de réussite globale,
• Ajouter des messages d'erreur de validation de champ en ligne et des instructions possibles, et
• Attirez l'attention sur les pièces qui nécessitent une attention avec les classes spéciales.

Validation du terrain

En plus de l'utilisation de la validation du formulaire HTML intégré, nous pouvons utiliser JavaScript pour une validation supplémentaire côté client et / ou profiter de la validation côté serveur.

En ce qui concerne la validation côté serveur, les formulaires de contact 7 et les formulaires de gravité l'offrent hors de la boîte et renvoient les messages d'erreur de validation dans le cadre de la réponse. Ceci est pratique car nous pouvons contrôler les règles de validation de l'administrateur WordPress.

Pour des règles de validation plus complexes, comme la validation conditionnelle du champ, il pourrait être logique de se fier uniquement à la côté du serveur, car la maintenance de la validation JavaScript frontale en synchronisation avec le paramètre des plugins peut devenir un problème de maintenance.

Si nous allons uniquement avec la validation côté serveur, la tâche devient en analysant la réponse, en extraction des données pertinentes et en manipulation DOM comme l'insertion d'éléments et basculer les noms de classe.

Messages de réponse

La réponse lorsqu'il y a une erreur de validation pour le formulaire de contact 7 ressemble à ceci:

 {
  "dans": "#",
  "statut": "validation_failed",
  "Message": "Un ou plusieurs champs ont une erreur. Veuillez vérifier et réessayer.",
  "posté_data_hash": "",
  "invalid_fields": [
    {
      "Into": "span.wpcf7-form-control-wap.somebodys-name",
      "Message": "Le champ est requis.",
      "idref": null,
      "error_id": "-ve-somebodys-name"
    },
    {
      "Into": "span.wpcf7-form-control-wap.any-email",
      "Message": "Le champ est requis.",
      "idref": null,
      "error_id": "-ve-any-email"
    },
    {
      "Into": "span.wpcf7-form-control-wap.before space-age",
      "Message": "Le champ est requis.",
      "idref": null,
      "error_id": "-ve-avant-espace-age"
    },
    {
      "dans": "span.wpcf7-form-control-wap.fake-terms",
      "Message": "Vous devez accepter les termes et conditions avant d'envoyer votre message.",
      "idref": null,
      "error_id": "-ve-tterms"
    }
  ]]
}

Sur une soumission réussie, la réponse ressemble à ceci:

 {
  "dans": "#",
  "statut": "mail_sent",
  "Message": "Merci pour votre message. Il a été envoyé.",
  "Publié_data_hash": "d52f9f9de995287195409fe6dcde0c50"
}

Par rapport à cela, la réponse d'erreur de validation des formulaires Gravity est plus compacte:

 {
  "is_valid": false,
  "validation_messages": {
    "1": "Ce champ est requis.",
    "2": "Ce champ est requis.",
    "3": "Ce champ est requis.",
    "5": "Ce champ est requis."
  },
  "page_number": 1,
  "source_page_number": 1
}

Mais la réponse sur une soumission réussie est plus grande:

 {
  "is_valid": vrai,
  "page_number": 0,
  "source_page_number": 1,
  "Confirmation_Message": "<div id="'gform_confirmation_wrapper_1'" class="'gform_confirmation_wrapper'"> <div id="'gform_confirmation_message_1'" class="'gform_confirmation_message_1" gform_confirmation_message> GORIED US!
  "confirmation_type": "message"
}<p> Bien que les deux contiennent les informations dont nous avons besoin, ils ne suivent pas une convention commune et ont leurs bizarreries. Par exemple, le message de confirmation dans les formulaires de gravité contient HTML, et les touches de message de validation n'ont pas le préfixe Input_ - le préfixe requis lorsque nous envoyons la demande. De l'autre côté, les erreurs de validation dans le formulaire de contact 7 contiennent des informations pertinentes uniquement pour leur implémentation frontale. Les touches de champ ne sont pas immédiatement utilisables; Ils doivent être extraits.</p>
<p> Dans une situation comme celle-ci, au lieu de travailler avec la réponse que nous obtenons, il vaut mieux trouver un format idéal souhaité. Une fois que nous avons cela, nous pouvons trouver des moyens de transformer la réponse originale à ce que nous jugeons. Si nous combinons le meilleur des deux scénarios et supprimons les pièces non pertinentes pour notre cas d'utilisation, nous nous retrouvons avec quelque chose comme ceci:</p>
<pre rel="JSON" data-line=""> {
  "Issuce": faux,
  "Message": "Un ou plusieurs champs ont une erreur. Veuillez vérifier et réessayer.",
  "ValidationError": {
    "Somebodys-name": "Ce champ est requis.",
    "Any-Email": "Ce champ est requis.",
    "Input_3": "Ce champ est requis.",
    "Input_5": "Ce champ est requis."
  }
}

Et sur une soumission réussie, nous définissons l'émission sur true et renvoie un objet d'erreur de validation vide:

 {
  "émetteur": vrai,
  "Message": "Merci de nous avoir contactés! Nous vous contacterons sous peu.",
  "ValidationError": {}
}

Maintenant, il s'agit de transformer ce que nous avons obtenu en ce dont nous avons besoin. Le code pour normaliser la réponse des formulaires de contact 7 est le suivant:

 const normalizontactform7Response = (réponse) => {
  // Les autres statuts possibles sont différents types d'erreurs
  const Issucess = réponse.status === 'Mail_sent';
  // Un message est fourni pour tous les statuts
  const Message = Response.Message;
  const ValidationError = émetteur
    ? {}
    : // nous transformons un tableau d'objets en un objet
    Object.fromentries (
      réponse.invalid_fields.map ((erreur) => {
        // extrait la pièce après "cf7-form-control-wap"
        const Key = /cf7[-Aze .*.(.*)/.exec(Error.into)@1];

        return [key, error.sessage];
      })
    ));

  retour {
    émetteur,
    message,
    ValidationError,
  };
};

Le code pour normaliser la réponse des formulaires de gravité se termine par le fait:

 const normalisegravityformsResponse = (réponse) => {
  // fourni déjà comme booléen dans la réponse
  const issucess = réponse.is_valid;
  const Message = Issucess
    ? // vient enveloppé dans un HTML et nous n'avons probablement pas besoin de cela
      StripHtml (réponse.confirmation_message)
    : // Pas de message d'erreur général, nous définissons donc un repli
      «Il y avait un problème avec votre soumission.»;
  const ValidationError = émetteur
    ? {}
    : // nous remplacons les touches par la version préfixée;
      // De cette façon, la demande et la réponse correspondent
      Object.fromentries (
        Object.ntries (
            réponse.validation_messages
        ) .map (([clé, valeur]) => [`entrée _ $ {key}`, valeur])
      ));

  retour {
    émetteur,
    message,
    ValidationError,
  };
};

Il nous manque toujours un moyen d'afficher les erreurs de validation, les messages de réussite et les classes basculantes. Cependant, nous avons une façon intéressante d'accéder aux données dont nous avons besoin, et nous avons supprimé toutes les incohérences dans les réponses avec une abstraction légère. Une fois assemblé, il est prêt à être déposé dans une base de code existante, ou nous pouvons continuer à construire par-dessus.

Il existe de nombreuses façons de s'attaquer à la partie restante. Ce qui est logique dépendra du projet. Pour les situations où nous devons principalement réagir aux modifications de l'État, une bibliothèque déclarative et réactive peut beaucoup aider. Alpine.js était couvert ici sur CSS-Tricks, et c'est un ajustement parfait pour les deux démonstrations et l'utiliser dans les sites de production. Presque sans aucune modification, nous pouvons réutiliser le code de l'exemple précédent. Nous n'avons qu'à ajouter les directives appropriées et aux bons endroits.

Emballage

Faire correspondre l'expérience frontale que les plugins WordPress Forms peuvent être réalisés avec une facilité relative pour des formulaires simples et sans tracas - et d'une manière réutilisable d'un projet à l'autre. Nous pouvons même l'accomplir d'une manière qui nous permet de changer le plugin sans affecter l'avant.

Bien sûr, il faut du temps et des efforts pour créer une forme de plusieurs pages, des aperçus des images téléchargées ou d'autres fonctionnalités avancées que nous serions normalement cuites dans un plugin, mais plus les exigences que nous devons répondre, plus il est logique d'utiliser le point de terminaison de la soumission car nous n'avons pas à travailler contre la mise en œuvre frontale donnée que les tests pour résoudre de nombreux problèmes, mais jamais le particulier que nous voulons.

L'utilisation de WordPress comme CMS sans tête pour accéder à l'API REST d'un plugin de formulaire pour frapper les points de terminaison de soumissions deviendra sûrement une pratique plus largement utilisée. C'est quelque chose qui vaut la peine d'explorer et de garder à l'esprit. À l'avenir, je ne serais pas surpris de voir des plugins de formulaires WordPress conçus principalement pour fonctionner dans un contexte sans tête comme celui-ci. Je peux imaginer un plugin où le rendu frontal est une fonctionnalité complémentaire qui ne fait pas partie intégrante de son noyau. Quelles conséquences qui auraient, et si cela pouvait avoir un succès commercial, reste à explorer mais est un espace fascinant à regarder évoluer.