DSC_0298.jpg ESC_0133.jpg DSC_0001.jpg

 i need more coffee

Atteint depuis mon plus jeune âge d'hippopotomonstrosesquippedaliophobie (cultivez vous ça ne fera pas de mal) j'ai décidé de faire un blog sur ma maladie (be feeeaar..).
Blague à part c'est un blog totalement axé génie logiciel que vous trouverez ici. Du PHP, du J2EE, et évidement toutes les technologies qui leur sont liées.

Have fun !

Intégrer un éditeur de template dans son module avec CgExtensions

18 novembre 2013Posté par : Kevin Danezis dans CmsMadeSimple

Petit article pratique sur la manière d'intégrer rapidement un éditeur de template dans ses propres modules CmsMadeSimple avec l'intégration de CgExtensions

La mise en place du système n'est pas difficile mais la documentation étant absente, même en anglais, je profite du blog pour permettre à d'autres de gagner du temps

Attention, cet article suppose que vous êtes déjà développeur de module :)

C'est suite à une demande sur mon module JQueryFU que je me suis penché sur la meilleur manière de proposer un éditeur de template dans l'administration de mon module.

CgExtensions est une réponse naturelle car tout est déjà inclus dans ce module qui -pour rappel- est une librairie avancée dédiée pour CmsMadeSimple. Sa documentation est pauvre et peu de développeur pensent en fait à profiter de ses capacités, moi même je ne l'utilise que très peu. C'est bien dommage et vous allez voir pourquoi.

Le contexte de votre module

Je pars du principe que votre module possède déjà un panel d'administration et utilise les templates Smarty pour afficher du contenu sur le front-office.

Je ne reviendrais pas sur la base de développement de module, vous pouvez trouver mes tutos sur cmsmadesimple.fr pour démarrer le votre.

Afin de faciliter la compréhension, je vais prendre exemple sur mon module JQueryFu et ses noms de fichiers utilisés dans la suite du tuto.

JQueryFU.module.php

le premier fichier à modifier : le noyau de votre module, vous aller modifier la classe dont hérite votre module, habituellement "CMSModule"

class JQueryFU extends CGExtensions

et vous allez préciser maintenant que votre module dépend de CGExtensions en version 1.37 dans mon cas.

function GetDependencies() {

 return array('CGExtensions'=>'1.37');

}

Vous allez également ajouter deux constantes à votre classe JQueryFU qui vont nous servir plus tard.

define("TMPL_PREFIX_DISPLAY" , "display" );

define("DEFAULT_DISPLAY_TMPL_PREF_NAME",'current_'.TMPL_PREFIX_DISPLAY.'_template');

A placer avant la déclarationde votre propre classe.

class JQueryFU extends CGExtensions

La première constante TMPL_PREFIX_DISPLAY va contenir le type de gabarit. La valeur est arbitraire mais doit rester logique car elle permettra dans le futur de définir différent type de template comme le fait le module News : les templates de sommaire, ceux de détail, ceux de liste de catégorie. Dans mon cas je n'ai qu'une seule type de catégorie : le "display" mais ça pourrait changer à l'avenir.

La seconde constante DEFAULT_DISPLAY_TMPL_PREF_NAME contient le nom de la préférence que j'utiliserais plus tard dans le code pour stocker et récupérer le template par défaut pour la catégorie "display".

Si vous définissez 2,3,4 types de templates différents, pensez à démultiplier ce couple de constantes.

templates/admin.tpl

Dans le sous répertoire templates, vous créez ce nouveau fichier qui représente le template du rendu de votre administration. Si un tel fichier existe déjà, incluez le code ci dessous dans votre propre template d'administration

<h3>{$heading_display}</h3>

{$list_display_templates}

Très simple comme vous pouvez le voir : un titre et le contenu que va nous fournir CgExtensions

action.default.php

Votre fichier action par défaut qui fait appel au template smarty pour le rendu de votre module sur le site internet. Si vous appelez des templates depuis d'autres fichier action, pensez à dupliquer le code que je vous propose

$template_name = TMPL_PREFIX_DISPLAY.$this->GetPreference(DEFAULT_DISPLAY_TMPL_PREF_NAME);

Nous récupérons ici dans $template_name le nom du template sélectionné par défaut dans l'administration. Nous pouvons donc l'utiliser de suite !

echo $this->ProcessTemplateFromDatabase($tpl);

