Créer ses propres traitements avec Formidable

Résumé

Un traitement formidable est composé de deux fichiers situés dans un dossier traiter accessible via le path de file.

• Un fichier .yaml (optionnel) décrivant le traitement : nom, description, options, dépendances éventuelles à d’autres traitements
• Un fichier .php contenant différentes fonctions. Vous êtes libres d’organiser les fonctions que vous voulez, mais formidable reconnaitra automatiquement certaines fonctions :
  • une pour enclencher le traitement lors de la soumission du formulaire (cas le plus courant) ;
  • une pour effectuer des vérifications complémentaires lors de la soumission du formulaire ;
  • une pour enclencher le traitement lorsque le statut d’une réponse est modifié (ajouté en formidable 7.0) ;

Le présent article va décrire le contenu de ces deux fichiers.

Préalable

Chaque traitement dispose d’un « nom technique » interne. Par exemple le traitement « Envoyer par email » a pour nom email. Dans la suite, lorsque nous parlerons du nom du traitement, c’est toujours à ce nom que nous ferons référence. Ce nom sert dans les noms des fichiers et des fonctions.

Dans le présent article, <nom> doit être remplacé par le nom technique du traitement.

Bien que cela ne soit pas stricto sensu nécessaire, il est vivement recommandé lorsqu’on crée un traitement complémentaire pour formidable de le distribuer sous forme d’un plugin. Lire la documentation officielle sur la création de plugins.

Dans le paquet.xml du plugin, on veillera à inclure la dépendance à formidable :

<necessite nom="formidable" /> 

Il est recommandé de mettre une borne maximum, car formidable se développant régulièrement, il peut arriver des ruptures de compatibilités, marquées par un changement de x. La syntaxe suivante permet de faire fonctionner le plugin uniquement avec formidable v7.

<necessite nom="formidable" compatibilite="[7.0.0;7.*]" /> 

Au moment de la sortie de formidable v8, les informations sur les ruptures de compatibilités seront fournies. Il conviendra alors, si besoin, d’ajuster le code du plugin puis d’élargir la borne de compatibilité.

Le fichier .yaml

Le fichier traiter/<nom>.yaml contient la description du traitement. Il est utilisé pour permettre son activation et sa configuration dans le formulaire de configuration des traitements.

A noter que depuis Formidable 7.2.0 il est possible de déclarer une fonctions PHP pour décrit le traitement. Nous y reviendrons. Cependant, dans la plupart des cas, l’utilisation d’un fichier .yaml suffit.

Dans l’ensemble du fichier .yaml il est recommandé d’utiliser les chaînes de langues spip : <:prefix_plugin:valeur:>.

Titre et description du traitement

Les deux premières entrées, les seules obligatoires, de ce fichier .yaml sont :

• le titre du traitement : titre, correspond au libellé de la case à cocher pour activer le traitement
• la description du traitement : description, correspond au libellé de l’onglet pour configurer le traitement. C’est aussi le texte qui s’affiche sous « Traitements activés »

Exemple dans le fichier traiter/enregistrement.yaml livré en standard avec formidable :

titre: '<:formidable:traiter_enregistrement_titre:>'
description: '<:formidable:traiter_enregistrement_description:>'

Dépendance

Il est possible de dire qu’un traitement ne peut être activé que si un ou plusieurs autres traitements le sont. L’entrée necessite peut contenir une liste de nom de traitements. Par ailleurs, lorsque qu’un traitement nécessite un autre traitement, il est exécuté systématiquement après celui ci (mais pas forcément immédiatement après).

Par exemple le traitement participation du plugin « Formulaire de participation à un évènement avec Formidable » ne peut être activé que si le traitement enregistrement livré par défaut est lui-même activé.

necessite:
  - 'enregistrement' 

Utilisation

Il est possible de dire qu’un traitement utilise un ou plusieurs autres traitements. L’entrée utilise peut contenir une liste de nom de traitements. Lorsque qu’un traitement utilise un autre traitement, il est exécuté systématiquement après celui ci (mais pas forcément immédiatement après).

Par exemple le traitement email livré avec Formidable est exécuté après le traitement enregistrement. Ceci permet de disposer du numéro de réponse dans le mail.

utilise: ['enregistrement']

Options

Lors de l’activation d’un traitement, celui-ci peut être configuré via des options. Celle-ci sont décrites sous forme d’une liste de saisies sous la clé options.

Exemple :

options:
  - 
    saisie: 'case'
    options: 
      nom: '<nom_de_l_option>'
      label: '<label_de_l_option>' 

Affichage conditionnel d’une option

Il est possible d’utiliser la clé afficher_si dans les options des saisies pour effectuer des affichages conditionnels. Il y a toutefois une petite subtilité : le nom du champ (entre @@) doit être sous la forme : @traitements[<nom_du_traitement>][<nom_de_loption__conditionnante>]@. Exemple :

  -
    saisie: 'fieldset'
    options:
      nom: 'responsable'
      afficher_si: '@traitements[email][activer_responsable]@'
      onglet: 'on'
      label: '<:formidable:traiter_email_responsable_label:>'

Il est donc possible de tester la valeur d’une option d’un autre traitement. On peut également tester si un autre traitement est activé avant d’afficher une option en utilisant @traitements_choisis@ IN "<nom_du_traitement>". Exemple dans le traitement email livré en standard :

      -
        saisie: 'checkbox'
        options:
          nom: 'quand_envoyer_accuse'
          label: '<:formidable:traiter_email_quand_envoyer_accuse_label:>'
          data:
            'immediat': '<:formidable:traiter_email_quand_envoyer_immediat_label:>'
            'publie': '<:formidable:traiter_email_quand_envoyer_publie_label:>'
          defaut: ['immediat']
          obligatoire: 'on'
          afficher_si: '@traitements_choisis@ IN "enregistrement" && @traitements[enregistrement][moderation]@ == "priori"'

Proposer de choisir un champ

Il est possible lors de la configuration des options de proposer de choisir un ou plusieurs champs du formulaire formidable que l’on configure.

Pour ce faire on utilisera la saisie champ. Celle-ci dispose des options suivantes :

Exemples

          -
            saisie: 'champ'
            options:
              nom: 'champ_destinataires'
              label: '<:formidable:traiter_email_option_destinataires_label:>'
              explication: '<:formidable:traiter_email_option_destinataires_explication:>'
              forcer_type: [destinataires,hidden]
              type_choix: 'checkbox'
              env: true

Le fichier .php

Le fichier traiter/<nom>.php contient le traitement proprement dit. Il peut également contenir
-  une description du traitement à la place du fichier .yaml ;
-  des vérifications propres au traitement ;
-  des actions à effectuer lorsque le statut d’une réponse est modifié.

La fonction traiter_<nom>_config()

Cette fonction peut remplacer le fichier .yaml. Attention, si un fichier .yaml est présent, celui-ci est prioritaire.

Elle renvoie un tableau contenant exactement les mêmes informations que le fichier .yaml. Il est intéréssant de passer par une telle fonction si les options de configuration sont variables, selon par exemple la présence de telle configuration générale de SPIP, ou encore selon l’existence de certains fichiers dans le path de SPIP.

Un exemple d’utilisation d’une telle fonction se trouve dans le plugin participation_evenement_attestation.

La fonction traiter_<nom>_dist()

Cette fonction effectue le traitement.

En entrée elle reçoit deux arguments :

