Utilisation et validation des crayons de Inscription2

Ceci est une « contribution pédagogique », qui montre par l’exemple comment développer une nouvelle fonctionnalité pour SPIP.

Cet article ne concerne que la version du plugin inscription2 compatible avec SPIP 2.0 récupérable sur SPIP-ZONE. Il fait partie d’une série d’articles documentaires du plugin inscription2.

Dans un autre article nous avons vu que le profil est accessible en modification de deux manière différentes : l’utilisation du formulaire d’inscription en lui passant un id_auteur défini ou via les crayons.

Dans le cas de l’utilisation des crayons, il est nécessaire de vérifier la validité des entrées afin d’avoir des profils d’utilisateurs avec le moins d’erreurs possibles.

Inscription2 propose des contrôleurs et vues spécifiques aux champs du plugin. Cet article permet de les expliciter et également de donner la marche à suivre afin de créer ses propres crayons...

Pour de plus amples informations sur les contrôleurs et les vues des crayons, voir la documentation officielle

Tout d’abord, l’architecture XHTML des crayons spécifiques au plugin inscription2 respecte au maximum la nomenclature des formulaires décidée par l’équipe de spip lors de la sortie de la version 2.0. Ainsi chaque crayon est constitué comme ceci :

<fieldset>
	<legend>titre</legend>
	<ul>
		<li>
			<label>Label de l'input</label>
			<input type="text" class="crayon-active text" name="name_input" value="valeur_input" />
		</li>]
	</ul>
</fieldset>

Il est à noter que les crayons entourent le contenu du contrôleur dans un formulaire avec la class formulaire_crayon dans une div de class formulaire_spip.

Cette méthode permet, dans un site en production, que les crayons ressemblent plus ou moins aux autres formulaires du site. Étant donné que ces crayons sont destinés à tout utilisateur du site (du visiteur au webmestre) il semble qu’il soit important que les utilisateurs comprennent visuellement ce qu’ils font et donc reconnaissent facilement qu’ils ont ouvert un formulaire.

Les contrôleurs / vues spécifiques à inscription2

Les contrôleurs spécifiques aux champs du plugins sont les suivants :

  • adresse : modifie et vérifie une adresse (chaîne de 5 caractères où plus de lettres et de nombres) ;
  • adresse_pro : modifie et vérifie l’adresse (voir ci-dessus) ;
  • code_postal : modifie et vérifie le code postal en fonction d’un masque qui devrait éviter des dérives mais n’assure pas forcément un vrai code postal car il est impossible de prévoir le pays de l’utilisateur (autorise cependant les notations du genre F-XXXXX et XXXXX par exemple) ;
  • code_postal_pro : modifie et vérifie le code postal professionnel (idem au code postal normal) ;
  • ville : modifie et vérifie la ville (chaîne de 2 caractères ou plus uniquement composée de lettres) ;
  • ville_pro : modifie et vérifie la ville professionnelle (idem ci-dessus) ;
  • pays : modifie le pays, il affiche le sélecteur de pays ;
  • pays_pro : modifie le pays professionnel (idem ci-dessus) ;
  • fax : modifie et vérifie la validité d’un numéro de téléphone (comme le code postal, cela permet d’éviter les dérives mais ne peut forcer une réelle validation dépendante du pays). On autorise les notations internationnales du type +33 X XX XX XX XX ou nationales XX XX XX XX XX ;
  • fax_pro : modifie et vérifie le fax professionnel (idem ci-dessus) ;
  • mobile : modifie et vérifie le numéro de mobile (idem ci-dessus) ;
  • mobile_pro : modifie et vérifie le numéro de mobile professionnel (idem ci-dessus) ;
  • telephone : modifie et vérifie le numéro de téléphone (idem ci-dessus)
  • telephone_pro : modifie et vérifie le numéro de téléphone professionnel (idem ci-dessus) ;

Les contrôleurs ci-dessus décrivent des contrôleurs pour champs uniques, le plugin met également à disposition plusieurs contrôleurs permettant de modifier plusieurs champs d’un seul coup, utile lorsqu’on a besoin d’un profil très complet (site de vente, d’associations ...) :

  • adressecomplete et adressecompletepro : modifient et valident les adresses normales et professionnelles complètes (les 4 champs adresse, code postal, ville et pays) ;
  • telfax et telfaxpro : modifient et valident les 3 types de numéros de téléphone possibles (fax, mobile et téléphone) ;