Notez l'utilisation de la fonction ProcessTemplateFromDatabase et non pas ProcessTemplate car nos templates vont se trouver en base de donnée ! Pas de soucis de cache, c'est Smarty qui s'occupera de ce travail.

method.install.php

Si inexistant, il va falloir le créer de toute pièce et je ne reviendrais pas sur la manière de le faire. Concentrons nous sur la partie du code intéressante.

# Setup display template

$fn = dirname(__FILE__).'/templates/full.tpl';

Nous récupérons le nom du template que je souhaite insérer en base à l'installation de mon module, c'est le fichier /templates/full.tpl

if( file_exists( $fn ) ) {

    $template = @file_get_contents($fn);

Là nous avons récupéré le contenu de ce fichier /templates/full.tpl

    $this->SetTemplate(TMPL_PREFIX_DISPLAY.'full',$template);

On peut l'enregistrer en base sous l'appelation "display_full". Notez l'utilisation du prefixe "display_" ce qui permet en cas de multi-categorie de template d'avoir des templates sous un même nom dans des catégories différentes.

    //Default values

$this->SetPreference(DEFAULT_DISPLAY_TMPL_PREF_NAME,'full');

$this->SetPreference('default_'.TMPL_PREFIX_DISPLAY.

 '_template_contents',$template);

On enregistre 2 préférences : la première est l'actuel nom du template par défaut à utiliser pour l'affichage dans la catégorie "display" il s'agit de "full" . La seconde préférence est le contenu de ce template par défaut, il servira de modèle pour tous les templates que mes utilisateurs créeront dans leur installation.

Et enfin on referme la condition If

}

Mais ce n'est pas finir car on peut continuer à insérer d'autres templates qui serviront d'exemple pour mes utilisateurs.

# Setup 2nd display template

$fn = dirname(__FILE__).'/templates/basic.tpl';

if( file_exists( $fn ) ) {

    $template = @file_get_contents($fn);

    $this->SetTemplate(TMPL_PREFIX_DISPLAY.'basic',$template);

}

On note ici que j'insère le template basic.tpl sans le nommer "template par défaut".

method.uninstall.php

Ce fichier sert à tout désinstaller. Comme j'ai installé des templates, il me faut les supprimer

$this->DeleteTemplate();

C'est tout, le fait de ne donner aucun nom permet à CmsMadeSimple de supprimer tous les templates liés à JQueryFU :)

action.defaultadmin.php

L'avant dernier fichier à modifier, et sans doute le plus important finalement.

$smarty = cmsms()->GetSmarty();

J'initialise la variable smarty

$smarty->assign('heading_display', $this->Lang('heading_display'));

Je donne le titre de mon administration (voir admin.tpl)

$tpl =     $this->ShowTemplateList(

        $id,

        $returnid,

        TMPL_PREFIX_DISPLAY,

        'default_'.TMPL_PREFIX_DISPLAY.'_template_contents',

        'template',

        'current_'.TMPL_PREFIX_DISPLAY.'_template',

        $this->Lang('title_display'),

        $this->Lang('text_display_edit'),

        'defaultadmin'

    )

C'est ici que la magie s'opère. la fonction ShowTemplateList est disponible grâce à CgExtensions et prend de nombreux paramètres. Ce qu'il faut retenir c'est surtout l'utilisation de TMPL_PREFIX_DISPLAY qui me permet de m’abstraire du type de template que je suis en train de lister, ainsi vous pouvez dupliquer facilement ce code en changeant la constante pour passer d'une liste de template de "display" à une liste de template de "summary" (sommaire) ou de "detail".

Il reste donc à afficher $tpl. Pour cela il me suffit d'affecter $tpl à Smarty et à appeler mon template admin.tpl créé au début du tuto.

$smarty->assign('list_display_templates',$tpl);

echo $this->ProcessTemplate('admin.tpl');

lang/en_US.php

dernier fichier : le wording. J'ai ajouté 4 nouvelles entrées dans mon fichier de lang qui sont évidement liée à ma catégorie de template "display". Vous pouvez adapter à votre sauce selon vos propres besoins.

$lang['title_template'] = 'Templates';

$lang['heading_display'] = 'Edit the templates';

$lang['title_display'] = 'Main Template';

$lang['text_display_edit'] = 'Edit the template';

Fini !

Et oui c'était pas bien compliqué comme d'habitude avec CmsMadeSimple. Voici une petite capture d'écran de ce que cela rend chez moi.

2013-11-17_201402.png

comments powered by Disqus