Carnet Wiki

PointsEntreeIncTexte

Le fichier inc_texte.php3 fournit tous les outils pour convertir les raccourcis typographique et autres choses que l’utilisateur pourrait entrer dans les champs texte. Il existe deux fonctions majeures propre et typo pour faire cela.

Avant la version 1.7.2, il fallait mettre les mains dans le cambouis pour ajouter ses propres raccourcis. Mais depuis, il existe 4 points d’entrée dans le traitement qui permettent de ne pas avoir à toucher au noyau SPIP pour avoir ses propres raccourcis.

La fonction propre

Le filtre applique 3 fonctions à la suite sur le texte qui lui est passé :
-  trim qui est une fonction de base php qui enlève les espaces en trop du texte,
-  traiter_raccourcis qui transforme les raccourcis SPIP en code HTML,
-  interdire_scripts qui empêche l’ajout de scripts malicieux dans les textes.

En résumé, elle fait le gros travail de traduction des raccourcis.

La fonction typo

La fonction typo fait un traitement (en plus de propre) un peu plus fin pour que les textes affichés suivent les règles de typographie (e.g : mettre une espace après «  : », etc.).

/ ! Le texte passant à travers la typo passe aussi à travers propre.

Les points d’entrée

La syntaxe des points d’entrée comprend :

  • le $texte à modifier et retourner
  • $ref passage par argument du tableau &$les_echap (si on veut les filtrer eux aussi ; pas conseillé !) On peut aussi y ajouter les parties que l’on veut y échapper.

Quatre fonctions sont implémentables :
-  avant_typo sera appliquée avant l’appel à typo. On doit y faire les traitements des raccourcis qui seront cassés par la fonction typo ou la fonction propre.
-  avant_propre sera appliquée avant l’appel à propre. On doit y faire tous les traitements qui pourraient être sensibles à l’application de propre.
-  apres_propre sera appliquée après la fonction propre. On peut y faire les traitements qui ont besoin ou ne sont pas sensibles aux transformations faites par propre. On doit aussi y remettre en place ce que l’on a échappé dans avant_propre
-  apres_typo sera appliquée après la fonction typo. L’idée est la même qu’avant.

Notez bien que les traitements faits après les fonctions typo ou propre ne seront plus transformés par celles ci. Il ne faut donc pas essayer d’insérer automatiquement des raccourcis SPIP ou du texte qui aurait besoin d’être traité par SPIP.

Voir aussi ce message.

Subtilités

1- Depuis le début on parle de parties échappées. Mais qu’est ce que cela veut dire ? Quand on ajoute un raccourci, on peut vouloir éviter que le texte à l’intérieur du raccourci soit traité par propre.

Par exemple, si on ajoute un nouveau bloc <machin> où un texte encadré de {} n’est pas un texte en italique mais un texte à mettre en rouge, alors on ne veut pas que propre remplace ce raccourci par le code html pour l’italique.

La méthode est d’enlever (échapper) cette partie du texte avant de le passer dans propre. Donc, dans avant_propre, on remplace le texte par quelque chose qui ne sera pas traité par propre et que l’on pourra retrouver dans apres_propre pour y replacer la partie traitée par notre plugin.

En pratique, on utilise une expression régulière pour remplacer le texte compris entre notre raccourcis par une chaîne contenant un numéro : @@MOI_MACHIN_10@@. Ce numéro sera l’index dans un tableau, disponible dans apres_propre, de la partie du texte que l’on doit replacer là.

Voici un code d’exemple, qui échappe le code entre balise <machin> :

function avant_propre($texte) {
   global $code_echapper;

   $regexp_echap = "(<machin>(([^<]|<[^/]|</[^m]|</m[^a]|</ma[^c]|</mac[^h]|</mach[^i]|machi[^n]|</machin[^>])*)</machin>)";

   $code_ech=0;
   while (preg_match($regexp_echap, $texte, $regs)) {
 	$code_echapper[$code_ech] = $regs[1];		
        $pos = strpos($texte, $regs[0]);
	$texte = substr($texte,0,$pos)."<@@MOI_MACHIN_$code_ech@@>".substr($texte,$pos+strlen($regs[0]));
	$code_ech++;
	}

	return $texte;
}

et voici le code qui les replace dans apres_propre :

function apres_propre($texte) {
   global $code_echapper;

	while (ereg('<@@MOI_MACHIN_([0-9]+)@@>', $texte, $regs)) {
		$lenum = $regs[2];
        $lecode = mon_traitement($code_echapper[$lenum],$regs[1]);

		$pos = strpos($texte, $regs[0]);

		$texte = substr($texte, 0, $pos). "<div class='machin'>". $lecode ."</div>". substr($texte, $pos + strlen($regs[0]));
   }

    //il faut faire attention de ne pas avoir cassé les échappements spip, par exemple, ici on s'assure que le script de remplacement n'ait pas remplacé < par &lt; et > par &gt;
	$find = "/&lt;@@SPIP_(SOURCEPROPRE|SOURCETYPO)([0-9]+)@@&gt;/";
	$replace = "<@@SPIP_12@@>";
	$texte = preg_replace($find,$replace,$texte);

	return $texte;
}

2- parfois, on fait appel à des scripts inclus, il faut alors bien penser que ces fonctions seront appelées depuis la racine du site ou l’espace d’admin (./ecrire). Donc si vous utilisez des chemins relatifs, il est possible d’utiliser la variable globale : $flag_ecrire pour savoir dans quelle partie on se trouve.
3- si on veut connaître la langue dans laquelle on est en train de naviguer, on peut accéder à la variable globale $spip_lang

Exemples

<?php

function avant_propre ($texte, $ref=false) {
    $texte = smileys($texte);
    return $texte;
}

?>

Observations supplémentaires de kouki

  • Ces fonctions sont appelées dans l’ordre suivant :
    1. avant_propre
    2. avant_typo
    3. apres_typo
    4. apres_propre
  • Seules les fonctions de typographie sont appelées pour les titres, cela implique que les balises gras ne sont pas traitées pour un titre (leur traitement se fait dans propre)
  • Les fonctions propre et typographie sont appelées sur l’ensemble du contenu d’un article, sur le post-scriptum et les notes ainsi que sur le texte explicatif d’une rubrique dans l’odre indiqué plus haut
  • Les fonctions de typographie semblent être appelées une nouvelle fois pour les types de lien excepté pour les liens des notes
  • pour les plugins (à partir de SPIP 1.9), on peut aussi personnaliser ces traitements via les pipelines pre_propre, post_propre et pre_typo et post_typo

sur spip-contrib :

-  Nouveaux raccourcis typographiques et antispam générique
-  Du joli code dans les articles
-  Génération automatique de numérotation, table des matières et références

- Mise à jour :25 novembre 2009 à 14h08min