Tutoriel plugins

Introduction

• être bilingue
• supporter les skins
• être valide HTML 5
• utiliser de préférence une base de données "fichier à plat"

Les types de plugins

Trois types de plugins sont possibles :

• Ceux de boites : ils affichent des données dans une ou plusieurs boites de GuppY, ils peuvent définir des boites d'entête, latérales, centrales secondaires et de pied de page.
• Ceux d'affichages principal : ils affichent des données dans la zone principale de GuppY.
• Ceux réservés à l'administration : il ne servent qu'à l'administrateur et ne sont pas accessibles au public. Un plugin peut être dans 1, 2 ou 3 des cas à la fois.

Les répertoires

Avec le système GuppY, il y a 4 emplacements où vous avez besoin de mettre des fichiers pour un plugin. Un pour les tâches d'administration, un pour la partie publique du plugin, un pour stocker les données et le dernier souvent omis mais cependant utile.

• admin/plugins/mon-plugin/ 
• plugins/mon-plugin/
• data/plugins/mon-plugin/
• documentation/plugins/mon-plugin/

Les fichiers

Premièrement un aperçu de tous les fichiers que nous allons créer pour notre plugin hello_world.

La partie administration

• admin/plugins/hello_world/index.php
• admin/plugins/hello_world/plugin.inc
• admin/plugins/hello_world/hello_world_admin.inc
• admin/plugins/hello_world/hello_world.png

La partie publique

• plugins/hello_world/index.php
• plugins/hello_world/plugin.inc
• plugins/hello_world/hello_world.png
• plugins/hello_world/hello_world_user.inc
• plugins/hello_world/lang/en-hello_world.inc
• plugins/hello_world/lang/fr-hello_world.inc

La partie documentation

Trop souvent négligée, elle doit être intégrée à votre plugin.
Les premiers documents à y placer  : les classiques lisezmoi.txt et readme.txt. Ne pas les mettre dans répertoire principal de GuppY, ils seraient fatalement écrasés par les fichiers d'autres plugins.

Ensuite, bien sûr un ou plusieurs documents pour expliquer l'installation (chmods) et le fonctionnement de votre plugin. Ces documents, de préférence au format .html, pourront être affichés à partir de l'administration du plugin.

• documentation/plugins/mon-plugin/
• documentation/plugins/mon-plugin/fr/
• documentation/plugins/mon-plugin/en/

La documentation dans les deux langues (ou plus) sera toujours appréciée.

La partie administration

Créer un sous répertoire hello_world dans le répertoire admin/plugins/.

Dans ce répertoire admin/plugins/hello_world/ nous allons mettre quelques fichiers.

1/ Commençons par le fichier index.php. Son contenu est :

<?php header('location:../index.php'); ?>

2/ Le second fichier est plugin.inc. Le contenu de ce fichier consiste en l'initialisation de plusieurs variables. Son contenu est :

<?php
// Sécurité
if (stristr($_SERVER['SCRIPT_NAME'], 'plugin.inc')) {
    header('location:../index.php');
    die();
}

