Créer un plugin

Le rôle des plugins est d’ajouter des fonctionnalités à PhpWebGallery. Depuis la version 1.7 l’installation se fait via l’interface d’administration et non en éditant les fichiers comme avant. Nous allons réaliser un plugin qui n’apporte rien de particulier à PhpWebGallery mais qui montre les différentes possibilités de ce nouveau système. Dans le répertoire plugins/ créez un sous-répertoire test/.

Corps principal (main.inc.php)

Dans le répertoire créez un fichier qui s’appelle main.inc.php. Editez ce fichier et copiez ceci :

<?php
/*
Plugin Name: Plugins de test
Version: 0.1
Description: Permet le test de création de plugin
Plugin URI: http://www.phpwebgallery.net
*/
if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');
?>

Explications :

<?php –> marque le début d’un fichier écrit en php
Plugin Name –> nom du plugin affiché dans l’interface d’administration des plugins
Version –> version de plugin affichée dans l’interface d’administration des plugins
Description –> descriptif du plugin affiché dans l’interface d’administration des plugins
Plugin URI –> lien pour afficher le site du plugin ou de son concepteur
Dernier if –> empêche l’accès direct au fichier main.inc.php; nécessaire pour la sécurité
?> –> marque la fin d’un fichier écrit en php

Maintenant vous pouvez vous rendre dans l’interface d’administration des plugins et admirer votre premier résultat. Les plugins utilisent les classes php pour fonctionner.

Transformez votre fichier de cette manière.

01:<?php
02:/*
03:Plugin Name: Plugins de test
04:Version: 0.1
05:Description: Permet le test de création de plugin
06:Plugin URI: http://www.phpwebgallery.net
07:*/
08:if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');
09:class TestPlugin
10:{
11:    var $my_config;
12:}
13:
14:$obj = new TestPlugin();
15:?>

09 –> nommage de la classe
11 –> création d’une variable globale pour la configuration
14 –> création de la classe

A ce stade nous pouvons appeler notre plugin par la classe TestPlugin.
Maintenant nous allons voir comment utiliser un fichier de configuration (data.dat). Modifiez votre fichier pour qu’il ressemble à ça.

<?php
/*
Plugin Name: Plugins de test
Version: 0.1
Description: Permet le test de création de plugin
Plugin URI: http://www.phpwebgallery.net
*/
if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');
class TestPlugin
{
    var $my_config;
    function load_config()
    {
        $x = @file_get_contents( dirname(__FILE__).'/data.dat' );
        if ($x!==false)
        {
            $c = unserialize($x);
            // do some more tests here
            $this->my_config = $c;
        }
 
        if ( !isset($this->my_config)
            or empty($this->my_config['TestPlugin1']) )
        {
            $this->my_config['TestPlugin'] = 'blabla';
            $this->save_config();
        }
    }
    function save_config()
    {
        $file = fopen( dirname(__FILE__).'/data.dat', 'w' );
        fwrite($file, serialize($this->my_config) );
        fclose( $file );
    }
}
$obj = new TestPlugin();
?>

La fonction load_config() gère les variables utilisées pour la configuration et définit les paramètres par défaut à la première utilisation du plugin. La partie la plus importante est ce bloc :

        if ( !isset($this->my_config)
            or empty($this->my_config['TestPlugin1']) )
        {
            $this->my_config['TestPlugin'] = 'blabla';
            ...
            $this->save_config();
        }

Si vous voulez ajouter une valeur dans votre fichier de configuration il suffit d’ajouter une ligne comme ceci

        if ( !isset($this->my_config)
            or empty($this->my_config['TestPlugin']) )
        {
            $this->my_config['TestPlugin1'] = 'blabla';
            $this->my_config['TestPlugin2'] = 'ma deuxieme variable';
            $this->save_config();
        }

La fonction save_config() sert uniquement à écrire la configuration dans le fichier data.dat. Il n’y a rien à modifier. Il ne nous reste plus qu’a faire un joli écran pour pouvoir modifier ces valeurs.

Transformez le fichier de cette manière.

<?php
/*
Plugin Name: Plugin de test
Version: 0.1
Description: Permet le test de création de plugin
Plugin URI: http://www.phpwebgallery.net
*/
if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');
class TestPlugin
{
    var $my_config;
    function load_config()
    {
        $x = @file_get_contents( dirname(__FILE__).'/data.dat' );
        if ($x!==false)
        {
            $c = unserialize($x);
            // do some more tests here
            $this->my_config = $c;
        }
 
        if ( !isset($this->my_config)
            or empty($this->my_config['TestPlugin']) )
        {
            $this->my_config['TestPlugin'] = 'blabla';
            $this->save_config();
        }
    }
    function save_config()
    {
        $file = fopen( dirname(__FILE__).'/data.dat', 'w' );
        fwrite($file, serialize($this->my_config) );
        fclose( $file );
    }
    function plugin_admin_menu($menu)
    {
        array_push($menu,
            array(
                'NAME' => 'Test PlugIn',
                'URL' => get_admin_plugin_menu_link(dirname(__FILE__).'/admin/testplugin_admin.php')
            )
        );
        return $menu;
    }
}
$obj = new TestPlugin();
$obj->load_config();
 
