WikiRenderer

english

Utilisation de Wikirenderer 2.0

La version 2.0 est obsolète et n'est plus maintenue..

Dernière mise à jour le 16/05/2004

Simple

 include('WikiRenderer.lib.php');
 $wkr = new WikiRenderer();
 $monTexteXHTML = $wkr->render($monTexteWiki);

Modifier la configuration par défaut

Il suffit d'instancier l'objet WikiRendererConfig et de modifier ses propriétés :

 include('WikiRenderer.lib.php');

 $config = new WikiRendererConfig();

 // exemple de désactivation de l'interpretation des balises wiki pour les tableaux
 $config->bloctags['table']=false;

  // exemple de désactivation de l'interpretation des balises wiki pour les citations
 unset($config->inlinetags['cite']);

  // ajout de l'interpretation d'un smiley
 $config->simpletags[';-)']='<img src="smiley_clindoeil.png" alt=""/>';

 $wkr = new WikiRenderer($config);
 $monTexteXHTML = $wkr->render($monTexteWiki);

Connaître les erreurs

Il est possible de savoir si lors de la transformation, WikiRenderer a rencontré des erreurs (balises wikis malformée, imbriquée...). Il suffit, aprés la transformation, de regarder le contenu de la propriété errors. Exemple :

include('WikiRenderer.lib.php');
$wkr = new WikiRenderer();
$monTexteXHTML = $wkr->render($monTexteWiki);

if($wkr->errors){
   echo '<p style="color:red;">Il y a des erreurs wiki aux lignes : ';
   echo implode(',',array_keys($wkr->errors)),'</p>' ;
}

La propriété errors est un tableau d'élements dont la clé est un numéro de ligne, et la valeur le contenu de la ligne en question. On peut donc si on le désire, afficher aussi les lignes en erreur.

WikiRenderer ne s'arrete pas à la première erreur rencontrée. Les tags wiki qui posent problèmes ne sont pas interpretés, ni enlevés dans le texte résultat.

Les paramètres de configuration

Ils sont situés dans l'objet WikiRendererConfig

inlinetags
liste des tags wiki que l'on peut utiliser à l'intérieur les phrases. Voir la partie configuration avançée.
bloctags
liste des tags de type blocs disponible. La clé de chaque élement de la liste est le nom du bloc et la valeur, true ou false suivant si on active ou non la détection du bloc. Voir la partie configuration avançée.
simpletags
tags simples pour lesquels il y a juste un remplacement à faire. C'est donc un tableau PHP d'élements 'chaine à remplacer'=>'chaine remplacante'.
minHeaderLevel
Niveau minimal pour la génération des titres avec la balise <Hx>. Par exemple, si on met 3, !!! donnera <H3>, !! donnera <H4> et ! donnera <H5>.
headerOrder
indique le sens dans lequel il faut interpreter le nombre de signe de titre :
  • true : ! = titre , !! = sous titre, !!! = sous-sous-titre
  • false : !!! = titre , !! = sous titre, ! = sous-sous-titre