Reportez vous aux modèles de modification de profil du plugin pour voir comment insérer ces contrôleurs dans votre site.

La vérification et validation des crayons

Le fonctionnement de ces crayons spécifiques est assez simple, à leur ouverture, ils vérifient la validité du contenu du ou des champs, l’opération est refaite à chaque fois que l’utilisateur ajoute ou supprime un caractère des champs (évènement javascript « keyup »). Si le contenu est valide, le crayon est normal, dans le cas où le contenu des champs est invalide, un message d’erreur est affiché à l’utilisateur et le bouton de validation du crayons est caché, l’utilisateur n’a plus la possibilité de valider son texte.

Avant la validation du crayon, les valeurs sont vérifiées afin de ne valider que des valeurs « raisonnables ». On utilise pour ce faire le plugin jQuery validation de Jörn Zaefferer.

Si le champs est spécifié comme obligatoire dans la configuration du plugin, cette option est prise en compte et il ne sera pas possible de valider un contrôleur vide.

Le plugin se base sur des méthodes ajoutées au plugin validation de jQuery, en plus de celles définies par défaut, afin de valider certains types de champs. Les méthodes en question sont des expressions régulières de validation des inputs et textareas, leur associant un message d’erreur en cas de non validité. Le plugin en compte quatre différentes :

  • chainenombre : qui vérifie que le contenu de l’input ou du textarea est une chaîne composée de chiffres et de lettres (utilisée dans le contrôleur d’adresse notemment) ;
  • chaine : qui vérifie que le contenu n’est composé que de lettres ;
  • postal : qui vérifie que le contenu est un code postal possible ;
  • numero : qui vérifie que le contenu est un numero de téléphone potentiel ;

Ces méthodes sont disponibles dans le fichier i2_validation_method.js.html à la racine du plugin.

Le plugin définit également quatre addClassRules pour le même plugin jQuery qui permet d’associer des méthodes de validation à des champs en se basant sur une class CSS associée à l’input ou au textarea en question. Ces class utilisables sont : « obligatoire » (pour les champs obligatoires), « adresse » (pour les champs de type adresse), « numero » pour les champs de type numéro de téléphone et « cp » pour des champs de type code postal. Ces « addClassRules » associent donc à des class CSS une ou plusieurs méthode de validation par exemple :

  • « required » (disponible par défaut dans le plugin) uniquement pour les champs avec la class obligatoire ;
  • « numero » (décrite dans le plugin inscription2) et « rangelength » (disponible par défaut dans le plugin jQuery) pour les numéros de téléphone ;

Ces associations sont également visibles dans le fichier i2_validation_method.js.html à la racine du plugin.

Ces « méthodes » et « addCassRules » sont extensibles facilement par tout développeur de sous plugin pour inscription2. Cette partie sera explicitée dans un autre article.

Créer ses propres crayons pour inscription2

La meilleure manière est de prendre exemple sur les contrôleurs existants.

Pour des besoins spécifiques il se peut que vous souhaitiez créer vous-mêmes certains crayons spécifiques (nous allons prendre l’exemple de modification du champs adresse), pour ce faire il est nécessaire de créer un fichier du type :
squelettes/controleurs/adresse.html

Il doit contenir au préalable une boucle sur la table dont fait partie le ou les champs que l’on souhaite modifier, dans un cache réglé à 0, dans notre cas :

