Gepi

h1. Coder un plugin pour GEPI

* Chaque plugin est stocké dans un sous-dossier du dossier *mod_plugins* de GEPI. Le nom du dossier du plugin, défini dans le fichier *plugin.xml*, ne comporte ni point ni accent, et les espaces sont remplacés par des tirets bas "_".

* La mise en fonction d'un plugin consiste à copier son dossier dans le dossier *mod_plugins*, puis en mode administrateur (Gestion des modules/Gérer les plugins) à "installer" et à "ouvrir" le plugin (un plugin peut être "installé" sans nécessairement être ouvert).

* Chaque plugin contient un fichier de paramétrage *plugin.xml* utilisé lors de son "installation" et de sa "désinstallation".

* La gestion des droits est assurée par une méthode verifDroits() (propre au module Plugins) qui consulte la table *plugins_autorisations*, et éventuellement cette gestion est complétée par la fonction *calcul_autorisation_...()*.

* Les tables de la base GEPI utilisées par le module Plugins sont *plugins* (liste des plugins présents), *plugins_menus* (page d'accueil et barre de menu) et *plugins_autorisations*.

* Un plugin ne doit pas modifier la structure des tables GEPI, et doit, lors de sa désinstallation, replacer GEPI (tables et fichiers) dans l'état où il se trouvait lors de son installation.

h2. Structure et contenu du fichier *plugin.xml*

Ce fichier, obligatoirement encodé en UTF-8 (sauf s'il ne comporte que des caractères ASCII 7 bits), est lu lors de l'installation ou de la désinstallation du plugin (Gestion des modules/Gérer les plugins).

<pre><code class="xml">

<?xml version="1.0" encoding="UTF-8"?>

<gepinstall type="plugin">

	<!-- nom du dossier contenant les fichiers du plugin -->

	<nom>plugin_example</nom>

	<creationDate>02 2012</creationDate>

	<auteur>A. Turing</auteur>

	<licence>GNU/GPL</licence>

	<auteurCourriel>at@gepi.com</auteurCourriel>

	<auteurSite>www.at.fr</auteurSite>

	<version>1.0</version>

	<versiongepi>1.5.5</versiongepi>

	<description>Plugin example</description>

	<installation>

		<!-- requêtes SQL exécutées à l'installation du plugin -->

		<requetes>

			<requete>

			CREATE TABLE IF NOT EXISTS `plugin_example` (

			  `id_plugin_example` int(11) NOT NULL AUTO_INCREMENT,

			  `login` varchar(50) NOT NULL,

			  `nom` varchar(50) NOT NULL,

			  `prenom` varchar(50) NOT NULL,

			  PRIMARY KEY (`id_plugin_example`),

			  UNIQUE KEY `login` (`login`)

			) ENGINE=MyISAM ;

			</requete>

		</requetes>

	</installation>

	<desinstallation>

		<!-- requêtes SQL exécutées à la désinstallation du plugin -->

		<requetes>

			<requete>

			DROP TABLE `plugin_example`;

			</requete>

		</requetes>

	</desinstallation>

	<administration>

		<fichier>

		<!-- les autorisations qui suivent, portant sur le satut de l'utilisateur, peuvent être

		confirmées/affinées dans la fonction calcul_autorisation_plugin_example() du fichier

		functions_plugin_example.php -->

			<nomfichier autorisation="A-P-C-S-sec-autre-E-R">index.php</nomfichier>

			<nomfichier autorisation="A">admin.php</nomfichier>

			<nomfichier autorisation="A">autre_script.php</nomfichier>

		</fichier>

		<menu>

		<!-- liste des accès aux scripts du plugin apparaissant sur la page d'accueil et dans

		la barre de menu, si la fonction  calcul_autorisation_plugin_example() est définies ces

		accès doivent y être confirmés et éventuellement affinés -->

			<item autorisation="A-P-C-S-sec-autre-E-R" titre="Utiliser" description="Description du script">index.php</item>

			<item autorisation="A" titre="Administrer" description="Administration du plugin">admin.php</item>

		</menu>

	</administration>

</gepinstall>

</code></pre>

h2. Structure d'un script PHP de plugin

<pre><code class="php">

<?php

$niveau_arbo = "2";

// Fichiers d'initialisation

// (attention au chemin des fichiers en fonction de l'arborescence)

include("../../lib/initialisationsPropel.inc.php");

include("../../lib/initialisations.inc.php");

include("../plugins.class.php");

// Resume session

$resultat_session = $session_gepi->security_check();

if ($resultat_session == 'c') {

	header("Location: ../../utilisateurs/mon_compte.php?change_mdp=yes");

	die();

} else if ($resultat_session == '0') {

	header("Location: ../../logout.php?auto=1");

	die();

}

// vérification des autorisations (définies dans plugin.xml)

$user_auth = new gepiPlugIn("plugin_example");

$user_auth->verifDroits();

//**************** EN-TETE *****************

$titre_page = "Titre de la page";

require_once("../../lib/header.inc");

//**************** FIN EN-TETE *************

?>

// code PHP du script

// ...

<?php

include("../../lib/footer.inc.php");

?>

</code></pre>

h2. Le script functions_....php

Un plugin peut contenir un script *functions_nom_du_plugin.php* (où 'nom_du_plugin' est le nom défini dans *plugin.xml*) dans lequel on peut définir les fonctions suivantes.

h3. Fonction calcul_autorisation_...()

Cette fonction, dont le nom doit être de la forme *calcul_autorisation_nom_du_plugin*, attend deux paramètres : un login utilisateur et le nom d'un script du plugin (avec ou non le chemin d'accès). En fonction du résultat qu'elle renvoie l'utilisateur connecté aura, sur sa page d'accueil et dans la barre de menu, accès ou non au script. Cette fonction ne prend pas en compte le chemin d'accès aux scripts, donc si le plugin contient des sous-dossiers il faut veiller à ce que les noms des scripts passés en paramètre soient distincts.

Exemple :

<pre><code class="php">

function calcul_autorisation_plugin_example($login,$chemin_script)

	{

	$script=basename($chemin_script);

	switch ($script)

		{

		// Dès lors que la fonction calcul_autorisation_... est définie

		// il faut y confirmer les autorisations définies dans plugin.xml

		// (ou les affiner) pour les scripts devant être accessibles

		// depuis la page d'accueil et depuis la barre de menu.

		// Ici tous les utilisateurs ont accès à index.php

		case "index.php":

			return true;

			break;

		// Ici seul l'administrateur ayant installé le plugin peut l'administrer

		case "admin.php":

			return ($_SESSION['login']==getSettingValue("admin_plugin_example"));

			break;

		default:

			return false;

		}

	}

</code></pre>

h3. Fonctions ante_installation...(), post_installation...(), ante_desinstallation...(), post_desinstallation...()

Ces fonctions, quand elles sont définies, sont exécutées respectivement avant et après "installation", avant et après "désinstallation" du plugin. Elles doivent retourner un chaîne vide si leur exécution s'est correctement déroulée, ou une chaîne contenant un message d'erreur qui sera affiché au début de la page de gestion des plugins. Si une erreur se produit à l'exécution de ante_installation...() ou de ante_desinstallation...() alors il n'est pas procédé à l'installation ou la désinstallation du plugin.

Exemple :

<pre><code class="php">

function post_installation_plugin_example()

	{

	if (saveSetting("admin_plugin_example",$_SESSION['login'])) return "";

		else return "Impossible d'enregistrer dans la table 'setting'";

	}

function post_desinstallation_plugin_example()

	{

	if (mysql_query("DELETE FROM `setting` WHERE `NAME`='admin_plugin_example'")) return "";

		else return "Impossible de supprimer dans la table 'setting' : ".mysql_error();

	}

</code></pre>

h2. Plugins, page d’accueil et barre de menu

Les utilisateurs ont accès au script d'un plugin, en fonction des autorisations définies dans le fichier *plugin.xml* et éventuellement dans la fonction *calcul_autorisation_...()*, par des liens sur la page d'accueil ou dans la barre de menu. Les intitulés de ces liens sont définis dans  le fichier *plugin.xml* : description du plugin dans la section <description>, et pour chaque script titre et description dans la section <menu>.

Sur la page d'accueil l'utilisateur trouve un cadre avec la description du plugin, puis pour chaque script son titre (support du lien) et sa description.

Pour la barre de menu deux possibilités :

* si l'utilisateur n'a accès qu'à un seul script alors dans le menu Plugins il trouve un lien dont l'intitulé est la description du plugin, et dont un survol par la souris fait apparaître la description du script ;

* si l'utilisateur a accès à plusieurs scripts alors de le menu Plugins il trouve une entrée dont l'intitulé est la description du plugin et dont le survol par la souris déroule un sous-menu. Ce sous-menu est composé des liens vers chaque script, liens dont l'intitulé est le titre du script et dont un survol par la souris fait apparaître la description du script.

h2. Adapter à la version 1.6.4 de Gepi un plugin codé pour une version antérieure

Avec la version 1.6.4 Gepi fonctionne désormais avec l'api *mysqli* alors que les versions précédentes passaient par l'api *mysql*. Donc pour adapter un plugin à cette nouvelle version de Gepi tous les appels aux fonctions mysql_*() doivent être convertis. Pour cela on peut utiliser l'outil *MySQLConverterTool* disponible sur "wikis.oracle.com":https://wikis.oracle.com/display/mysql/Converting+to+MySQLi. C'est un script PHP qui peut être  exécuté sur un serveur web ou en ligne de commande.

Sur un serveur web, près avoir copié le dossier du plugin à sa racine (ce n'est pas un nécessité, mais une commodité) il faut procéder ainsi :

* exécuter le script http://.../MySQLConverterTool/ , choisir l'option 'Convert a directory' puis dans la boîte de dialogue obtenue indiquer le chemin absolu vers le dossier du plugin, les extensions des fichiers à convertir, opter pour une modification des fichiers sans sauvegardes et lancer la conversion

!MySQLConverterTool.png!

* ensuite il faut dans tous les fichiers du plugin contenant du code PHP remplacer toutes les occurrences de $GLOBALS["___mysqli_ston"] par $GLOBALS["mysqli"] (ou plus simplement par $mysqli mais dans ce cas il faut ajouter "global $mysqli ;" à toutes les fonctions contenant des appels à l'api mysqli)

* remplacer également toutes les occurrences de

  ((is_object($GLOBALS["mysqli"])) ? mysqli_error($GLOBALS["mysqli"]) : (($___mysqli_res = mysqli_connect_error()) ? $___mysqli_res : false)

  par mysqli_error($GLOBALS["mysqli"]

* enfin  il faut dans tous les fichiers du plugin contenant du code PHP remplacer toutes les occurrences de mysql_result par old_mysql_result

Il 'y a pas d'équivalent à la fonction mysql_result() dans l'api mysqli aussi une fonction old_mysql_result() a été ajoutée à Gepi 1.6.4 pour y pallier, mais le mieux est encore d'adapter le code, par exemple un appel (cas le plus courant) comme

> @$var=mysql_result($resultat,0,'champ') ;@

pourra être remplacé par

> @$t_var=mysqli_fectch_assoc($resultat) ;@

> @$var=$t_var['champ'] ;@

h2. Des idées de plugins

Ce n'est pas ce qui manque :

* la page blanche du PP pour chacun de ses élèves ;

* intégrer du code pour initialiser GEPI à partir d'un ENT (ou de toute autre source externe) ;

* un lieu de réunion pour chaque équipe éducative qui pourrait ainsi laisser des infos avant un conseil ou pour aider celui qui prépare le conseil de classe ;

* un tchat d'échange entre professeurs ;

* et bien d'autres idées, laissez vous aller :)

h2. Un exemple pour tout comprendre :

Télécharger ci-dessous le plugin *plugin_example* et examiner son code.

----

----