MODx - Gérér les Chunks lié au template avec GetChunkTemplate.

Dans ce post, je vais présenter l'origine et l'utilisation de mon Snippet GetChunkTemplate. Une section d'apronfondissement et de généralisation de la solution est également disponible. Le snippet est téléchargeable à la fin de ce post, son source est également disponible.

MODx ?

Je ne vais pas m'étaler sur une présentation de MODx dans ce premier post à son sujet. De nombreuses présentations sont disponibles sur le web. A ce jour une communauté francophone commence également à se développer plus officiellement avec un site web dédié. Alors MODx c'est quoi ? Bé c'est tout simplement le CMS qui gére ce site. Mais modx est bien plus qu'un CMS, c'est un CMF. Personnellement, je le trouve mieux que Joomla. Il est sûrement plus compliqué à aborder pour les non-techniciens, mais il est réellement personalisable... Bref le résultat est bien plus customisable... par contre le parcours est un peu plus semé d'embûche... chose logique.
Pour finir, reprenons la présentation frenchy officiel:

MODx est l'outil idéal pour les développeurs et webdesigners qui cherchent un framework de gestion de contenu hautement flexible et performant, tout en étant simple d'accès pour les utilisateurs finaux. Actuellement, il vise avant tout un public averti (ayant de bonnes connaissance en XHTML, CSS voire quelques notions de PHP).

Le reste de cet article est donc dirigés aux personnes déjà familiarisé avec le monde de Modx.

Les "Chunks Template"

Origine

Beaucoup de Snippets utilisent des paramètres afin de customiser leur rendu graphique. Ces paramètres pointent usuellement sur des Chunks contenant le gabarit graphique html a utilisé. Ce gabarit contient des basiles qui seront remplacés par des informations dynamique provenant du snippet appelant, ce sont les placeholders. De ce point de vue la régle de base de séparation du contenu/contenant est bien appliquée. Il y a toutefois des limites à ce sujet: souvent les gabarits html contiennent déjà quelques mots pour présenter le contenu dynamique, par exemple pour un blog la date du post pourra être introduite de différent manière selon le template du site.

