Proposer son article
Construire un module - part II
Normer plutôt que Coder
Les modules dans CmsMadeSimple ont conservé l'état d'esprit de CmsMadeSimple : il faut que ce soit simple pour le développeur. Et c'est dans cette optique que les concepteurs ont prévu de privilégier les normes d'écriture afin d'alléger le poids du code très répétitif.
Le premier exemple de l'utilisation de ces normes est la façon de structurer un module. Prenons notre exemple du dernier billet sur la balise utilisateur auto-nettoyante, nous appellerons notre projet CmsModuleCleaner, partant de ce point je vais devoir composer mon projet ainsi (dans le répertoire "modules" de votre installation) :
- ./modules
- ./modules/CmsModuleCleaner
- ./modules/CmsModuleCleaner/lang
- ./modules/CmsModuleCleaner/lang/ext
Dans chaque dossiers vous ajouterez un fichier index.html vide qui servira de sécurité supplémentaire pour éviter qu'un utilisateur trop curieux ne parcourt le contenu de votre module trop facilement
Ce qui fait la force de CmsMadeSimple c'est qu'une telle structure lui permet de détecter seul la présence (ou non) d'un module sur son installation, cela nous évite d'aller modifier le code source du noyau de CmsMadeSimple. Ainsi la mise à jour de CmsMadeSimple se ferra de manière indépendante des modules, ceux qui utilisent des logiciels tels que phpBB, fluxBB et autres savent de quoi je parles :)
Second point dans notre démarche d'économie de code : nommer correctement les fichiers principaux. Vous devez avoir 4 fichiers au minimum dans votre répertoire CmsLangCleaner :
- ./CmsModuleCleaner.module.php
- ./method.install.php
- ./method.uninstall.php
- ./lang/en_US.php
Les fichiers method.install.php et method.uninstall.php sont évidement destinés à contenir les instructions nécessaires à l'installation de votre module et à sa désinstallation. C'est ce code qui sera exécutée lorsque l'utilisateur cliquera sur votre module depuis le gestionnaire de modules pour l'installer, ou lorsqu'il clic sur désinstaller depuis ce même gestionnaire de modules : créer une table, créer des paramétrages dédiés à votre module et tout supprimer lorsque l'utilisateur désinstallera votre module.
Note : Par habitude il vous faut désinstaller TOUT ce que votre module a pu installer ou créer durant son existence afin de laisser place nette à sa sortie.
Leur contenu est du code php sans surprise, on peut le simplifier pour notre exemple à cette simple ligne :
<?php echo "hello world"; ?>
Le fichier de langue : en_US.php est un fichier qui contiendra tous les libellés de boutons, de textfield et de message que génèrera votre module, cette norme préconisée par tous les développeurs consiste à dissocier le fonctionnement d'un module (et d'un programme de façon générale) de la langue de l'utilisateur. Exemple de contenu :
<?php
$lang['texte1'] = 'my tailor is rich';
$lang['texte2'] = 'where is bryan ?';
?>
Notez que nous sommes français mais que le premier fichier de langue doit être écrit en anglais (pas de bol pour les anglophobes). En effet l'anglais est la langue par défaut qui sera pris en compte par CmsMadeSimple. Si vous souhaitez traduire votre module dans la langue de voltaire, nous verrons comment y remédier un peu plus tard.
son utilisation est très pratique puisque dans tous nos fichiers nous pouvons appeler ces traductions. Pour notre exemple je reviens sur le fichier method.install.php et je remplace le code écrit précédemment par ceci :
<?php echo '<b>'.lang('texte2').'</b>'; ?>
Produira en sortie : where is bryan ?;
Dernier fichier : CmsModuleCleaner.module.php, c'est le noyau de votre module. C'est à dire que c'est dans ce fichier que l'on définira le nom du module, sa version, ses dépendances, ses paramètres, et énormément d'autres choses. Voici un exemple ultra simplifié du contenu de ce fichier dans notre cas.
<?php
class CmsModuleCleaner extends CMSModule
{
function GetName()
{
return 'CmsModuleCleaner';
}
function GetFriendlyName()
{
return $this->Lang('friendlyname');
}
function GetVersion()
{
return '1.0.0';
}
function GetHelp()
{
return '';
}
function GetAuthor()
{
return 'Bess';
}
function GetAuthorEmail()
{
return '';
}
function GetChangeLog()
{
return '';
}
function IsPluginModule()
{
return false;
}
function HasAdmin()
{
return false;
}
function GetAdminSection()
{
return 'extensions';
}
function GetAdminDescription()
{
return '';
}
function VisibleToAdminUser()
{
return false;
}
function GetDependencies()
{
return array();
}
function MinimumCMSVersion()
{
return "1.0";
}
function SetParameters()
{
}
function InstallPostMessage()
{
return $this->Lang('postinstall');
}
function UninstallPostMessage()
{
return $this->Lang('postuninstall');
}
function UninstallPreMessage()
{
return $this->Lang('really_uninstall');
}
}
?>
Premier constat à faire : l'héritage de classe. CmsModuleCleaner.module.php hérite des fonctions de CmsModule ce qui permet bénéficier immédiatement de fonctionnalités très puissantes dans notre modules, nous verrons leur utilité un peu plus tard.
Second constat à faire : vous retrouvez les appels aux fichiers de lang. Il nous faut donc enrichir notre fichier de langue pour se mettre à niveau.
<?php
$lang['friendlyname'] = 'Best Cleaner Module Ever';
$lang['postinstall'] = 'Post Install Message';
$lang['postuninstall'] = 'Post Uninstall Message, e.g., "Curses! Foiled Again!"';
$lang['really_uninstall'] = 'Really? You\'re sure you want to uninstall this fine module?';
?>
Voilà pour l'aspect Norme de nos modules
L'installation de votre module
Maintenant que nous avons écrit la base de votre module, nous allons tester son installation et sa désinstallation.
Allez dans le panel admin > gestion des modules, vous devriez retrouver votre module. Cliquez sur "installer"
Et voilà votre module installé ! Un clic sur "désinstaller" devrait vous faire revenir au point de départ.
Dernier point : le partage de votre module
Toujours fidèle à la logique CmsMadeSimple : restons simple.... Cliquez sur le bouton xml sur la droite de la ligne de votre module, un fichier XML devrait vous être proposé en téléchargement, c'est ce fichier que l'on distribuera au final à son client, à ses amis ou à la communauté.
Notez que pour les plus habitués d'entre vous, vous pouvez également proposer un .zip un .tar ou encore un .tar.gz en archivant directement le répertoire de votre module : ./modules/CmsLangCleaner
Déjà finit...
Voilà pour cette seconde partie du tutorial, toujours aussi abordable je l'espère, vous savez maintenant quel est le strict minimum à réaliser pour démarrer votre module et le partager.
Pour ceux et celles qui n'auraient pas envie de perdre trop de temps, je vous invite à télécharger ce fichier xml qui vous permettra d'installer en un clic ce tuto sur votre propre site internet de test. Bien évidement le module proposé en sa version 0.0.1 ne ferra rien d'autre que s'installer et se désinstaller efficacement.
Télécharger CmsModuleCleaner-1.0.0.xml (clic droit > enregistrer sous)
Le prochain tutorial vous montrera énormément de fonctions complémentaires disponibles dans CmsLangCleaner.module.php, quelques exemples de procédures d'installation/désinstallation, mais également le processus de mise à jour des modules.
Stay tuned !