API CFG : Extensions et points d’entrées

Une grande réécriture du code a été faite entre les versions 1.4 et 1.7 de CFG afin de lui permettre d’être étendu assez facilement, complété par 1.10.2.

Il y a essentiellement 4 types d’extensions :
-  créer un dépôt,
Ou en utilisant les points d’entrées de CFG :
-  créer un type de validation pour un champ de formulaire,
-  créer une action sur un champ de formulaire,
-  créer une action sur un paramètre de formulaire,

Créer un dépot

Les dépôts sont les méthodes de stockage des informations passées à CFG. Pour utiliser un dépôt dans un formulaire, il faut passer le paramètre <!-- depot=nom_du_depot -->. Les dépôts fournis avec CFG sont « meta », « metapack », « tablepack », « table » et « php ».

Ils peuvent être appelés aussi avec la balise #CONFIG et les fonctions lire_config(), ecrire_config() et effacer_config(), par exemple comme ceci : #CONFIG{php::nom/champ}

Le code des dépots se situent dans le dossier cfg/depots/xxx.php. Ils se composent d’une classe cfg_depot_xxx et d’au moins 5 fonctions :
-  cfg_depot_xxx($params=array()), constructeur de la classe,
-  lire(),
-  ecrire(),
-  effacer(),
-  et charger_args($args) qui détermine la manière dont sont traités les arguments passés à la balise #CONFIG ou aux fonctions lire_config(), ecrire_config() et effacer_config()

Pour ajouter un nouveau dépôt, il suffit de créer un nouveau fichier php dans ce dossier (ou dans la même arborescence dans un autre plugin).

Les points d’entrées

CFG dispose maintenant de points d’entrées, qui peuvent être utilisés pour les 3 extensions décrites ensuites. Actuellement, les actions possibles sont :
-  pre_charger : avant la lecture du dépôt
-  charger : après la lecture du dépôt
-  pre_verifier : après validation du formulaire, mais avant de récupérer les valeurs postées
-  verifier : après la récupération des valeurs postées
-  pre_traiter : si la vérification était OK, avant le traitement (écriture ou effacement dans le dépôt)
-  post_traiter : après le traitement dans le dépôt.

Un formulaire peut utiliser ces points d’entrées pour effectuer des opérations qui lui sont propres, comme des post traitements. Il lui suffit de déclarer alors la fonction : function cfg_toto_post_traiter(&$cfg){ ... }, par exemple dans le fichier fond/cfg_toto_fonctions.php si le formulaire est fond/cfg_toto.html.

Le cas de la validation est particulier car les messages d’erreurs doivent être placés au bon endroit. Avant CFG 1.10.2, la fonction verifier retournait le tableau d’erreurs, elle doit maintenant utiliser la fonction ajouter_erreurs() de préférence. Voir ci-dessous.

Types de validations

Il y a 2 façons de vérifier les données d’un formulaire CFG.

Vérifier tous les champs d’un coup

La première est de faire, un peu comme la nouvelle API sur les formulaires dynamiques de SPIP (version de développement), une fonction qui analyse les valeurs postées et renseigne un tableau d’erreur.

Prenons l’exemple d’un formulaire fonds/cfg_toto.html contenant un champs <input type="text" name="annee" />. Il est possible de créer un fichier fonds/cfg_toto_fonctions.php contenant :

<?php
function cfg_toto_verifier(&$cfg){
  $err = array();
  if ($cfg->val['annee']<2000) {
    $err['annee'] = "Soyez au XXI siècle !";
  }
  // ou encore
  // $err['message_erreur'] = "Le champ date est invalide";

  return $cfg->ajouter_erreurs($err);
  // return $err; // ancienne ecriture
}
?>

Si $err n’est pas vide, la vérification échoue et le traitement du formulaire ne se fait pas.

Vérifier selon un type de champ

La seconde façon est de vérifier un champ en le déclarant d’un certain type. Cela se traduit en CFG en passant une classe css « type_yy » au champ en question. Attention, l’attribut class doit suivre l’attribut name. Par exemple : <input type="password" name="mon_passe" class="type_pwd" /> indique que ce champ est de type « pwd », ce qui entraine la lecture, par CFG des points d’entrées proposés dans le fichier cfg/classes/type_pwd.php. Il y a actuellement dans ce fichier :

function cfg_verifier_type_pwd($champ, &$cfg) {
	if (strlen($cfg->val[$champ]) < 5){
		$cfg->ajouter_erreur($champ, _T('cfg:erreur_type_pwd', array('champ'=>$champ)));
	}
	return true;
}

Le point d’entrée utilisé est « verifier », et 2 paramètres sont passés : le nom du champ et l’instance de la classe cfg_formulaire.
 [1] Une fonction ajouter_erreur($champ, $message) permet d’ajouter un message ($message) d’erreur sur le champ nommé (attribut name) $champ.

Pour créer un nouveau type de champ, il suffit de créer un fichier cfg/classes/type_yy.php contenant des fonctions cfg_action_quoi().

Action sur un champ de formulaire

Il est possible de réaliser des actions plus complexes que les verifications (type_yy) en utilisant une classe css « cfg_yy ». Au lieu de passer $nom et $val comme dans les types, se sont $nom et la classe php CFG qui sont transmises, ce qui permet de réaliser nombre d’action.

En voici une très simple, du fichier cfg/classes/cfg_couleur.php, qui revient à mettre automatiquement dans un formulaire CFG le paramètre <!-- selecteur_couleur=1 --> si au moins un champ possède la classe « cfg_couleur » :

function cfg_charger_cfg_couleur($nom, &$cfg){

	$cfg->param['selecteur_couleur'] = 1;
	$cfg->ajouter_extension_parametre('selecteur_couleur');
	    
	return $cfg;
}

Action sur un paramètre de formulaire

Comme les 2 extensions précédentes, il est possible d’indiquer des actions à réaliser en fonction de paramètres donnés dans le formulaire, sous 2 conditions : que le paramètre soit non vide et qu’un fichier cfg/params/mon_parametre.php existe.

Ces actions sont faites juste après les actions proposées par les classes css. 2 arguments sont passés aux fonctions : $valeur est la valeur du paramètre, et &$cfg est la classe php de CFG.

Voici par exemple une partie de ce que le paramètre « selecteur_couleur » effectue : mettre dans le head html les scripts javascripts nécessaires à son fonctionnement :

function cfg_charger_param_selecteur_couleur($valeur, &$cfg){
	// si la librairie farbtastic est installee,
	// on la charge dans le header prive
	$dir_lib = _DIR_LIB . 'farbtastic12/farbtastic/';
	if (file_exists($lib = $dir_lib.'farbtastic.js')) {
		$cfg->param['head'] .= "\n<script langage='javascript' src='$lib'></script>\n";
		// .....
	}
}

Notes

[1Avant CFG 1.10.2, l’api était différente et ne recevait que le nom du champs et sa valeur. Le changement permet d’homogénéiser (et permettre d’autres actions)

Discussion

3 discussions

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