Dans la suite de cet article, nous nommerons ce genre de chunk les "Chunks template" car ceux si sont réellement liés aux templates.
Prenons l'example du célébre snippet Ditto. Celui-ci est en charge, pour faire court, du listage des articles d'un blog. Il est paramètrable par de nombreux gabarits html. Après quelques utilisations, et tests on se rend bien compte que ces gabarits (chunks template) sont réellement dépendant du template utilisé par le site web. Selon le template du site la liste des articles contenu par votre blog sera différente... ces gabarits doivent donc être personalisés sur changement de template. Si un jour vous avez envie de changer le template de votre site web (ou si vous donnez la possiblité d'en changer dynamiquement), vous devrez donc toucher au rendus de vos listes d'articles générés par Ditto, et donc vous devrez modifier ces Chunks Templates.

Certes certains me dirront qu'avec des gabarits html assez générique (avec des div et des class dans tous les sens pour chaque partie), il est déjà fortement possible de customiser la sortie rien qu'avec le css utilisé par le template de votre site web. Le projet Jardin Zen css nous l'a prouvé depuis longtemps. Mais ceçi est réellement applicable quand on passe un certains temps sur son css, en espérant que la gabarit unique a bien été pensé. En pratique si vous avez récupérez un template sur le net, il vous faudra alors passer par la case retouche du 'css' qui est toujours très douleureuse grâce à certains navigateur.... Il est bien plus simple de garde le css livré est adapté son gabarit. De plus les templates peuvent aussi avoir des texte fixes différents, des présentations de dates différents... le gabarit doit bien être touché.

Bref, nous avons donc des snippets (comme Ditto) qui appelent ce genre de Chunk Template. Les Pages contenants ces appels constituent souvent le squelette de votre site Web, et sont souvent celle présente dans un répertoire de base au niveau de la structure de votre site. De plus ces pages contiennent souvent d'autres champs dynamiques et ce sont donc elle qui les agence. Elle sont donc elle-même des sorte de gabarit html, ou même des gabarit de snippets. Appelons les: pages squelettes. Toutes ces pages, très lié au section du site, styles et templates, sont donc aussi suceptible d'être modifiées lors d'un changement de template. Nous allons donc généraliser l'utilisation de nos Chunk Template au niveau de ces pages squelettes qui seront donc totalement contenu par ce genre de Chunk.

Dans le reste de cet article nous allons donc mettre en place une méthode générique et automatique qui se chargera d'utiliser différent ChunkTemplate selon le Template utilsé par le Site Web. Cette méthode s'appuie sur un snippet et un peu d'organisation au niveau des Chunks.

Terminologie

  • PageSquelette: Ce sont les documents modx structurant le site web. Ils sont en général situés dans les répertoires de base de la structure du site.
  • SqueletteHTML : Ce sont des portions de code HTML contenant des champs remplies dynamiquement (les placeholders sous MODx). Ils sont généralement définis par des chunks qui sont utilisés comme paramétres de template pour personaliser la sortie générés par certains Snippet.
  • ChunkTemplate : Ce sont les Chunks qui sont liés à un Template. Ils sont donc toujours utilisé comme squelette. Ils peuvent donc contenir des SqueletteHTML ou la totalité dune PageSquelette.

La solution: mon snippet GetChunkTemplate

Présentation

Le Snippet que j'ai mis en place permet de retourner le contenu d'un chunk qui est dépendant d'un template. Il prend un unique paramétre chunk, qui est le nom de base du chunk. Il retourne alors le contenu du Chunk donc le nom est construit par concaténation du nom du template courant, d'un underscore, et de la valeur du paramètre: "CurrentTemplateName_paramChunk". Par example en passant le nom tpl_blogMainPage et si le template courant est MyTemplate, alors le contenu du chunk nommé MyTemplate_tpl_blogMainPage est retrourné. Si ce dernier n'existe pas c'est le contenu de default_tpl_blogMainPage qui sera retourné (ou encore tout simplement le contenu de tpl_blogMainPage si le chunk commencant par default n'existe pas non plus).En dernier recours, (auncun chunk trouvé) une chaîne vide est retourné.

GetChunkTemplate - FlowChart

Utilisation

Prenons un example issue du site web livré avec l'installation de modx. La page utilisée pour appeller Ditto est la page squelette de la section Blog de notre site. Cette page est la suivante:

 
[[Ditto? &startID=`2` &summarize=`2` &removeChunk=`Comments` &tpl=`ditto_blog` &paginate=`1` &extenders=`summary,dateFilter` &paginateAlwaysShowLinks=`1` &tagData=`documentTags`]]
 
Showing [+start+] - [+stop+] of [+total+] Articles
 
[+previous+] [+pages+] [+next+]
 
[[Reflect? &dittoSnippetParameters=`startID:2` &groupByYears=`0` &showItems=0` &tplMonth=`reflect_month_tpl`]]
 

Comme indique plus haut, on s'aperçoit que c'est bien toute la page web qui peut être impactée par un changement de template. Dans cette page, on appelle Ditto avec des ChunkTemplate, et on trouve aussi des placeholders dépendant de Ditto, et enfin l'appel d'un autre snippet utilisant également des ChunkTemplate. Cette page fait bien parti du squelette du site web est mérite fortement sont nom de page squelette.

On va couper le contenu de cette page (Ctrl-X, on va utiliser ce texte plus loin) et on va le remplacer par ce simple appel à mon Snippet:

 
[[GetChunkTemplate? &chunk=`DittoCall`]]
 

Il nous faut donc créer un Chunk nommé default_DittoCall (ou DittoCall) dans lequel on va mettre l'ancien contenu de notre page.
Si on effectue un test à ce niveau l'appel du Snippet va retourner le contenu du Chunk nouvellement crée, et notre site web sera exactement comme avant.

Par contre, maintenant il est beucoup plus facile d'intégrer un nouveau template. Une fois le nouveau gabarit du template mis en place, nommons le MyTemplate, il nous suffit alors d'appliquer ce template aux pages pour qu'il soit pris en compte comme nouveau template. Ensuite l'affichage utilisera toujours votre ancien chunk. Pour customiser le squelette de votre blog il suffit simplement de faire un nouveau Chunk nommé my_template_DittoCall. Un petit test, et on se rend compte que c'est bien ce nouveau Chunk qui est utilisé !

Maintenant que vous changez de template vous n'avez plus besoin de changer tous les document squelettes de votre site web. Tout est géré depuis les Chunks. Et vous ne perdez plus les anciens paramétres utilisés avec votre ancien template dans l'appel des différents snippets. Vraiment Simple et Facile....

Allons plus loin...

Pour tout bien ranger, il faudra faire attention dans le nommage de ces différents Chunks. Il faudra prendre l'habitue de bien nommé tous les ChunkTemplates avec le nom du Template référant en prefix. De même pour ceux qui ne sont pas directement utilisé par mon snippet. Par example dans notre appel à Ditto dans le Chunk default_DittoCall, on utilise le chunk ditto_blog comme template. Pour bien organiser tout ca il faudrait le nommer default_ditto_blog. Ensuite dans notre nouveau appel à Ditto depuis le Chunk mytemplate_DittoCall on pourra apeller le template utilisé my_template_ditto_blog. Tout ceçi n'est pas obligatoire, mais permet d'avoir une réel meilleur organisation... c'est du bon sens...

Il faudra faire attention à ne pas changer le nom d'un template. Mon snippet ne serait plus capable de faire le lien avec les Chunks Templates déjà mis en place (sauf si ceux si sont également renommé bien entendu). Pour éviter ce problème on pourrait créer une interface utilisateur permettant de lier des Chunks à des Templates. Les liens seraient alors basés sur les id (en base) des chunks et les changement de nom du template n'impacteront plus ce lien. (le paramètre Chunk de mon snippet existerait toujours mais le snippet chercherait alors parmis les chunks liés au template courant, celui qui contient le nom passé en paramètre).

En suivant ces régles pour l'utilisation de mon snippet l'utilisation d'un template nécessite donc l'installation du Gabarit de ce template, des ces fichiers liés (css, images) mais aussi des différents ChunksTemplates. Cette installation est possible en un clik via le module SkinGraft.
Par contre pour que tout se limite réellement à un click il faudrait fixer quelques autres régles:

  • tout le monde doit utiliser GetTemplateChunk dans ces documents squeltettes,
  • une régle quand au nom de base des ChunkTemplate doit etre également dicté. Par example pour la page squelette de Ditto nommez votre chunkTemplate NomDuTemplate_Ditto.

Cela devient un peu laborieux !! Mais le click unique est faisable uniquement dans ce cas.
Une manière plus ouverte et conviviale serait une interface de packaging et d'installation de template plus poussée. On pourrait alors changer, lors de l'instalation du template, le nom des Chunks qui sont utilisés dans l'appel de GetTemplateChunk:

  • Du côté du packaging, il faudra permettre une distinction des Chunks qui sont en réalité le contenu d'une PageSquelette. Ce sont donc les Chunks qui sont appelés via le snippet GetTemplateChunk.
  • Lors de l'installation, une interface pourrait demander à l'utilisateur quel nom doit être utilisé pour ce genre de chunk.
On rejoint là l'interface du point précédant (connaissance des chunk lié au tempalte via leur id), en beaucoup plus riche. Ce dernier point pourrait être à creuser.

Le Source de GetChunkTemplate

 
<?php
/*
 * @Title: GetChunkTemplate Snippet
 * 
 * @Brief:
 *      Get Specific Chunk Content, depending current Template used.
 * 
 * @Author: 
 *      Fabien Letort (www.fabienletort.com)
 * 
 * @Version: 
 *      0.1
 *
 * @Param: 
 *      - chunk:
 *       Purpose: Terminal Name of the Chunk to return.
 *       Mandatory: YES (if not present "" is returned)
 * 
 * @Return:
 *      The Contant of the Chunk whose name is build from the concatenation
 *      of the name of the current template and the parameter chunk, separated
 *      by the underscor character: "'currentTemplateName'_'paramChunkValue'".
 *      If this chunk does not exist the snippet try to return the content of
 *      a potential default Chunk: "default_'paramChunkValue'" or "'paramChunkValue'".
 *      Otherwise "" is returned: no chunk is used.
 *
 * Links:
 *     - On author French Blog: http://www.fabienletort.com/blog/modx-snippet-getchunktemplate/
 *     - On Modx Repository: http://modxcms.com/GetChunkTemplate-0.1-2033.html
*/
 
global $table_prefix;
 
/* Get parameter Value */
$chunk = isset($chunk) ? $chunk : "";
 
/* Get parameter Value */
$chunk = isset($chunk) ? $chunk : "";
 
$output = "";
 
if ($chunk != "")
{
    $templateId = $modx->documentObject['template'];
    $templateName = 
        $modx->db->getValue($modx->db->select("templatename", $table_prefix."site_templates", "id='$templateId'"));
 
    $output = $modx->getChunk($templateName."_".$chunk);
    if ($output == "")
    {
        $output = $modx->getChunk("default_".$chunk);
    }
    if ($output == "")
    {
        $output = $modx->getChunk($chunk);
    }
}
 
return $output;
?>
 

Download from MODx Repository
top