// inclusion du fichier de langue
if (is_file(CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world.inc')) {
    include CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world.inc';
} else {
    include CHEMIN.'plugins/hello_world/lang/en-hello_world.inc';
}
// Nom du plugin
$plugin_admin_name = $world[6];
// Partie administration du plugin
$plugin_admin_url = 'hello_world/hello_world_admin';
// Icône du plugin dans la zone administration
$plugin_admin_icon = 'hello_world/hello_world.png';

// Structure pour la désinstllation propre du plugin
$plugin_datas_uninstall = array(
    'dirs' => array( 'plugins/hello_world',
    'data/plugins/hello_world',
    'documentation/plugins/hello_world',
    'admin/plugins/hello_world' ),
    'files' => array(),
    'include' => 'admin/plugins/hello_world/uninstall.inc',
    'function' => 'hw_uninstall' );

// Ajout de la boite latérale (une fonction qui ajoutera la boîte à la liste)
AddPluginBox($world[1], 'plugins/hello_world/hello_world_user', 'fbox_hello_word', BOX_LEFT.BOX_RIGHT); // boite latérale du plugin
?>

Voyons le détail de ce fichier :

– Le bloc Sécurité bloque l'appel direct du script, il doit être présent en début de tous les fichiers '.inc'

– Le lien vers le fichier de langue utilise la constante CHEMIN, permettant d'utiliser un chemin relatif à la racine du site pour l'inclusion. Il utilise aussi la variable $lng qui contient la langue en cours. Notez que le plugin doit être bilingue, il convient de tester la présence du fichier et si besoin c'est le fichier de langue anglaise qui sera chargé.

– $plugin_admin_name contient le nom du plugin qui sera affiché dans la console d'administration.

– $plugin_admin_url contient le chemin relatif vers l'administration du plugin depuis le répertoire /admin/plugins/ sans l'extension '.inc'.

– $plugin_admin_icon contient le chemin relatif depuis le répertoire /admin/plugins/ vers l'icône du plugin qui sera affiché dans la console d'administration.

– $plugin_datas_uninstall est une structure pour le désinstallation du plugin. La désinstallation est à la charge du concepteur qui est la personne la plus qualifiée pour réaliser une désinstallation propre. Cette structure n'est pas obligatoire mais fortement conseillée. Elle contient les items suivants :
    dirs : un tableau des répertoires à supprimer
    files : un tableau des fichiers à supprimer qui ne se situeraient pas dans les répertoires à désinstaller
    include : le nom du fichier qui contient la fonction de d"sinstallation
    function : le nom de la fonction qui exécutera la désinstallation

– AddPluginBox() permet d'ajouter la boîte latérale par l'intermédiaire de la fonction fbox_hello_world(), déclarée dans le script hello_world_user.inc. La variable $world[1] représente le titre de la boîte latérale.

Dans les variables, GuppY considère automatiquement que les deux URLs font référence à un fichier .inc, vous devez donc réfreiner votre envie d'ajouter l'extension de fichier.

3/ Avec le troisième fichier hello_world_admin.inc, vous pouvez configurer le plugin via la zone admin de GuppY.

Dans le plugin Hello_world, inclus avec cet article, nous vous montrons comment vous pouvez ajouter une icône, dans la barre de navigation, utilisable par les visiteurs pour activer le plugin. Cet exemple n'est pas la partie la plus simple du code du plugin hello_world, mais peut être très utile si vous souhaitez utiliser une icône dans la barre de navigation pour votre plugin. C'est juste un problème de copier/coller et changer un petit bout de code.

Dans le second fichier plugin.inc, vous avez vu que l'URL pour la partie administration pointe vers hello_world/hello_world_admin. Comme nous l'avons écrit plus haut, GuppY considère automatiquement que l'extension de ce fichier est .inc. Ainsi le nom du troisième fichier est hello_world_admin.inc.

Pour le contenu complet de ce fichier, référez-vous au plugin Hello_World joint.

Le contenu minimum d'un fichier pour configurer le plugin par la zone admin est :

<?php
// Sécurité
if (stristr($_SERVER['SCRIPT_NAME'], 'hello_world_admin.inc')) {
    header('location:../index.php');
    die();
}
// inclusion du fichier de langue
if (is_file(CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world.inc')) {
    include CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world.inc';
} else {
    include CHEMIN.'plugins/hello_world/lang/en-hello_world.inc';
}
// toujours commencer avec les 5 lignes suivantes
$topmess = '<a href="admin.php?lng='.$lng.'&amp;sid='.$sid.'">Admin</a> > '.str_replace('Admin - ', '', $world[0]);
include CHEMIN.'admin/hpage.inc';
// haut de page
htable($world[0], '100%'); // entête de boite centrale avec le nom du plugin
// inclusion du fichier d'entête de la page d'admin selon ses droits
if ($wri == 'admin') include CHEMIN.'admin/administrateur.php';
if ($wri == $userprefs[1]) include CHEMIN.'admin/adminredac.php';

//////////////////////////////////////////////////////
//  Votre code PHP et/ou HTML .. //
//////////////////////////////////////////////////////

// toujours terminer ce fichier par les lignes suivantes
// pas besoin de renvois à la page d'admin, dans la nouvelle structure, les onglets
// du menu déroulant linéaire sont toujours à votre disposition
btable(); // fin de boite admin
include CHEMIN.'admin/bpage.inc'; // colonne de droite et bas de page
?>

Notez les variables $world qui proviennent du fichier de langue.

Plus d'information sur le fichier de langue à la fin de cet article !

4/ Pour terminer il y a un quatrième fichier que vous trouvez aussi dans plugin.inc. C'est l'icône utilisée dans la zone administration pour ce plugin.
Appelée dans ce cas hello_world.png. Les icônes font 42*42 pixels.

La partie publique

Cette partie du plugin Hello_World traite la partie que les visiteurs de votre site web pourront voir.

Créez un sous répertoire hello_world dans le répertoire /plugins/.

1/ Nous commençons de nouveau avec le fichier index.php. Son contenu est :

<?php header('location:../index.php'); ?>

2/ Le second fichier est plugin.inc. Le contenu de ce fichier consiste en plusieurs variables. Son contenu est :

<?php
// sécurité
if (stristr($_SERVER['SCRIPT_NAME'], 'plugin.inc')) {
    header('location:../index.php');
    die();
}

define('CHEMIN', '../../');
// inclusion du fichier de langue
if (is_file(CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world.inc')) {
    include CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world.inc';
} else {
    include CHEMIN.'plugins/hello_world/lang/en-hello_world.inc';
}

// Nom du plugin
$plugin_bar_name = $world[1];
// Les deux lignes suivantes font références à des fichiers dans le répertoire plugin/hello_world/
// L'URL à activer quand on clic sur l'icône
$plugin_bar_url = 'hello_world.php';
// L'icône
$plugin_bar_icon = 'img/hello_world.png';
?>

Vous n'avez pas besoin de ce fichier si vous n'utilisez pas d'icône dans la barre de navigation !

Voyons le détail de ce fichier :

– define("CHEMIN", "../../") définit le chemin relatif pour retourner à la racine du site.

– $plugin_bar_name contient le nom qui sera affiché dans la barre de menu.

– $plugin_bar_url contient l'url relative au répertoire du plugin du fichier php contenant la page d'accueil publique du plugin, celle qui sera appelée lors du clic sur la barre de menu.

– $plugin_bar_icon contient l'url relative au répertoire du plugin de l'icône qui sera affiché dans la barre de menu.

3/ Le troisième fichier qui s'appelle hello_world_user.inc et déjà mentionné dans le fichier admin/plugins/hello_world.inc.

Ce fichier contient une fonction qui crée la boite latérale.

Pour le contenu complet de ce fichier, référez-vous au plugin Hello_World joint.

Le contenu minimum pour une boite latérale est :

<?php
// Sécurité
if (stristr($_SERVER['SCRIPT_NAME'], 'hello_world_user.inc')) {
    header('location:../index.php');
    die();
}

function fbox_hello_world($pos, $args) {
    // Déclaration des variables système nécessaires
    global $lng, $lang, $site, $serviz, $userprefs, $drtuser, $page, $tconfig, $reptheme, $web;
    // inclusion du fichier de langue
    include CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world.inc';
    // inclusion du fichier de configuration du plugin
    include CHEMIN.DATAREP.'plugins/hello_world/hello_world_config.inc';

    // La variable $out contient le code HTML de votre boîte
    $out = '
      <div style="text-align: center;padding: 12px;">
        <a href="'.CHEMIN.'plugins/hello_world/hello_world.php?lng='.$lng.'" title="hello_world" />Hello !</a>
      </div>';

    // Mettre l'icône d'administration rapide
    if (($serviz[32] == 'on' && !empty($serviz[31]) && ($serviz[31] == $userprefs[1]) || $serviz[32] == 'on' && $drtuser['hello_world'] == 'on')) {
        $out .= '
          <div class="f-right">'.displayQuickConfig($pos).'
            <a href="'.CHEMIN.'admin/admin.php?lng='.$lng.'&pg=plugin&plug=hello_world/hello_world_config&amp;sid='.$sid.'" title="">
              <img alt="'.$web[308].'" src="'.$reptheme.'/edit.png" style="border:0;" title="'.$web[308].'" />
            </a>
          </div><div class="c-right"></div>';
    }
    // Terminer la fonction pour une boite latérale par cette ligne
    return boxthin($pos, $world[1], $out, ' H_W'.$tconfig, $hwdynabox);
} // fin de la fonction
?>

La boite latérale doit être activée dans Admin > Configurations > Config boites !

Voyons le détail de ce fichier :

– function fbox_hello_world($pos, $args), l'exécution de cette fonction affichera la boîte latérale hello_world, les paramètres de la fonctions, $pos donne la position de la boîte dans la structure de la page, $args contient les arguments passés à la fonction, ils sont transmis par la fonction d'exécution du moteur de GuppY.

– global : à l'intérieur d'une fonction les variables globales ne sont pas visibles, il convient donc de les déclarer. Par exemple $lng qui contient la langue utilisée doit être visible pour charger le fichier de langue du plugin.

– $out est la variable qui contient le code HTML 5 affiché dans la boîte. Elle sera transmise à la fonction boxthin() qui se charge elle d'afficher la boîte entière, titre et contenu.

– if (($serviz[32] == .... , ce code a pour rôle d'afficher en bas à droite de la boîte les petites icônes d'administration rapide

– return boxthin() on retourne toute la boîte mise en forme grâce aux paramètres fournis, $pos est la position de la boîte, $world[1] est le titre de la boîte, $out est le contenu de la boîte, ' H_W' est le nom d'une pseudo classe qui peut servir à personnaliser la boîte, $tconfig est une variable globale qui définit le numéro de la page d'affichage et enfin $hwdynabox un paramètre de configuration définissant le statut de la boîte (ouverte, fermée, statique). Ce dernier paramètre sera défini en admin dans la configuration du plugin

4/ Le quatrième fichier est hello_world.php qui sera activé par l'icône du plugin dans la barre de navigation (si présente). Ce fichier sera aussi activé par un lien dans la boite latérale.

Le but est que la sortie de ce fichier soit affichée dans la partie centrale d'une page.

Le contenu ressemble à cela :

<?php
/* Sécurité
* Cette fois pas de code de sécurité (4 lignes)
* que vous avez vu dans tous les autres fichier .php et .inc
* parce que ce fichier .php est appelé par un lien direct.
*/
// Commencez avec les lignes suivantes pour afficher la sortie dans une boite centrale

header('Pragma: no-cache');
define('CHEMIN', '../../');
include CHEMIN.'inc/includes.inc';
include CHEMIN.'inc/medias.inc';
$false = false;
foreach ($medias as $media) if (strstr(strtoupper($_SERVER["HTTP_USER_AGENT"]), $media)) $false = true;
if (!$false) @session_set_cookie_params(0, '/', $_SERVER['HTTP_HOST'], false, (is_ssl() ? true : false));
@session_name('GuppYSite');
@session_start();

include CHEMIN.'inc/hpage.inc';
// inclusion du fichier de langue
include CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world.inc';
// Entête de boite
htable($world[1], '100%');

// Votre code PHP et/ou HTML
echo '<h3>Hello World</h3>';

// Terminez toujours par les lignes suivantes
btable();
include $CHEMIN.'inc/bpage.inc';
?>

Le code exemple est juste une ligne d'XHTML. Ce que vous verrez souvent ici est l'utilisation de code PHP, XHTML et CSS.

Voyons le détail de ce fichier :

– header('Pragma: no-cache') pour ne pas mettre en cache la page, cas d'une page dynamique.

– include CHEMIN.'inc/includes.inc' chargement du moteur de GuppY.

– Les autres éléments ont déjà été vus auparavant.

5/ Une des fonctions sympa de GuppY, c'est de pouvoir l'utiliser en bilingue. Cela signifie qu'il est important de rendre vos plugins facilement traduisibles et faciles à utiliser en bilingue. Pour le rendre bilingue, nous avons ajouté la ligne suivante dans le code dont nous avons parlé plus tôt :

// inclusion du fichier de langue
include CHEMIN.'plugins/hello_world/lang/'.$lng.'-hello_world-web.inc';

La variable $lng contient le code de langue. Par exemple : si votre site est en français le nom du fichier est fr-hello_world.inc. Le fichier de langue contient des variables. Ces variables sont utilisées dans le code du plugin. Pour rendre le plugin utilisable dans d'autres langues, nous devons seulement renommer le fichier de langue et traduire le contenu des variables.

Par exemple : pour traduire le plugin en espagnol, nous dupliquons et renommons le fichier en es-hello_world.inc et
traduisons le contenu des variables.

Le fichier de langue du plugin Hello_World contient :

<?php
// sécurité
if (stristr($_SERVER['SCRIPT_NAME'], 'fr-hello_world.inc')) {
    header('location:../index.php');
    die();
}
// Variables de langue utilisées par le plugin Hello_World
$world[0] = 'Admin - Plugin Hello World';
$world[1] = 'Hello World';
$world[2] = 'Mettre l'icône 'Hello World' dans la barre de navigation';
$world[3] = 'Mettre ici le code pour les taches d'administration (si
nécessaire)';
$world[4] = 'Mettre ici le code pour la partie visiteurs (si nécessaire)';
$world[5] = 'Cliquez ici';
$world[6] = 'Désinstaller le plugin';
?>

Il est conseillé de faire un sous-répertoire lang/ pour séparer ces fichiers des autres et faciliter leur repérage par les traducteurs.

Sur des gros plugins, vous pouvez séparer le fichier de langue en 2, un postfixé 'admin' et un autre postfixé 'web' pour respectivement les parties administration et publique du plugin.

6/ Pour terminer il y a un sixième fichier que vous trouvez aussi dans plugin.inc. C'est l'icône utilisée dans la barre de navigation et appelé hello_world.png. Les icônes font 42*36 pixels. Cela peut être la même icône que celle utilisée dans la zone admin. Vous n'avez pas besoin de ce fichier si vous n'utilisez pas d'icône pour ce plugin dans la barre de navigation ni dans la boite centrale !

7/ Points à considérer.

• Pour chaque fichier .inc et .php de votre plugin, commencez directement après le premier <?php avec des lignes de commentaires signalant le nom du plugin, la licence de distribution, l'auteur, votre site web... :

  /*
Plugin : Nom du plugin
Licence : CeCILL
Name : votre nom ou pseudo
Website : votre site web (pour le support)
N'ajoutez pas votre courriel pour éviter le spam!
Commentaires utiles sur les modifications du fichier
*/

• Ajoutez une documentation claire à propos de l'objectif du plugin, comment l'installer (CHMOD) et comment le configurer.

• Une fois terminé, soumettez votre plugin aux bêta-testeurs. Rien ne vaut l'avis des utilisateurs.

• Une fois validé et vérifié, annoncez-le sur FreeGuppY et soumettez-le sur GuppYLand.

Aller plus loin

Naviguer dans un plugin comportant plusieurs pages

Pour accéder à une page d'administration d'un plugin, on passe toujours par admin.php (qui gère les droits d'accès) en lui passant 2 paramètres :

– pg qui contient la valeur 'plugin', pour dire que l'on accède à un plugin,

– plugin qui contient le chemin relatif vers la page d'administration du plugin depuis le répertoire /admin/plugins/ sans l'extension '.inc'.

Si l'on reprend l'exemple du plugin "hello_world", l'adresse de la page d'administration du plugin est la suivante dans du html :

echo CHEMIN.'admin/admin.php?lng='.$lng.'&pg=plugin&plug=hello_world/hello_world_admin&sid='.$sid;

Définir plusieurs boites latérales et centrales

Pour faire cela, il va falloir modifier le fichier admin/plugins/mon-plugin/plugin.inc.

Créer un fichier .inc dans plugins/mon-plugin/ par boite, par exemple my_first_box.inc, my_second_box.inc, etc.

Chaque fichier .inc contiendra la fonction correspondante, fbox_my_first_box($pos, $args) pour le premier fichier, fbox_my_second_box($pos, $args), et ainsi de suite.

La prise en charge de ces boîtes se fera dans le fichier admin/plugins/mon_plugin/plugin.inc avec les déclarations suivantes :

AddPluginBox($box_name[1], 'plugins/mon_plugin/my_first_box', 'fbox_my_first_box', BOX_LEFT.BOX_RIGHT);
AddPluginBox($box_name[2], 'plugins/mon_plugin/my_second_box', 'fbox_my_second_box', BOX_LEFT.BOX_RIGHT);
etc.

Notez que BOX_LEFT.BOX_RIGHT indique que l'utilisation de la boîte sera possible uniquement dans les colonnes droite et gauche. Il est possible de l'écrire comme ceci : 'LR'.

Pour rendre la boîte disponible dans tous les emplacements d'une page, il faudrait indiquer 'LRAEUTB', ou en utilisant les constantes prédéfinies.

Ajouter le plugin dans la barre de menu

Exemple du plugin hello_world

<?php
// intégration des fonctions nécessaires
include 'plugins/funcplug.inc';
// Cette partie sauve l'état du plugin dans la barre de menu
// Les 3 occurrences de "hello_world" correspondent au nom du répertoire du plugin
$regit = import('regit');

if ($regit == 1) {
    $hello_world = import('hello_world');
    $iconexec = import('iconexec');
    $icondisp = import('icondisp');
    if ($hello_world == 'on') {
        if (!PluginRegistered('hello_world')) RegisterPlugin('hello_world', $iconexec, $icondisp);
    }
    else UnregisterPlugin('hello_world');
}

// Formulaire pour (des)inscrire le plugin
echo '
<form name="hello_world" action="admin.php?lng='.$lng.'&pg=plugin&plug=hello_world/hello_world_admin&amp;sid='.$sid.'" method="post">
  <input type="hidden" name="regit" value="1" />
  <select style="max-width:180px; margin-top:4px;" name="iconexec">
    <option value="ALL"'.Selected($iconexec == 'ALL').'>'.$admin[1363].'</option>';
foreach ($templates as $key=>$val) {
  echo '<option value="'.$key.'"'.Selected($iconexec != 'ALL' && $iconexec == $key).'>'.$key.' - '.$val.'</option>';
}
echo '
  </select>
  <select style="max-width:180px; margin-top:4px;" name="icondisp">
    <option value="ALL"'.Selected($icondisp == 'ALL').'>'.$admin[1363].'</option>';
foreach ($templates as $key=>$val) {
  echo '<option value="'.$key.'"'.Selected($icondisp != 'ALL' && $icondisp == $key).'>'.$key.' - '.$val.'</option>';
}
echo '
  </select>
  <p>'.$world[2].'&nbsp;&nbsp;<input type="checkbox" name="hello_world"'.Checked(PluginRegistered('hello_world')).' /></p>  <p style="text-align:center;">'.SubmitButton($admin[66]).'</p>
</form>';
?>

Voyons le détail de ce code :

– include 'plugins/funcplug.inc' permet d'avoir accès aux fonctions PluginRegistered(), RegisterPlugin() et UnregisterPlugin()

– si le formulaire est validé ($regit == 1) on lit le contenu de $hello_world

– si la case est cochée ($hello_world == 'on') alors si le plugin n'est pas déjà inscrit (!PluginRegistered('hello_world'))
on l'inscrit RegisterPlugin('hello_world');

– sinon on le désinscrit UnregisterPlugin('hello_world');

– notez dans le formulaire l'utilisation de la fonction Checked() qui affichera si besoin checked="checked", de même la fonction SubmitButton() qui affiche le bouton du formulaire.

Insérer l'éditeur de texte

Nous allons voir comment intégrer dans l'administration d'un plugin l'éditeur avancé de GuppY.

Affichage de l'éditeur dans un formulaire

1/ Pour commencer, il faut insérer les fonctions nécessaires et stocker les drapeaux réutilisables devant les champs du formulaire.

<?php
require CHEMIN.'admin/editors/editors_functions.php';
$flag1 = '<img src="'.CHEMIN.INCREP.'lang/'.$lang[0].'.gif" style="vertical-align:middle;border:0;" alt="'.$lang[0].'" />';
$flag2 = '<img src="'.CHEMIN.INCREP.'lang/'.$lang[1].'.gif" style="vertical-align:middle;border:0;" alt="'.$lang[1].'" />';
$wysiwyg = $serviz[49] == 'on' ? true : false;

2/ Puis nous allons afficher le formulaire avec l'éditeur dans 1 ou 2 langues en fonction de la configuration de GuppY.

echo '
<form name="adminsend" action="admin.php?lng='.$lng.'&amp;sid='.$sid.'" method="post">
  <input type="hidden" name="pg" value="plugin" />
  <input type="hidden" name="plug" value="mon-plugin/monplugin" />
  <input type="hidden" name="regit" value="1" />';
// Langue principale
echo '
  <div style="text-align: center; margin: auto; width: 560px;">
    <label for="contenu1">'.$flag1.' Texte en langue principale</label><br />
    '.display_admin_editor('contenu1', '540px', '400px', $contenu1, $wysiwyg).'
    <p style="text-align: center;">'.SubmitButton($admin[66]).'</p>
  </div>';
if ($lang[1] != '') {
// Langue secondaire
   echo '
  <div style="text-align: center; margin: auto; width: 560px;">
    <label for="contenu1">'.$flag2.' Texte en langue secondaire</label><br />
    '.display_admin_editor('contenu2', '540px', '400px', $contenu2, $wysiwyg).'
    <p style="text-align: center;">'.SubmitButton($admin[66]).'</p>
  </div>';
}
echo '
</form>';
?>

Voyons le détail de ce code :

– require on charge la libraire qui contient toutes les fonctions nécessaires de l'éditeur

– $flag1, $flag2, ces deux variables contiennent les images de lanque du site

– $wysiwyg récupère le choix de l'éditeur ("on" par défaut)

– le formulaire est classique en admin, on affiche le drapeau de langue associé à un label, suivi de l'appel à la fonction

– display_admin_editor() est donc cette fonction d'affichage de l'éditeur, qu'il soit WYSIWYG ou non
    'contenu1' est le nom de la variable donnée en retour
    suivent la largeur et la hauteur de l'éditeur en pixels
    $contenu1 contient le texte à éditer
    et enfin $wysiwyg qui déterminera l'éditeur à utiliser, CKEditor ou un textarea

– if ($lang[1] != '') on teste si une langue secondaire est présente, puis on affiche une seconde fois l'éditeur avec les valeurs correspondantes

Traitement des données du formulaire

Avec CKeditor nous transformons les chemins relatifs en absolus. Mais avant le stockage des données, il faut faire l'opération inverse.

if ($regit == 1) {
    $text1 = import('contenu1');
    $text2 = import('contenu2');
    $text1 = PathAbsoluteRelative($text1);
    $text2 = PathAbsoluteRelative($text2);
    $txt   = "<?php
$contenu1 = stripslashes("$text1");
$contenu2 = stripslashes("$text2");
";
    WriteFullDB(CHEMIN.DATAREP.'plugins/mon_plugin/contenu.inc', $txt);
}

Voyons le détail de ce code :

– if ($regit == 1) $regit est passé par le formulaire

– $text1, $text2, on récupère et on formate les valeurs

– PathAbsoluteRelative transforme les chemins absolus en relatifs.

Afficher les textes

Les textes sont sauvegardés avec des chemins relatifs par rapport à la racine du site. Donc les images et liens ne fonctionnent pas quand la page où s'affiche le texte est plugins/mon-plugin/monplugin.php.

Pas de soucis, GuppY a une fonction pour rétablir correctement les chemins relatifs. Il suffit de faire :

echo PathToImage($contenu1);

Désinstaller le plugin

Pour le plugin hello_world nous allons réaliser la désinstallation dans le script admin/plugins/hello_world/hello_world_admin.inc.

Ajoutons un petit formulaire pour lancer la désinstallation :

if (isset($plugin_datas_uninstall)) {
    echo '
<hr />
<div style="width:480px;text-align:center;margin:auto;">
  <form name="uninstall" action="admin.php?lng='.$lng.'&amp;pg=plugin&amp;plug=hello_world/hello_world_admin&amp;sid='.$sid.'" method="post">
  <input type="hidden" name="regit" value="unplug" />
  <p style="text-align:center;">'.SubmitButton($world[6]).'</p>
  </form>
</div>';
}

Voyons le détail de ce code :

– if (isset($plugin_datas_uninstall)) on teste l'existence de la structure de désinstallation déclarée dans admin/plugins/hello_world/plugin.inc

– on affiche le formulaire qui ne comporte que le bouton de soumission

Ensuite il faut traiter la demande :

if ($regit == 'unplug') {
    $dirs  = $plugin_datas_uninstall['dirs'];
    $files = $plugin_datas_uninstall['files'];
    foreach ($dirs as $dir) RecursiveRemoteDir(CHEMIN.$dir);
    foreach ($files as $file) @unlink(CHEMIN.$file);
    echo BeginJavascript().'
window.location="admin.php?lng='.$lng.'&sid='.$sid";
'.EndJavascript();
}

Ressources

Vous êtes arrivé au terme de ce tutoriel sur un exemple très simple. Vous disposez des principaux éléments qui vous permettront de créer votre propre plugin pour GuppY version 5.0.

Quand votre plugin est au point, c'est le moment de créer un une archive .zip, avec le fichier Manifest qui permettra aux utilisateurs de GuppY version 5.0.x de l'installer directement en ligne avec la fonction admin > Administration générale > Installer.

L'utilitaire mkZip, créé par JeanMi, pour créer votre archive .zip est à votre disposition à la fin de cet article. Installez-le sur votre disque dur. Il suffira de lancer le script mkzip.php et de remplir les champs nécessaires.

Où trouver des plugins ?

GuppYLand, le site à visiter absolument : https://www.guppyland.org/index.php?lng=fr

Licence CeCILL

L'intégralité du manuel est soumise à la CeCILL License, ce qui signifie :

• que toute personne a le droit d'utiliser librement le manuel.
• que toute personne est autorisée à diffuser le manuel.

Le logiciel GuppY est soumis à la licence CeCILL. Vous trouverez plus de détails à son propos ici :

https://ghc.freeguppy.org/articles.php?lng=fr&pg=542&mnuid=422&tconfig=0

Lien pour le téléchargement du plugin Hello World :   

Lien pour le téléchargement de l'utilitaire mkZip :