add_event_handler('get_admin_plugin_menu_links', array(&$obj, 'plugin_admin_menu') );
set_plugin_data($plugin['id'], $obj)
?>

La fonction plugin_admin_menu() permet l’ajout dans la barre de menu d’administration d’une entrée dans la section Plugin. add_event_handler() indique où ajouter ce menu.

Menu administrateur

Nous allons créer un écran qui permet la lecture et la modification des deux variables définies dans le fichier main.inc.php.

Pour cela nous allons utiliser deux fichiers, admin/testplugin_admin.php et admin/testplugin_admin.tpl

Toujours dans le répertoire de votre plugin, créez un sous-répertoire admin/ puis un fichier testplugin_admin.php.

Editez testplugin_admin.php et ajoutez :

<?php
if (!defined('PHPWG_ROOT_PATH')) die('Hacking attempt!');
 
$me = get_plugin_data($plugin_id);
 
global $template;
$template->set_filenames( array('plugin_admin_content' => dirname(__FILE__).'/testplugin_admin.tpl') );
 
$template->assign_var('TESTPLUGIN_VAR1', $me->my_config['TestPlugin1']);
$template->assign_var('TESTPLUGIN_VAR2', $me->my_config['TestPlugin2']);
 
$template->assign_var_from_handle( 'ADMIN_CONTENT', 'plugin_admin_content');
?>

Ce fichier n’a rien de compliqué mais avant d’aller plus loin je vous conseille de lire la documentation sur les Templates. Créez un fichier dans le répertoire admin, nommé testplugin_admin.tpl. Ajoutez le code suivant:

<div class="titrePage">
  <h2>Test PlugIn</h2>
</div>
<p>
Configuration de Test PlugIn
</p>
<form method="post" action="{TESTPLUGIN_F_ACTION}" class="general">
<fieldset>
	<legend>Test PlugIn</legend>
    <label>Variable 1 du fichier de configuration
	   <input type="text" name="testplugin_var1" value="{TESTPLUGIN_VAR1}" />
    </label>
    <br/>
    <label>Variable 2 du fichier de configuration
	   <input type="text" name="testplugin_var1" value="{TESTPLUGIN_VAR2}" />
    </label>
</fieldset>
 
<p><input type="submit" value="Enregistrer" /></p>
</form>

Maintenant vous pouvez installer et activer votre plugin. Un nouveau lien est apparu dans la barre de menu. Cliquez dessus pour voir l’écran que vous venez de créer.

Merci à FlipFlip pour ce tutoriel

Modifier les fonctions en utilisant les triggers

Préambule

Cette partie s’adresse à des personnes avertis car nous allons modifié les fonctions de base de PhpWebGallery donc la galerie peut être instable (plus, d’affichage, message d’erreur...) si notre modification n’est pas adéquat. Cependant, en désinstallant le plugin tout devrait rentrer en ligne en cas de soucis...

Les Triggers quesako ?

Dans les fonctions de PhpWebGallery nous trouvons dans la plupart des cas des triggers de la forme :

 
function nom_fonction_native($parametres)
  
  //Calcul du parametre à retourner $paramreturn
 
  return trigger_event('nom_evenement', $paramreturn, $parametres_suplementaires)
 
}

En fait, cela permet soit

de retourner $paramreturn calculé dans la fonction
de retourner ce qui est retourné par une fonction d’un plugin

Utilisation des triggers dans les plugin

Chaque trigger est associé à un nom d’évenement qui peut être associer à une fonction dans un plugin grâce au code suivant dans main.inc.php :

add_event_handler('nom_evenement','nom_fonction_plugin');

Remarque si l’on veut pouvoir utiliser les paramètres supplémentaires dans la fonction du pluggin il faut rajouter le nombre de paramètres à prendre en compte

add_event_handler('nom_evenement','nom_fonction_plugin', priority=EVENT_HANDLER_PRIORITY_NEUTRAL, $accepted_args=nb_params);

La fonction nom_fonction_plugin en question

pourra utiliser les $paramreturn et $parametres_suplementaires du trigger
devra retourner la nouvelle valeur de $paramreturn

function nom_fonction_plugin($paramreturn, $parametres_suplementaires)
{
  //Calcul de la nouvelle valeur à retourner $newparamreturn
  return $newparamreturn
}

Remarque : si la fonction fait partie d’une class l’association se fera de cette sorte :

//instanciation de la class 
$nom_obj = new NomClass();
//association
add_event_handler('nom_evenement',array(&$nom_obj, 'nom_fonction'));

Attention : l’association doit bien être en dehors de la class.