À la demande générale de mon cousin, voici un tutoriel sur la création de mon premier plugin Joomia. Je ne savais même pas ce qu'était un plugin Joomla 24 heures auparavant, bien que j'en avais déjà installé, activé/désactivé sur mes sites web. Mon tutoriel va expliquer tout cela, code à l'appui.
Un plugin Joomla, c'est quoi ?
Un plugin Joomia, et bien c'est un plugin pardi ! La question est plutôt à quoi sert et quel est le rôle d'un plugin pour le CMS Joomla
Et la réponse est très claire :
Un plugin, sous Joomla, et une extension du logiciel qui n'a pour but que de répondre à un événement.
Si vous avez déjà pratiqué un peu de Visual Basic ou de Delphi, ou même d'autres langages de programmation au travers d'un IDE, c'est exactement ce que l'on retrouve dans les inspecteurs d'objets et qui commence par généralement on, c'est-à-dire un événement.
Un événement, c'est la réponse à une action utilisateur.
Un événement de type oncClick, c'est la réponse du logiciel que vous êtes en train d'écrire, lorsque votre utilisateur clique sur la souris. D'autres événements comme onMouseOver, onExit,... existent, et pour chacun d'entre eux, vous coderez à l'intérieur ce que le logiciel doit exécuter lorsqu'il reçoit interruption système.
Je m'arrête en ce qui concerne les événements, je vous épargne les interruptions sur un événement. Ce qu'il faut retenir, c'est que sur un événement prédéfini par le langage de programmation, une action est lancée. Cela ne vous rappelle pas les interruptions système ? Bien sûr que si ! Alors rentrons désormais dans le vif du sujet.
Mon besoin : Avoir un champ email
Mon besoin est super simple. La version de Joomla (3) n'a pas de champs de type email. Un champ de type email et un champ sur lequel nous pourrions renseigner une adresse email, qui afficherait un lien hypertexte, avec une commande mailto:, permettant, lorsque l'utilisateur clique sur ce lien hypertexte, de lancer son client mail par défaut sur son ordinateur.
Que l'on soit bien d'accord : Ce plugin est génial pour le spam, je sais, sauf si on est sur un réseau interne non connecté à internet Et c'est le cas, il n'y a aucun risque pour cela. Parenthèse faite, découvrons comment j'ai écrit ce plugin.
L'organisation des fichiers.
Pour commencer, il faut savoir où placer une fichier dans le CMS Joomla. Nous allons travailler dans notre propre dossier de notre propre plugin Joomia. Il se trouve dans notre sous-dossier [dossier joomla]/plugins/fields/email. Pourquoi fields ? Tout simplement parce que nous allons faire un champ de saisie ! L'organisation des fichiers sera donc celle présenté ci-dessous :
Soyons d'accord : je n'ai pas tout écrit, et me suis énormément basé sur le champ texte existant, auquel j'ai rajouté mes propres fonctionnalités. Je crois que nous appelons ça héritage en programmation orientée objet. Pour rappels sur l'héritage, le principe est de prendre un objet existant, auquel nous rajoutons une fonctionnalité ou une propriété. En d'autres termes, nous créons soit une nouvelle propriété, soit une nouvelle méthode pour étendre les capacités de la classe de départ.
Entrons désormais dans le vif du code.
<?php
/**
* @package Joomla.Plugin *
* @subpackage Fields.Text *
* @copyright Copyright (C) 2005 - 2020 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/ defined('_JEXEC') or die;
$value = $field->value;
if ($value == '')
{
return;
}
if (is_array($value))
{
$value = implode(', ', $value);
}
echo '<a href="mailto:'.htmlentities($value).'">'.htmlentities($value)."</a>"; Le fichier fields/email/email.xml
Dans le même répertoire que le fichier précédent, nous avons aussi un fichier XML qui porte le même nom que le précédent, excepté bien entendu son extension. Dans ce fichier, vous pouvez remarquer une description de manière très détaillée, du plugin que nous allons écrire. Je ne vous cache pas que je ne me suis contenté que de remplacer quelques informations par rapport au plugin de base texte que j'ai dérivé pour faire mon plugin email.
<extension type="plugin" version="3.7.0" group="fields" method="upgrade">
<name>Plugin pour afficher une adresse email</name>
<author>Sébastien LHUILLIER</author>
<creationDate>Juin 2021</creationDate>
<copyright>Copyright (C) 2005 - 2020 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>3.7.0</version>
<description>PLG_FIELDS_TEXT_XML_DESCRIPTION</description>
<files>
<filename plugin="email">email.php</filename>
<folder>params</folder>
<folder>tmpl</folder>
</files>
<languages>
<language tag="en-GB">en-GB.plg_fields_text.ini</language>
<language tag="en-GB">en-GB.plg_fields_text.sys.ini</language>
</languages>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="filter"
type="list"
label="PLG_FIELDS_TEXT_PARAMS_FILTER_LABEL"
description="PLG_FIELDS_TEXT_PARAMS_FILTER_DESC"
class="btn-group"
default="JComponentHelper::filterText"
validate="options"
>
<option value="0">JNO</option>
<option value="raw">JLIB_FILTER_PARAMS_RAW</option>
<option value="safehtml">JLIB_FILTER_PARAMS_SAFEHTML</option>
<option value="JComponentHelper::filterText">JLIB_FILTER_PARAMS_TEXT</option>
<option value="alnum">JLIB_FILTER_PARAMS_ALNUM</option>
<option value="integer">JLIB_FILTER_PARAMS_INTEGER</option>
<option value="float">JLIB_FILTER_PARAMS_FLOAT</option>
<option value="tel">JLIB_FILTER_PARAMS_TEL</option>
</field>
<field
name="maxlength"
type="number"
label="PLG_FIELDS_TEXT_PARAMS_MAXLENGTH_LABEL"
description="PLG_FIELDS_TEXT_PARAMS_MAXLENGTH_DESC"
filter="integer"
/>
</fieldset>
</fields>
</config>
</extension>
Le fichier fields/params/email.xml
Le fichier est un fichier au format XML, son extension vous le faire remarquer.
Ce fichier vous permet de décrire de manière détaillée, comment ce fichier doit contenir les données saisies par l'utilisateur. Nous nous rendons compte que ce champ est de type texte, qui possède comme il y avait la constante décrite à la ligne 8 et la description de ce champ est la constante décrite à la ligne 9.
Comme vous pouvez le voir, un seul champ est défini dans ce fichier XML.
<extension type="plugin" version="3.7.0" group="fields" method="upgrade">
<name>Plugin pour afficher une adresse email</name>
<author>Sébastien LHUILLIER</author>
<creationDate>March 2016</creationDate>
<copyright>Copyright (C) 2005 - 2020 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>3.7.0</version>
<description>PLG_FIELDS_TEXT_XML_DESCRIPTION</description>
<files>
<filename plugin="email">email.php</filename>
<folder>params</folder>
<folder>tmpl</folder>
</files>
<languages>
<language tag="en-GB">en-GB.plg_fields_text.ini</language>
<language tag="en-GB">en-GB.plg_fields_text.sys.ini</language>
</languages>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="filter"
type="list"
label="PLG_FIELDS_TEXT_PARAMS_FILTER_LABEL"
description="PLG_FIELDS_TEXT_PARAMS_FILTER_DESC"
class="btn-group"
default="JComponentHelper::filterText"
validate="options"
>
<option value="0">JNO</option>
<option value="raw">JLIB_FILTER_PARAMS_RAW</option>
<option value="safehtml">JLIB_FILTER_PARAMS_SAFEHTML</option>
<option value="JComponentHelper::filterText">JLIB_FILTER_PARAMS_TEXT</option>
<option value="alnum">JLIB_FILTER_PARAMS_ALNUM</option>
<option value="integer">JLIB_FILTER_PARAMS_INTEGER</option>
<option value="float">JLIB_FILTER_PARAMS_FLOAT</option>
<option value="tel">JLIB_FILTER_PARAMS_TEL</option>
</field>
<field
name="maxlength"
type="number"
label="PLG_FIELDS_TEXT_PARAMS_MAXLENGTH_LABEL"
description="PLG_FIELDS_TEXT_PARAMS_MAXLENGTH_DESC"
filter="integer"
/>
</fieldset>
</fields>
</config>
</extension>
Le fichier email/tmpl/email.php
Passons désormais au dernier fichier en question. C'est dans ce dernier que je ne respecte pas tout à fait le principe modèle vue contrôleur et j'en suis tout à fait conscient. À celles et ceux qui savent comment modifier la ligne 24, c'est avec grande joie que je lirai vos réponses car je l'ignore. En effet, même si bon code est fonctionnel, le fait de faire un écho en dernière ligne du fichier, casse le modèle de type MVC. Passons sur ce détail qui, personnellement, me gonfle royalement, mais je suis conscient que ce n'est pas propre.
La parenthèse et en fait, regardons de plus près ce fichier. Dans la variable value, nous récupérons la propriété value de l'objet. Cette valeur est testée. Si c'est d'ailleurs évident, nous retournons rien, dans le cas où cette valeur est constituée de plusieurs valeurs dans un tableau, elles sont concaténées.
En dernière ligne, je récupère la valeur de la variable value, et j'en sais simplement un simple affichage. Mais d'afficher le contenu direct adresse email, Tout le code HTML permettant de générer un hyperlien de type mailto :
<?php
/**
* @package Joomla.Plugin
* @subpackage Fields.Text
*
* @copyright Copyright (C) 2005 - 2020 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/
defined('_JEXEC') or die;
$value = $field->value;
if ($value == '')
{
return;
}
if (is_array($value))
{
$value = implode(', ', $value);
}
echo '<a href="mailto:'.htmlentities($value).'">'.htmlentities($value)."</a>";
Une fois le processus de découverte en route, il apparaît dans ma liste des éléments découverts mon plugin. Il suffit de le sélectionner au travers de sa case à cocher en début de ligne, puis de cliquer sur le bouton Installer. Voilà votre plugin est prêt à fonctionner. Toutefois, il reste bien entendu une dernière action à ne surtout pas oublier. En effet, lorsque vous installez votre propre plugin, a-priori, le plugin est, par défaut, désactivé. En tout cas c'est exactement ce qu'il se passait chez moi. Il faut donc que vous activiez votre plugin que vous venez d'installer. Retournez alors dans le menu extension -> plugins et rechercher dans la liste des plugins le vôtre. N'hésitez pas à utiliser le moteur de recherche qui est à votre disposition. Lorsque vous l'aurez trouvé, vous remarquerez que son statut est par défaut désactivé. Cliquez alors sur l'icône le rouge symbolisant la désactivation du statut du plugin, l'icône passe à une tick verte. Et voilà votre plugin est fonctionnel. En tout cas le mien l'était.
Utilisation du plugin
Avant d'enregistrer cet article, j'oubliais de vous préciser le fonctionnement de ce plugin.
Lorsque vous allez créer votre champ personnalisé, vous allez pouvoir sélectionner et voir donc apparaître, nouveau type de champs. Ce type s'appelle email. Désormais, lorsque vous allez déclarer dans le menu contenu champ, après avoir donner le nom de votre champ, dans la liste déroulante type, vous verrez apparaître un nouveau type email. Ce type c'est celui que vous avez déclaré dans votre fichier XML. Sélectionner votre type, donnez un titre à votre champ, remplissez les autres particularités de votre champ que le logiciel vous propose, et valider par le bouton Enregistrer.
C'est encore long ?
Bravo, vous venez de déclarer un nouveau champ de type email. Désormais, lorsque vous saisirez une adresse email dans un champ personnalisé de ce type, votre adresse email sera de la forme d'un Hyperlien.