Creer plugin

Un article de FreeGlobes Wiki.

Sommaire 1 Architecture générale d'un plugin 1.1 Préambule 1.2 Architecture multilingue 1.3 Où se trouvent les plugins ? 1.4 De quoi se compose un plugin ? 1.5 Fichiers qui composent un plugin 2 Architecture détaillée de chaque fichier 2.1 Langues 2.1.1 Dossier language/ 2.1.2 lang.php 2.1.3 Préfixez les clefs de vos définitions de langue 2.1.4 Chargement des langues 2.2 desc.xml : Description du plugin 2.2.1 Contenu général 2.2.2 Définition du plugin 2.3 index.php : Page d'administration de votre plugin 2.3.1 Afficher du text/code HTML 2.3.2 Accessibilité des fonctionnalités de FreeGlobes 2.3.3 Conventions de codage 2.4 functions.php : fonctions accessibles depuis les templates 2.4.1 Convention d'écriture 2.4.2 Exemple de fichier functions.php 2.4.3 Appel d'une fonction d'un plugin depuis un template 2.4.4 Plugin Smarty d'appel de fonction d'un plugin

Architecture générale d'un plugin

Préambule

Un plugin (extension) est un petit script en PHP qui va venir se rajouter à FreeGlobes pour apporter de nouvelles fonctionnalités. Par exemple, FreeGlobes possède un plugin nommé "A propos" qui informe l'administrateur des différents droits sur les fichiers ainsi que sur les versions PHP et MySQL installées sur son serveur.

FreeGlobes utilise une version modifiée de l'architecture Plugin de Dotclear.

Un plugin se caractérise par sa modularité : il doit pouvoir être installé sans problème sur n'importe quel site fonctionnant avec le script FreeGlobes.

Architecture multilingue

Un plugin est conçu pour être multilingue. Chaque plugin possède donc un dossier language/ contenant pour chaque langue la définition de chaque expression utilisée dans le plugin. Vous devez obligatoirement utiliser ces fichiers de langues pour définir le texte de votre plugin.

Où se trouvent les plugins ?

Tous les plugins de FreeGlobes sont installés dans le répertoire "plugins/". Chaque plugin est un sous-dossier du dossier "plugins/".

De quoi se compose un plugin ?

Un plugin est un sous-dossier du dossier "plugins/" et portant le nom simplifié de celui-ci. Par exemple, le plugin A propos de FreeGlobes est dans le répertoire "info/" du dossier "plugins/".

Fichiers qui composent un plugin

L'image ci-dessus vous montre les fichiers présents dans le plugin info que nous allons prendre comme plugin type. Un plugin se compose des fichiers suivants :

• desc.xml : ce fichier décrit le plugin (auteur, titre, description et actif/inactif). Il est au format XML.
• icon.png : image du plugin au format PNG (32x32 pixels) qui va apparaitre dans le panneau d'administration des plugins.
• index.php : Il s'agit du fichier PHP affiché lorsque l'utilisateur se rend sur la partie administration de votre plugin.
• functions.php : ce fichier contient les fonctions spécifiques au plugin qui peuvent être appelées dans le template (thème) du site.
• language/ : dossier des langues. Pour chaque langue, il existe un dossier portant le nom de la langue qui contient un fichier lang.php.
• (facultatif) images/ : images spécifiques au plugin.

Nous allons maintenant voir plus précisément à quoi servent chacun de ces fichiers et les règles à respecter pour leur conception.

Note : Vous pouvez bien sûr créer d'autres dossiers dans votre plugin pour vos besoins. Il s'agit ici d'expliquer la manière d'organiser un plugin aux fonctionnalités minimales.

Architecture détaillée de chaque fichier

Langues

Dossier language/

Nous abordons ici le dossier language/ et son contenu. Ce dossier contient un dossier pour chaque langue.

Voici un exemple du contenu du dossier langue :

