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ésisntallation".

* La gestion des droits est assurée par une méthode verifDroits() (propre au module Plugins) qui consulte la table *plugins_autorisations*, et éventuellement complétée par une 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>

<?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="Déscription du script">index.php</item>

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

		</menu>

	</administration>

</gepinstall>

</pre>

h2. Structure d'un script PHP d'un plugin

<pre>

<?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");

?>

</pre>

h2. Le fichier functions_....php

Un plugin peut contenir un fichier *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.

Exemple :

<pre>

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;

		}

	}

</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 alors une chaîne contenet 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 ante_desinstallation...() alors il n'est pas procédé à l'installation ou la désinstallation du plugin.

Exemple :

<pre>

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();

	}

</pre>

h2. Plugins, page d'acceuil 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 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 déscription du plugin, puis pour chaque script son titre (support du lien) et sa déscription.

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 de 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 dont le survol à 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 de la souris fait apparaître la description du script.

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.

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

h2. Un exemple pour tout comprendre :