Aide à la création de plugins

Cette documentation, bien que toujours valide, repose sur des principes complexes dont on peut se passer pour créer un plugin.
Nous vous invitons à consulter la documentation anglaise et le code source du plugin Skeleton dont le but est de montrer par l'exemple ce qu'il est possible de faire.

Fiche


Niveau de difficulté : Expert.
Recommandations : Voir la page.
A lire aussi : [Exemple] Faire son plugin personnel


Inspirez-vous aussi des plugins déjà existants.

Généralités

Les plugins pour la branche 1.7 ont été numérotés 1.7.a, 1.7.b, et les plugins pour la branche 2.0 sont numérotés 2.0.a, 2.0.b, 2.0.c, etc.

On supprimera les anciennes révisions d'une même branche (1.7.c ou 1.7.b supprimeront 1.7.a).

A une demande d'assistance reposant sur une ancienne version d'une même branche, ce qui n'arrive jamais, il conviendra de répondre : mise à jour, svp.

La mise à jour est si simple à faire avec le plugin manager (en 1.7, en standard depuis Piwigo) qu'il n'y a aucune raison de perdre du temps avec une révision dont le contexte est devenu obsolète.

Plus encore supprimez les sources des plugins des anciennes branches pour que les utilisateurs passent le moment venu en Piwigo ou versions ultérieures (6 mois de tolérance, puis suppression sans le moindre remord).

Ce principe est voulu pour améliorer les performances du Gestionnaire des Plugins.

:!: À partir de la version 1.7 :!:

Créer un plugin

Le rôle des plugins revient à rajouter des fonctionnalités à Piwigo. 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 à Piwigo 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 : Plugin 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['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 );
    }
}
$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['TestPlugin']) )
        {
            $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['TestPlugin1']) )
        {
            $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['TestPlugin1']) )
        {
            $this->my_config['TestPlugin1'] = 'blabla';
            $this->my_config['TestPlugin2'] = 'ma deuxieme variable';
            $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);
 
if (isset($_POST['submit']))
{
  $me->my_config['TestPlugin1'] = $_POST['TESTPLUGIN_VAR1'];
  $me->my_config['TestPlugin2'] = $_POST['TESTPLUGIN_VAR1'];
  $me->save_config();
}
 
global $template;
$template->set_filenames( array('plugin_admin_content' => dirname(__FILE__).'/testplugin_admin.tpl') );
 
$template->assign('TESTPLUGIN_VAR1', $me->my_config['TestPlugin1']);
$template->assign('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_VAR2" value="{$TESTPLUGIN_VAR2}" />
    </label>
</fieldset>
 
<p><input type="submit" value="Enregistrer" name="submit" /></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 averties car nous allons modifier les fonctions de base de Piwigo, donc la galerie peut être instable (plus d'affichage, messages d'erreur …) si notre modification n'est pas adéquate. Cependant, en désinstallant le plugin tout devrait rentrer en ligne en cas de soucis …

Les triggers késako ?

Dans les fonctions de Piwigo, 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 plugins

Chaque trigger est associé à un nom d'événement, qui peut être associé à 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 plugin, 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_supplémentaires du trigger
  • devra retourner la nouvelle valeur de $paramreturn
function nom_fonction_plugin($paramreturn, $parametres_supplementaires)
{
  //Calcul de la nouvelle valeur à retourner $newparamreturn
  return $newparamreturn
}

Remarque: si la fonction fait partie d'une classe, l'association se fera ainsi :

//instanciation de la classe 
$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 classe.

Déclarer un sous-répertoire pour les templates

Pour aller plus loin...


Retrouvez le contenu de cette section grâce à ce mini sommaire:



MERCI DE NE PAS TOUCHER AUX LIGNES QUI SUIVENT.

 
Haut de page
projet/developpement/plugins.txt · Dernière modification: 2014/06/09 19:34 par mistic100
 
 
github twitter facebook google+ newsletter Faire un don Piwigo.org © 2002-2017 · Contact