Fr:Snippets:Mon premier snippet

From MODx Wiki

Jump to: navigation, search

Dans ce tutoriel, nous allons voir comment utiliser un snippet pour répondre à un besoin concret: celui d'afficher sur une page un texte choisi au hasard (pour faire une rubrique "Le saviez-vous?"). Le texte devant changer à chaque fois que l'on recharge la page.

Tout d'abord, nous développerons notre propre snippet en PHP, puis nous verrons qu'il peut être plus avantageux d'utiliser un des snippets distribués avec MODx.

Contents

[edit]

La technique du "codeur fou"

Pour répondre à mon besoin, je décide de développer un snippet. C'est à dire un bloc de code PHP exécuté lors du chargement de ma page. Mon snippet définit un tableau avec les différents textes possibles, et le code se résume à en choisir un au hasard (fonction PHP rand): 

<?php
$messages = array(
    "Mon premier message",
    "Second message",
    "Message n°3",
    "Quatrième message",
    "Message de fin");
 
$index = rand(0,count($messages)-1);
$output = $messages[$index];
 
return "<div>$output</div>";
?>

Pour utiliser mon snippet (c'est à dire pour récupérer le résultat de l'exécution du code PHP de mon snippet), et en supposant que je l'ai appelé RandomMessage, il me suffit d'ajouter dans ma page: 

[!RandomMessage!]

Avantage(s):

  • Moins de 5 minutes à faire!

Inconvénient(s):

  • Le texte est codé en dur: pour modifier ou ajouter un message, il faut modifier le code source du snippet. Pas terrible.
  • (à confirmer) Risque de problème avec les caractère spéciaux si l'encodage de la page qui utilise le snippet et celui du snippet n'est pas identique (l'un en UTF-8, l'autre en iso-8859-1, par ex.)
[edit]

En utilisant l'API de MODx

Pour remédier aux inconvénients de la première méthode, j'ai décidé de créer un dossier dans mon document tree et de mettre chaque texte possible dans un document situé dans ce dossier. Mon snippet va donc choisir aléatoirement un document de ce dossier. Une recherche dans la doc de l'API m'apprend qu'il faudra utiliser la fonction getDocumentChildren: 

<?php
$folder = 8;
$active=1;
$deleted=0;
$messages = $modx->getDocumentChildren($folder, $active, $deleted, 'content');
$index = rand(0, count($messages)-1);
 
$output = $messages[$index]['content'];
 
return "<div>$output</div>";
?>

Avantage(s):

  • Séparation du code (le snippet) et des données (les messages)
  • N'importe quel utilisateur avec les permissions suffisantes peut ajouter ou modifier des messages sans avoir à toucher au code PHP

Inconvénient(s):

  • L'identifiant du répertoire est codé en dur ($folder = 8)
[edit]

En utilisant les propriétés des snippets

Ce que je voudrais pouvoir changer (sans modifier le code!) d'une utilisation à l'autre de mon snippet, c'est l'ID du répertoire contenant mes messages. Cette information est donc le candidat idéal pour devenir une propriété du snippet. C'est à dire, en quelque sorte, un arguments utilisée lors de "l'appel" du snippet. Ca a l'air compliqué comme ça, mais en fait, il y a peu de choses à changer: Dans le code du snippet, j'ajoute un test pour voir si la propriété est définie, et pour l'initialiser à une valeur par défaut si ce n'est pas le cas: 

$folder = isset($folder)? $folder:0;

Et lors de l'utilisation de mon snippet sur ma page de test, j'utilise la notation suivante: 

[!RandomChild? &folder=`8` !]

Qui veut simplement dire: "Exécute le snippet RandomChild en initialisant la propriété folder à 8". Voici le code complet du snippet (avec quelques commentaires en prime): 

<?php
# RandomChild 0.1
# Created By Sylvain Leroux - May, 2007
#::::::::::::::::::::::::::::::::::::::::
# Usage:     
#    Allows a web user to retrieve a random document in a folder.
#
# Params:    
#
#    &folder        - ID of the parent folder
#
# Examples:
#
#    [!RandomChild?folder=7!] 
 
$folder = isset($folder)? $folder:0;
$active=1;
$deleted=0;
$messages = $modx->getDocumentChildren($folder, $active, $deleted, 'content');
$index = rand(0, count($messages)-1);
 
return $messages[$index]['content'];
?>
[edit]

Avec Ditto

Jusqu'à présent, j'ai choisi des solutions m'obligeant à développer moi-même mes propres snippets. Mais MODx est livré en standard avec un certain nombre de snippets déjà installés. Parmi eux certains sont très souples et polyvalents. C'est particulièrement vrai pour Ditto.

Pour citer la documentation de Ditto:

Ditto est un snippet construit pour MODx afin d'agréger des documents [...]

L'utilisation première de Ditto est de permettre de facilement créer des blogs, des catalogues d'articles, etc. Il est également possible de l'utiliser pour afficher un article au hasard!

En cherchant dans la documentation de Ditto 2.0.1 et sur la page officielle on découvre qu'il est possible d'obtenir le résultat souhaité simplement en écrivant: 

[!Ditto? &parents=`8` &randomize=`1` &total=`1` &tpl=`@CODE[+content+]` !]

Le code ci-dessus invoque le snippet Ditto avec les propriétés suivantes:

&parent=`8`
ID du répertoire contenant les documents à retrouver
&randomize=`1`
Affiche les résultats dans un ordre aléatoire
&total=`1`
N'afficher qu'un seul résultat
&tpl=`@CODE[+content+]`
Template utilisé par Ditto pour afficher le résultat

Avantage(s):

  • Aucun codage en PHP nécessaire
  • Souplesse

Inconvénient(s):

  • (discutable) Grosse artillerie pour un problème simple
  • (discutable) Performances
Retrieved from "http://wiki.modxcms.com/index.php/Fr:Snippets:Mon_premier_snippet"
Personal tools