Nous remarquons que ce plugin possède les langues suivants : anglais et français. Le nom des langue sera spécifié en anglais de préférence. Chacun de ces dossier contient un fichier portant le même nom : lang.php.

lang.php

Voici un exemple de code contenu dans le fichier language/english/lang.php (dossier relatif à partir de la racine de votre plugin) :

<?php
// Définition pour chaque langue de l'auteur, du titre et de la description du plugin
// Utilisé dans le panneau d'administration des plugins
$lang['in_author'] = 'Jerome Loisel';
$lang['in_label'] = 'About FreeGlobes';
$lang['in_desc'] = 'System information.';

$lang['in_information'] = "Information";
$lang['in_generalinformation'] = "General Information";
$lang['in_yourtables'] = "Freeglobes Tables";
$lang['in_name'] = "Name";
$lang['in_records'] = "Rows";
$lang['in_size'] = "Size";
$lang['in_fileinfos'] = "file system information";
$lang['in_fileinfoshelp'] = "User rights on different files and directories.";

?>

Le fichier lang.php contient un tableau nommé $lang et qui contient toutes les définitions de langue de votre plugin.

Préfixez les clefs de vos définitions de langue

Les indexes de $lang sont préfixés. Pour éviter qu'il y ait des collisions dans les définitions de langue, il convient pour chaque plugin de définir un préfixe de langue (ici le préfixe est "in") unique compose d'au moins 3 lettres (ici 2 lettres, mais c'est reservé aux plugins par défaut).

Exemple : vous avez fait un plugin "tartempion". Voici comment vous pouvez préfixer vos langues :

<?php
$lang['tart_author'] = '...';
?>

Chargement des langues

• Vos définitions de langue sont chargées automatiquement lorsque l'utilisateur affiche la page d'administration de votre plugin. Vous n'avez pas besoin de gérer l'inclusion de ces fichiers langue.
• FreeGlobes connait d'après la configuration du site la langue définie pour le site. Il va donc chercher le dossier de langue du même nom présent dans le dossier language/ de votre plugin.

desc.xml : Description du plugin

Contenu général

Voici le code d'un fichier desc.xml type :

<?xml version="1.0" encoding="ISO-8859-1"?>
<plugin name="info" version="1.1" active="1">
 <author>in_author</author>
 <label>in_label</label>
 <desc>in_desc</desc>
</plugin>

Le fichier desc.xml utilise donc la syntaxe XML pour définir le plugin. L'auteur, le titre et la description du plugin sont à indiquer en inscrivant l'index de langue définissant chacun de ces éléments.

Dans le cas présent, il faut donc le code ci-dessous dans chaque fichier langue :

$lang['in_author'] = 'Jerome Loisel';
$lang['in_label'] = 'About FreeGlobes';
$lang['in_desc'] = 'System information.';

On voit donc immédiatement la correspondance logique : pour afficher le résumé de votre plugin dans le panneau d'administration des plugins, FreeGlobes va chercher $lang['votreindex'] et l'affiche. Dans l'exemple ci-dessus, pour afficher l'auteur, vous avez indiqué 'in_author' comme index de langue. FreeGlobes va donc chercher $lang['in_author'] dans le fichier de langue lang.php présent dans votre plugin.

Définition du plugin

<plugin name="info" version="1.1" active="1">

• L'attribut "name" doit correspondre au nom du répertoire contenant le plugin. Ici, il s'agit du répertoire "info".
• L'attribut "version" indique la version courante du plugin.
• L'attribut "active" indique si le plugin est activé (1) / désactivé (0). Cet état peut être changé par le gestionnaire de plugins si le fichier desc.xml est accessible en écriture (droits 777).

index.php : Page d'administration de votre plugin

Ce fichier contient le code PHP affichant la page d'administration de votre plugin.

Afficher du text/code HTML

Voici un fichier index.php très simple :

<?php
Buffer::str($lang["hello"]);
?>

Remarques importantes :

• Pour tout affichage, il faut utiliser la routine Buffer::str(). Vous ne pouvez pas utiliser des fonctions PHP comme "echo" ou "print" et la raison est très simple : votre affichage est géré par FreeGlobes via le moteur de templates Smarty; l'utilisation du Buffer permet à FreeGlobes d'intégrer l'affichage de votre page admin dans l'affichage général de l'administration.

• Ne mettez jamais le texte de votre plugin en dur. Utilisez les fichiers de langues !

• Il n'est pas nécessaire d'échapper les lignes d'affichages dans votre code. en effet, voici la fonction str() de la classe Buffer :

<?php
class Buffer
{
  ...


  function str($str)
  {
	global $CONFIG;
	$str = $CONFIG['encoding'] == 'UTF-8' ? utf8_encode($str) : $str; 
	$GLOBALS['__fg_buffer'] .= $str."\n";
  }

  ...
}
?>

FreeGlobes se charge d'effectuer l'échappement du code en rajoutant un \n à chaque appel Buffer::str().

Note : Pour les interressés, la classe Buffer se trouve dans class/libs/lib.buffer.php.

Accessibilité des fonctionnalités de FreeGlobes

Dans le code du fichier index.php de votre plugin vous avez accès à l'ensemble des objets et classes déclarées dans le fichier admin/init.php (depuis la racine de votre script).

Conventions de codage

Référez-vous aux Conventions de codage pour en savoir plus.

functions.php : fonctions accessibles depuis les templates

Convention d'écriture

Ce fichier ne doit contenir que des fonctions et/ou des classes. Vous ne devez en aucun cas écriture du code PHP en dehors d'une fonction dans ce fichier. En effet, ce fichier est inclu par le moteur de Templates de FreeGlobes (Smarty) lors de la compilation du template.

L'objet de ce fichier est de contenir des fonctions qui pourront être appelées depuis le thème du site (contenu dans le dossier themes/ du script).

Exemple de fichier functions.php

<?php

/*
*	Displays PHP Version
*	call it in site's template with this tag : <{plugin name='info' call='displayPhpVersion'}>
*
*	@param void
*	@return string
*/
function displayPhpVersion($params = array())
{
	echo 'PHP Version : '.phpversion();
} 

// No php code should be written out of functions in this file
?>

Il s'agit du fichier functions.php du plugin "info". la fonction displayPhpVersion() permet d'afficher la version PHP du serveur sur votre site en insérant un tag Smarty expliqué ci-dessous.

Notes :

• Toutes les fonctions déclarés dans le fichier functions.php doivent avoir pour prototype :

maFonction($params = array())

Les paramètres spécifiés dans le template seront reçus dans le tableau $params, indexés de manière simple : 1er paramètre dans $params[0], 2nd paramètre dans $params[1] etc...

• On ne peut appeler que des fonctions depuis le template, on ne peut pas appeler une méthode d'une classe, même si cette dernière est en accès statique. Par exemple, on ne peut pas faire :

<{plugin name='info' call='MyClass::displayPhpVersion'}>

Appel d'une fonction d'un plugin depuis un template

L'appel d'une fonction d'un plugin depuis un template se fait par "inversion de contrôle" avec la balise Smarty suivante :

<{plugin name='nom_du_plugin' call='fonction_a_appeler' parameters="param1,param2"}>

Ce code est à insérer dans un fichier template de votre thème (par exemple, footer.tpl).

Voici la description détaillée de chaque attribut :

• Attribut name : nom du plugin dont on appelle la fonction.
• Attribut call : nom de la fonction à appeler présente dans le fichier functions.php du plugin.
• Attribut parameters : Paramètres à passer à la fonction, séparés par des virgules

Plugin Smarty d'appel de fonction d'un plugin

L'appel par inversion de contrôle d'une fonction d'un plugin FreeGlobes comme on l'a vu plus est géré par un plugin Smarty développé spécialement pour l'occasion : ce plugin se trouve dans class/smarty/plugins/function.plugin.php. (Pour les interressés)