inlineTagSeparator
Séparateur des differents attributs des tags wiki. Par defaut : |
checkWikiWord
Indique si il faut détecter les mots wiki (un mot wiki est un mot commençant par une majuscule, et contenant au moins une deuxième majuscule à l'interieur du mot)
checkWikiWordFunction
Indique le nom de la fonction qui sera appelée si la détection des mots wiki est activé. Cette fonction devra recuperer en paramètre une liste de mots wiki, et devra renvoyé une liste des chaines qui remplaceront les mots wiki indiqués. Cette fonction est à implémenter par vous-même selon votre application. Voir la partie configuration avançée.
escapeSpecialChars (version >= 2.0.5)
Indique si il faut échapper (true) ou non les balises html incluses dans le texte wiki pour ne pas qu'elles soient interpretées par le navigateur. Par mesure de sécurité, toujours laisser à true sauf si vous vous faîtes une configuration pour transformer dans un format autre que XHTML/HTML.

Les tags wiki par défauts

de types bloc :

de type inline :

Note

Dans un texte wiki, on peut désactiver l'interpretation d'un tag wiki en mettant un antislash devant la balise d'ouverture (et de fermeture pour les tags en lignes). Exemple : \__emphase\__.

Configuration avançée

Si le balisage wiki proposée par défaut ne vous convient pas, il faut le redéfinir. Voici comment.

Principes

Il faut :

  1. créer un objet de configuration selon le modèle de WikiRendererConfig (ou surcharger WikiRendererConfig)
  2. Créer des nouveaux objets de type WikiRendererBloc pour les balises de type blocs et les indiquer dans votre objet de configuration
  3. Passer cet objet de configuration en paramètre au constructeur de WikiRenderer

Voir l'exemple avec le fichier WikiRenderer_w2x.conf.php, qui redefinit un balisage compatible avec wiki2xhtml : 


 include('WikiRenderer.lib.php');
 include('WikiRenderer_w2x.conf.php');

 $wkr = new WikiRenderer(new Wiki2XhtmlConfig());
 $monTexteXHTML = $wkr->render($monTexteWiki);

Modifier les tags wiki inlines

Les tags wiki inlines sont les tags que l'on utilise à l'interieur des textes : liens, emphases (gras, italique...), acronymes etc.. Ils sont définis dans la variable inlinetags de la classe de configuration WikiRendererConfig.

Les propriétés d'un tag wiki

inlinetags est un tableau d'élements définissant chaque tag wiki :

array(
  'nomtagwiki'=>array( propriétés du tag...),
  'nomtagwiki2'=>array( propriétés du tag...),
  ...);

Les propriétés du tag sont, dans l'ordre :

  1. symbole de début (chaîne);
  2. symbole de fin (chaîne);
  3. liste (tableau) des attributs xhtml (Si il n'y en a pas : null );
  4. nom d'une fonction à appeler pour générer la balise xhtml, pour les balises au fonctionnement complexe (si il n'y en a pas : null).

Génération du xhtml par défaut

Quand il n'y a pas de fonction indiquée pour générer la balise xhtml, WikiRenderer la générera automatiquement. Il prendra le nom du tag wiki comme nom de balise xhtml.

Définissons par exemple une balise wiki pour faire une emphase (balise html strong) avec pour délimiteurs __ : 

var $inlinetags= array(
   'strong' =>array('__','__', null,null),
   ...
   );

Si on écrit donc __mon emphase__, cela prendra strong comme nom de balise, et sera transformé alors en <strong>mon emphase</strong>.

On a vu que l'on pouvait indiquer une liste d'attributs xhtml dans les propriétés du tag. Dans ce cas, WikiRenderer récuperera chaque chaîne se trouvant entre le séparateur | (séparateur configurable) dans le tag wiki, et seront utilisées comme valeur aux attributs indiqués.

Par exemple, admettons que l'on définisse ceci :

var $inlinetags= array(
   'acronym'=>array('??','??', array('lang','title'),null),
   ...
   );

Si on écrit alors ??aaaa|bbbb|cccc?? :

Le code XHTML résultant sera donc <acronym lang="bbbb" title="cccc">aaaa</acronym>..

Utilisation d'une fonction génératrice spécifique

Quand la génération par défaut ne suffit pas, qu'il faille un traitement particulier, il faut alors indiquer une fonction de génération xhtml. Dans ce cas, le nom du tag importe peu, voir même la liste des attributs. Il faut juste que le nom soit différent des autres. Cette fonction devra accepter en paramètre deux tableaux :

  1. Liste des chaines trouvées entre le symbole de début et le symbole de fin;
  2. Liste des noms d'attributs de la propriété 3 du tag.

Par exemple, si les propriétés d'un tag sont :

var $inlinetags= array(
   'link'   =>array('[',']', array('href','lang','title'),'wikibuildlink'),
   ...
   );

Et si on écrit [aaaa|bbbb|cccc|dddd], la fonction wikibuildlink sera appelée avec les paramètres suivants :

La fonction devra retourner une chaîne contenant le code XHTML généré. Vous pouvez voir des exemples de telles fonctions dans WikiRenderer.conf.php : wikibuildlink, wikibuildimage, wikibuildanchor.

Modifier les tags wiki de bloc de texte

Les tags wiki de blocs permettent d'indiquer la nature d'un bloc de texte : titre, paragraphe, liste, citation etc.. Pour prendre en charge un type de bloc de texte, il faut développer une classe dérivant de WikiRendererBloc. Et ensuite indiquer cette classe dans la classe de configuration.

Si vous voulez seulement modifier quelques propriétés d'un bloc existant dans la configuration par défaut (par exemple redéfinir l'expression régulière, donc le tag du bloc), vous pouvez simplement écrire une classe dérivant du blog d'origine et indiquer la nouvelle expression régulière, comme ceci :

class WRB_monTitleAMoi extends WRB_title {
   var $type='titleamoi';
   var $regexp="/^(\={1,3})(.*)/"; // et non plus /^(\!{1,3})(.*)/
}

Les propriétés

Voici les propriétés de WikiRendererBloc que vous pouvez modifier dans votre propre classe :

type
C'est un nom que vous donnez arbitrairement à votre tag. Il doit être unique parmis les noms des autres tag wiki de blocs (propriété obligatoire).
regexp
Expression régulière qui sera appliquée sur chaque ligne du texte, pour savoir si la ligne appartient au bloc (Propriété obligatoire).
_openTag
C'est la balise XHTML qui sera insérée au début du bloc de texte. Propriété obligatoire si la méthode open n'est pas redéfinie ou si la propriété _closeNow est à false et/ou que vous n'avez pas redefini getRenderedLine.
_closeTag
C'est la balise XHTML qui sera insérée à la fin du bloc de texte. Propriété obligatoire si la méthode close n'est pas redéfinie ou si la propriété _closeNow est à false et/ou que vous n'avez pas redefini getRenderedLine.
_closeNow
C'est un boolean (true ou false), qui indique si le bloc doit être fermée immediatement aprés son ouverture. On mettra donc true si le bloc ne fait qu'une ligne, comme c'est le cas pour les titres ou les séparateurs HTML <hr />. (Propriété obligatoire).

Il existe également une propriété, _detectMatch, qui contient ce qui a été trouvée par l'expression régulière, si celle-ci a des parenthèses capturantes. Vous pourrez donc faire appel à cette propriété dans les méthodes open ou getRenderedLine pour éviter éventuellement d'avoir à refaire une analyse de la ligne de texte pour la transformer.

Les méthodes

constructeur
C'est dans le constructeur que vous pourrez initialiser les propriétés de votre objet. Le constructeur doit accepter en paramètre l'objet WikiRenderer, passé en référence. Ainsi, si votre classe s'appelle WRB_title, vous devrez débuter la déclaration du constructeur comme ceci: function WRB_title(&$wr){.
Le fait d'avoir l'objet WikiRenderer en paramètre vous permet d'accéder éventuellement à la configuration. Ex: $this->_minlevel = $wr->config->minHeaderLevel;.
Vous devrez également impérativement faire appel au constructeur de WikiRendererBloc comme ceci : parent::WikiRendererBloc($wr);.
detect
Cette méthode est appelée pour detecter si la ligne de texte courante fait partie du bloc ou pas. En temps normal, vous ne devriez pas avoir à redefinir cette méthode.
open
C'est une méthode appelée quand le début du bloc a été détécté. Elle doit renvoyer du texte HTML à inserer au début du bloc généré (<ul> pour une liste par exemple). Par défaut, renvoi la valeur de la propriété _openTag. Vous pouvez redefinir cette méthode si vous voulez éffectuer d'autres traitements à ce moment là.
close
C'est une méthode appelée quand la fin du bloc a été détéctée. Elle doit renvoyer du texte HTML à inserer à la fin du bloc généré (</ul> pour une liste par exemple). Par défaut, renvoi la valeur de la propriété _closeTag. Vous pouvez redefinir cette méthode si vous voulez effectuer d'autres traitements à ce moment là.
closeNow
Renvoi par défaut la valeur de la propriété _closeNow (un booléen). Elle indique donc au moteur de WikiRenderer si il faut fermer immediatement le bloc juste aprés l'ouverture. En temps normal, vous ne devriez pas avoir à redefinir cette méthode.
getRenderedLine
Elle doit renvoyer la ligne courante transformée en XHTML, en utilisant notamment la méthode _renderInlineTag. (Note : Avant la version 2.0 finale, getRenderedLine acceptait en paramètre la ligne de texte courante. Ce n'est plus le cas pour des raisons d'optimisation. En effet, on trouve celle ci dans le premier élement de _detectMatch : $ligneOriginale=$this->_detectMatch[0]).
Par défaut, elle fait juste ça : return $this->_renderInlineTag($this->_detectMatch[1]);.
_detectMatch contenant le résultat de l'évaluation de l'expression régulière regexp de votre bloc, cela signifie donc qu'il doit y avoir au moins une parenthèse capturante dans l'expression. Si il y a plus d'une parenthèse capturante ou pas du tout, il vous faudra donc redéfinir getRenderedLine pour en tenir compte.
Vous pourriez aussi avoir besoin de faire des choses supplémentaires. Par exemple, si il s'agit d'un bloc de liste, rajouter les balises XHTML <li> et </li>, avant et aprés le texte transformé. Cela donnerait : return '<li>'.$this->_renderInlineTag($this->_detectMatch[1]).'</li>';.
Il peut arriver aussi parfois, de ne pas tenir compte de la ligne de texte, et de renvoyer directement un contenu, comme cela peut être le cas pour la séparation <hr /> : return '<hr />';.
_renderInlineTag
Cette méthode appelle le moteur de rendu des tags wiki inline (WikiInlineParser). Elle prend en argument une chaine formatée wiki et renvoie la chaine correspondante en XHTML. En principe, vous n'avez pas à la redéfinir.

Nommage de votre classe

Le nom de votre classe doit commencer par WRB_ et se finir par un nom que vous indiquerez dans la propriété bloctags de la configuration. Ainsi, si vous nommez votre classe WRB_titre, vous mettrez dans la configuration :

var $blogtags = array( ... , 'titre'=>true, ... );

Principes de fonctionnement

Voici quelques informations qui vont vous permettre de mieux comprendre comment est utilisé un objet WikiRendererBloc par le moteur WikiRenderer.

Pour en savoir plus sur les blocs

Regardez comment sont développés les blocs par défaut, dans le fichier WikiRenderer.conf.php.

Fonction de traitement des mots wikis

Les mots Wiki sont des mots qui commencent par une majuscule et en contiennent au moins 2. Ex : CeciEstUnMotWiki. Cela est utilisé dans les systèmes wiki, pour faire automatiquement des liens vers les pages qui portent le même nom.

WikiRenderer permet de détecter ces mots Wiki, mais ce n'est pas activé par défaut, car le traitement des mots Wiki est spécifique à l'usage que vous en faites. Pour utiliser les mots wiki vous devez donc :

  1. Modifier dans l'objet de configuration les propriétés checkWikiWord (activer la détection) et checkWikiWordFunction (indiquant la fonction de traitement des mots wiki).
  2. Définir une fonction de traitement des mots wiki

Voici un exemple de configuration :

class ConfWikiRenderer extends CopixWikiRendererConfig {
  var $checkWikiWord = true;
  var $checkWikiWordFunction = 'evalWikiWord';
}

Ici WikiRenderer fera appel à la fonction evalWikiWord.

La fonction que vous indiquerez devra accepter en paramètre une liste de mots wiki qui ont été trouvé dans la ligne de texte courante. Et devra retourner une liste de chaine qui remplaceront ces mots wiki dans le texte. Le contenu de cette liste est dans le même ordre que la liste des mots wiki : la première chaîne correspond au premier mot wiki, la deuxième au deuxième mot wiki etc.

Exemple de fonction pour un système d'edition wiki, qui retourne des liens HTML pour chaque mot wiki, liens qui sont différents si ces mots correspondent ou pas à des pages wiki : 

function evalWikiWord($wikiWordList){

   $result=array();

   foreach($wikiWordList as $word){
      // findWikiPage = fonction imaginaire, qui tenterait de trouver dans un système wiki, la page correspondante au mot
      if(findWikiPage($word))
         // page wiki trouvée
         $result[]='<a href="wiki.php?wiki='.$word.'" class="wikiword">'.$word.'</a>';
      else
         // page wiki non trouvée
         $result[]='<a href="wiki.php?wiki='.$word.'&action=edit" class="unknowwikiword">'.$word.'</a>';
   }
   return $result;
}