#CACHE{0}
<BOUCLE_a(AUTEURS_ELARGIS){id_auteur=#ENV{id_auteurs_elargi}}{tout}>
</BOUCLE_a>

Dans cette boucle nous ajoutons le contenu html basique de chaque crayons :

<fieldset[ style="(#ENV{style})"]>
	<legend><:inscription2:adresse:></legend>
	<ul>
		[(#CONFIG{inscription2/adresse_fiche_mod}|=={on}oui)
		[(#CONFIG{inscription2/adresse_obligatoire}|=={on}|oui)#SET{adresse_obl, true}]
		[(#GET{adresse_obl}|?{<li class="obligatoire">,<li>})]
			<label><:inscription2:adresse:></label>
			<textarea class="crayon-active text adresse[(#GET{adresse_obl}|oui) obligatoire]" name="#ENV{name_adresse}" style="width:#ENV{largeur}px;">[(#ADRESSE**|entites_html)]</textarea>
		</li>]
	</ul>
</fieldset>

Explicitons un peu son contenu en prenant chaque balise une à une :

  • #ENV{style} : : cette balise est calculée automatiquement par le plugin « crayons » ;
  • [(#CONFIG{inscription2/adresse_fiche_mod}|=={on}oui) : on vérifie si le champs en question est bien activé, devrait toujours retourner vrai si le squelette est correctement fait ;
  • [(#CONFIG{inscription2/adresse_obligatoire}|=={on}|oui)#SET{adresse_obl, true}] : on vérifie si le champ est obligatoire, s’il l’est on position à true la variable « adresse_obl » ;
  • [(#GET{adresse_obl}|?{<li class="obligatoire">,<li>})] : on vérifie la variable « adresse_obl », si elle vaut « true » on crée le li parent du champs à modifier avec la class « obligatoire » sinon on ne lui met pas de class spécifique ;
  • #ENV{name_adresse} : cette balise est envoyée par crayons, il est important de mettre « name_nom_de_votre_controleur » ;
  • #ENV{largeur} est également envoyée par le plugin crayons ;
  • [(#ADRESSE**|entites_html)] : correspond à la valeur de la balise de la boucle parente à afficher (l’écriture de la sorte évite tout type d’erreurs) ;

Voilà, l’écriture diffère un peu d’un crayon habituel mais elle correspond à la meilleure que l’on ait trouvée pour ce plugin.

Si vous souhaitez ajouter une validation à votre contrôleur

Dans un premier temps juste en dessous de la ligne de la boucle (avant le html), ajoutez la ligne suivante :

[<script type="text/javascript" src="(#URL_PAGE{crayons_validation.js}|parametre_url{lang,#ENV{lang}})"></script>]

Cette ligne permet d’insérer les librairies javascript nécessaires à la validation javascript.

La fonction de base de validation à ajouter juste en dessous est la suivante (elle est documentée au maximum pour expliquer ce qu’elle fait, certaines parties sont à modifier en fonction du nom du contrôleur utilisé) :

<script type="text/javascript">
	// On test si le js est bien chargé, sinon on ne fait rien
	if (typeof cQuery.fn.validate == "function") {
		// On récupère l'objet du dom créé par crayons
		// Ici vous devez renommer "adresse" par le nom de votre contrôleur
		var me = cQuery(".auteurs_elargi-adresse-#ID_AUTEUR");
		// On récupère un objet javascript correspondant au formulaire à valider
		var id = me.crayon().find('form');

		// La fonction de validation en tant que telle
		function validation(){
			// On doit répéter cette opération si le controleur accepete la barre typo
			var me = cQuery(".auteurs_elargi-adresse_pro-#ID_AUTEUR");
			var id = me.crayon().find('form');
			var validator = cQuery(id).validate({
				onkeyup: function(){
					validation();
				},
				showErrors: function(errors, errorList){
					validator.defaultShowErrors();
					crayon_affiche_submit(me, id);
				},
				success: function(label){
					label.parents('li.erreur').removeClass('erreur');
					label.remove();
					crayon_affiche_submit(me, id)
				}
			});
			//On test le formulaire pour chercher les potentielles erreurs
			validator.form();
			// On affiche /cache le bouton de submit en cas d'erreur
			crayon_affiche_submit(me, id);
		}
		//On ajoute l'asterisque qui signale qu'un champ est obligatoire
		id.find('.obligatoire label').not('.error').append('*');
		//On lance la fonction validation() au bout de 500 ms
		setTimeout('validation()', 500);
	}
</script>

Voilà avec cela nous avons l’ensemble du contrôleur « adresse ».

Si vous estimez que certains contrôleurs ou certaines méthodes de validation manquent, ou qu’ils devraient être modifiés pour correspondre à un usage par défaut du plugin (pas un cas particulier correspondant à vos besoins personnels), n’hésitez pas à le modifier sur la zone ou ajouter des correctifs dans le forum ci-dessous.

Discussion

Une discussion

  • texaverie

    bonjour,

    dans le cadre du plugin association2 pour spip2.1.2 , on ne voit nulle part la possibilité de donner un statut interne ni à un nouveau visiteur, ni de modifier un visiteur en prospect par exemple

    est-ce un correctif à faire ou une manip que je n’ai pas trouvé ?

    Répondre à ce message

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom