Un formulaire C.V.T avec Saisies par l’exemple

This is an « educational contribution » which shows, with concrete example, how to develop a new functionality for SPIP.

Réalisation d’un formulaire SPIP type CVT avec le plugin Saisies

Pré-requis :

Réalisé avec SPIP 2.1.2 et les plugins suivants :

  • Saisies : Version : 1.8.12 [42956]
  • Bonux : Version : 2.2.14 [42736]
  • Verifier : Version : 0.1.6 [42959]
  • Yaml : Version : 1.4.1 [42112]

Avertissements

Cet article est

  • un «retour d’expérience» sur l’utilisation du plugin Saisies pour la mise en place d’un formulaire;
  • un partage de réponses aux questions qui se sont posées à moi lors de ma découverte du plugin.

Cet article n’est pas

  • exhaustif : les descriptions qui suivent partent seulement d’un point de vue particulier (un des intérêts de Saisies étant sa pluralité d’approche en terme de développement);
  • une documentation développeur.

Le formulaire

Pour cet exemple, le formulaire à réaliser contient 4 champs et 1 fieldset :

  • Fieldset Le film :
    • titre,
    • année,
    • genre
  • Avis : c’est bien ?

Comme tous les formulaires C.V.T, créer un couple de fichiers HTML/PHP dans le dossier squelettes/formulaires :

  • film.html qui accueillera les balises gérées par SPIP et Saisies
  • film.php où sera paramétré le formulaire avec les fonctions C, V et T

Première étape : déclarer ces champs comme des saisies à l’aide d’un tableau PHP [1], dans film.php :

$mes_saisies = array(
  array( // le fieldset 
    'saisie' => 'fieldset',
    'options' => array(
      'nom' => 'le_film',
      'label' => 'Le film'
    ),
    'saisies' => array( // les champs dans le fieldset 
      array( // champ titre : ligne de texte
          'saisie' => 'input',
          'options' => array(
            'nom' => 'titre',
            'label' => 'Son titre',
            'obligatoire' => 'oui'
          )
      ),
      array( // champ annee : 4 chiffres
          'saisie' => 'input',
          'options' => array(
            'nom' => 'annee',
            'label' => 'Année de réalisation',
            'size' => 4,
            'maxlength' => 4
          )
      ),
      array( // champ genre : liste déroulante
        'saisie' => 'selection',
        'options' => array(
          'nom' => 'genre',
          'label' => 'Son genre',
          'datas' => array(  // apparté : penser à ranger les choix par ordre alphabétique (ou numérique), c'est plus facile à trouver pour ceux qui utilisent le formulaire
            'animation' => 'Animation',
            'comedie' => 'Comédie',
            'docu' => 'Documentaire',
            'drame' => 'Drame',
            'sf' => 'Science-fiction'
          )
        )
      ),
    )
  ),
  array( // hors fieldset : avis 
    'saisie' => 'radio',
    'options' => array(
      'nom' => 'c_bien',
      'label' => 'C\'est bien ?',
      'data' => array(
         'oui' =>'Oui c\'est bien',
        'non' =>'Non ce n\'est pas bien'
       )
    )
  ),
);

Tous les éléments de saisie du formulaire sont définis. Il reste cependant le bouton d’envoi du formulaire (submit) à créer.

Ici (et à l’heure actuelle), deux possibilités :

  1. écrire le bouton en HTML dans film.html :
    <input type="submit" value="envoyer" />
  2. créer son propre type de saisie pour cet élément

Créer son propre type de saisie

Créer un sous-répertoire saisies dans /squelettes, y placer un nouveau fichier qui prendra pour nom le type de la saisie : mon_submit.html et y écrire le code HTML/SPIP du bouton :

[(#REM)   
  Parametres :
  -* nom (obligatoire) : attributs name et id du bouton
  -* texte (optionnel) : attribut value, par défaut Envoyer
  -* class (optionnel) : attribut class, par défaut submit
 
  Exemple d'appel :
	[(#SAISIE{mon_submit, envoyer,
    texte=Ok
	})]
][
<input type="submit" name="(#ENV{nom})" class="#ENV{class, submit}" id="bouton_#ENV{nom}" value="#ENV{texte,Envoyer}" />]

(prendre pour exemple un des fichiers de saisie du plugin dans /plugins/saisies/saisies/)

Ajouter la déclaration du bouton à la fin du tableau $mes_saisies (l’ordre de déclaration définit l’ordre d’affichage):

array(
  'saisie' => 'mon_submit',
  'options' => array (
    'nom' => 'envoyer',
    'texte' => 'Ok'
  )
)

Générer et Charger le formulaire

Les saisies sont prêtes, on peut les appeler avec #GENERER_SAISIES{#ENV{mes_saisies}} dans film.html

Cette balise ne produit que les éléments contenus dans le formulaire. Il reste donc un peu de travail pour terminer ce formulaire :