1. $args (array) tableau associatif contenant différentes valeurs utiles pour pouvoir effectuer le traitement :
   • formulaire (array) description complète du formulaire (ligne dans la table spip_formulaires)
   • options (array) options du traitement configuré lors de la création du formulaire
   • options_appel (array) options lors de l’appel au formulaire (troisième argument de #FORMULAIRE_FORMIDABLE)
   • saisies (array) description complète des saisies du formulaire
   • traitements (array) description des traitements associés au formulaire
   • id_formulaire (int) identifiant du formulaire
   • valeurs (array) valeurs passées lors de l’appel du formulaire (second argument de #FORMULAIRE_FORMIDABLE
   • id_formulaires_reponse (int|false) : identifiant de la réponse qu’on a demandé de modifier, false si pas de modification d’une réponse
   • forcer_modif (bool) à true? si l’option forcer_modif a été passée lors de l’appel
   • message_retour_general (string) message de retour général du formulaire
2. $retours tableau associatif qui pourra être modifié et devra être renvoyé
   • message_ok (string) message de retour si tout va bien
   • message_erreur(string) message d’erreur en cas de problème
   • traitements (array) liste des traitements déjà effectués
   • id_formulaire_reponse (int|false) identifiant de la réponse qui vient d’être créée ou enregistrée
   • modification_reponse (bool) à true si le formulaire a modifié une réponse existante, false sinon (création d’une nouvelle réponse en base / pas d’enregistrement de réponse)
   • erreurs (array) liste des erreurs sur les précédents traitements

Dans le code de la fonction, vous pouvez utiliser tout ce qui est fourni en appel et n’importe quel code PHP pour effectuer vous-même le traitement. C’est là que vos compétences en programmation seront déployées. Il est probable que vous devrez retrouver les valeurs postées par l’internaute en utilisant la fonction saisies_request() [1].

Il vous faudra compléter le tableau $retours en modifiant le cas échéant les entrées message_ok et/ou message_erreur. Il est possible également d’utiliser une clé scripts_ok pour passer un code JavaScript à exécuter.

Il ne faut pas gérer dans le code d’un traitement les retours d’un autre traitement. $retours['message_ok'], $retours['script_xx'] et $retours['message_erreur'] ne doivent contenir que les messages, scripts et erreurs du traitement courant. Les message_ok, scripts_ok et message_erreur des différents traitements seront automatiquement concaténés, à la fin, par formidable.

Surtout, il vous faudra compléter l’entrée traitements en indiquant que le traitement a été effectué. Par exemple, une fois l’email envoyé, le traitement email a cette ligne de code :

 $retours['traitements']['email'] = true;

Il est également possible d’ajouter une clé redirect permettant de rediriger vers une URL. Attention : il n’y a pas de mécanisme de gestion des conflits de redirection. Le dernier traitement à modifier cette clé l’emporte.

La fonction traiter_<nom>_verifier_dist()

Formidable se charge d’effectuer automatiquement les vérifications sur les champs définis lors de la création du formulaire. Cependant, certains traitements peuvent nécessiter des vérifications supplémentaires.

Par exemple le traitement enregistrement doit pouvoir vérifier, si le formulaire y a recours, qu’un champ a une valeur unique.

On peut donc définir une fonction traiter_<nom>_verifier_dist() qui reçoit en entrée deux arguments :

1. $args (array) tableau clé/valeurs recevant les mêmes valeurs que $args de la fonction traiter_<nom>_dist() (plus haut), complété par une clé etape (int|null) indiquant l’étape courante dans le cas d’un formulaire multiétape.
2. $erreurs (array), liste des erreurs existantes.

Le cas échéant, le tableau $erreurs doit être complété : les clés de ce tableau correspondent aux champs en erreurs, tandis que les valeurs correspondent aux messages d’erreurs. La clé message_erreur contient le message d’erreur général. Il est recommandé de la laisser telle quelle.

À noter que cette fonction est appelée après que les vérifications individuelles de chaque saisie aient été effectuées.

Les erreurs générées lors de la vérification sont différentes des erreurs générées lors du traitement. Les premières sont liées à ce que l’internaute a rempli (non respect des conditions de remplissage) les secondes sont “techniques” (par exemple impossibilité technique d’envoyer un email).

La fonction traiter_<nom>_instituer_reponse()

Cette fonction est appelée automatiquement lorsqu’une réponse est instituée, c’est-à-dire que son statut est modifié. Elle reçoit deux arguments :

• $flux (array) correspondant au $flux passer au pipeline de SPIP post_edition. L’entrée $args de ce flux est toutefois complété par :
  • id_formulaire (int) identifiant numérique du formulaire
  • formulaire (array) description complète du formulaire (ligne dans la table spip_formulaires)
  • saisies (array) description complète des saisies du formulaire
  • traitements (array) description des traitements associés au formulaire
• $options (array) options du traitement courant

La fonction doit effectuer les actions nécessaires, puis retourner $flux après l’avoir éventuellement modifié.

Par exemple le traitement email dispose d’une telle fonction pour envoyer un email à la validation d’une réponse, si le traitement est configuré pour cela.

La fonction traiter_<nom>_post_config()

Permet d’exécuter du code juste après que la configuration du traitement ait été effectué en base. Elle reçoit deux arguments :

• $id_formulaire (int) identifiant du formulaire concerné ;
• $config (array) configuration du traitement concerné.

Par exemple le traitement enregistrement dispose d’une telle fonction pour ajuster la date d’expiration du formulaire lorsque les réponses sont supprimées à une date précise.

Ordre des traitements

Par défaut, les traitements sont listés dans le formulaire de configuration et exécutés selon l’ordre alphabétique de leurs noms. Toutefois, formidable s’occupe automatiquement de passer les traitements qui utilisent ou nécessitent un autrement après celui-ci.

Pipeline formidable_traitements

Le pipeline formidable_traitements permet de modifier les traitements. Il reçoit un tableau dont la clé data contient la description des traitements. Il est possible de manipuler cette clé data pour :

• supprimer un traitement
• modifier les options proposées pour un traitement
• modifier l’ordre des traitements, par exemple en ajoutant une utilisation

Par exemple, un plugin qui proposerait un traitement « établir une facture » pourrait vouloir que l’établissement de la facture ait lieu AVANT l’envoi de l’email. Il modifiera donc le traitement email pour ajouter un utilise.

/**
 * Ajouter `facture` comme `utilise`  pour le traitement `email`
 *
 * @pipeline formidable_traitements
 * @param array $flux
 * @return array $flux
 **/
function formidable_formidable_traitements($flux) {
	if (isset($flux['data']['email'])) {
               $flux['data']['email']['utilise'][] = 'facture';
	}
	return $flux;
}