[<p class="reponse_formulaire reponse_formulaire_ok">(#ENV**{message_ok})</p>]
[<p class="reponse_formulaire reponse_formulaire_erreur">(#ENV**{message_erreur})</p>]
 
[(#EDITABLE|oui) 
  <form id="film_form" name="film_form" action="#ENV{action}" method="post">
    #ACTION_FORMULAIRE{#ENV{action}}
    <ul>
      #GENERER_SAISIES{#ENV{mes_saisies}}
    </ul>
  </form>]

Maintenant, le formulaire peut être appelé avec la balise #FORMULAIRE_FILM dans un squelette ou avec le raccourci typographique <formulaire|film> à l’intérieur d’un article par exemple.

En prenant ce dernier exemple et en affichant l’article dans la partie publique, rien ne se passe ...c’est normal.

#ENV{mes_saisies} «n’existe pas» encore dans le contexte de la page affichée. Pour ce faire, il faut d’abord mettre en œuvre les fonctions C, V et T qui vont gérer toutes les variables :

  1. Charger les données de Saisies et les champs à manipuler par ces fonctions
  2. Vérifier les valeurs envoyées par le formulaire
  3. Traiter ces données vérifiées
  4. Ainsi qu’une fonction qui permettra d’envoyer à ce trio la structure des saisies (tableau $mes_saisies). Appelons-la mes_saisies_film().
function mes_saisies_film() {
  $mes_saisies = array (
    ...
  );
  return $mes_saisies;
}
 
function formulaires_film_charger_dist() {
// on charge les saisies et les champs qui nécessitent un accès par les fonctions
  $valeurs = array(
    'titre' => '',
    'genre' => '',
    'annee' => '',
    'c_bien' => '',
    'mes_saisies' => mes_saisies_film()
  );
  return $valeurs;
}

En recalculant l’article contenant le formulaire, il doit maintenant s’afficher.

Vérifier les saisies

Le plugin Verifier entre en scène. Saisies utilise un pipeline pour s’y «brancher». Il est toutefois nécessaire de déclarer dans la structure des saisies les vérifications souhaitées : ajouter un tableau verifier dans le tableau de la saisie à... vérifier.

Ici, le champ annee doit être un nombre (type entier) compris entre 1895 et l’année en cours + 1 (on pourrait anticiper une sortie) :

$mes_saisies = array(
    ...
      array(
        'saisie' => 'input',
        'options' => array(
          'nom' => 'annee',
          'label' => 'Année de réalisation',
          'size' => 4,
          'maxlength' => 4
        ),
        'verifier' => array(
          'type' => 'entier',
          'options' => array (min => 1895, max => (date('Y')+1))
        )
      ),
    ...
  );

Le tableau verifier peut prendre plusieurs options, selon son type
 [2]. Se reporter aux fichiers de vérification du plugin dans /plugins/verifier/verifier/.

Il suffit ensuite de compléter la fonction formulaires_film_verifier dans film.php :

function formulaires_film_verifier_dist() {
 
  // on va chercher le pipeline saisies_verifier() dans son fichier
  include_spip('inc/saisies');
 
  // on charge les saisies
  $mes_saisies = mes_saisies_film();
 
  // saisies_verifier retourne un tableau des erreurs s'il y en a, sinon traiter() prend le relais
  return saisies_verifier($mes_saisies);
}

Traiter le formulaire

La fonction «T» dans film.php est appelée après la fonction «V», si celle-ci ne retourne pas d’erreurs.

function formulaires_film_traiter_dist() {
  // on charge les saisies, si besoin
  $mes_saisies = mes_saisies_film();
 
  // Traitement des données reçues du formulaire, 
  // par mail par ex ou insertion dans une base
    ...
 
  // S'il y a des erreurs, elles sont retournées au formulaire
  return array('message_erreur'=>'Le film n\'a pas été enregistré');
 
  // Sinon, le message de confirmation est envoyé
  return array('message_ok'=>'Le film a été enregistré');
}

Footnotes

[1Voir la documentation de Saisies

[2Les types de vérification fournies par le plugin Verifier :

  • code_postal : code postal français, composé de 5 chiffres
  • date : date au format JJ/MM/AAAA (avec séparateurs souples : espace / - .)
  • decimal : un entier cohérent peut être extrait de la valeur
  • email : validité d’une adresse de courriel
  • entier : un entier cohérent peut être extrait de la valeur
  • id_document : la valeur correspond à un id_document valide
  • regex : une valeur suivant une expression régulière.
  • siren_siret : SIREN (9 caractères) ou SIRET (14 caractères)
  • taille : taille minimale/maximale, pour un mot de passe par exemple
  • telephone : numéro de téléphone. Pour l’instant seulement avec le schéma français.
  • url : URL format web

Références des vérifications

updated on 19 May 2020

Discussion

11 discussions

Ajouter un commentaire

Who are you?
[Log in]

To show your avatar with your message, register it first on gravatar.com (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom