plateforme coopérative de partage d'information 1.9 Version de PLOOPI
PLOOPI est une plateforme web de travail collaboratif (GNU GPLv2) permettant à ses utilisateurs d'échanger et de diffuser des données. Il s'agit d'un logiciel sécurisé, robuste et optimisé dont le code source a été de nombreuses fois audité. PLOOPI se présente également sous la forme d'un framework de développement permettant de faciliter la mise en oeuvre de modules métiers basés sur des fonctionnalités avancées de travail collaboratif.

Documentation

Pages visitées : Mon premier module

Mon premier module

Structure intiale

Supposons que vous devez créer le module “test”, ce module doit respecter une certaine arborescence de fichiers.

Seuls 2 fichiers sont obligatoires :

1
2
/modules/test/block.php
/modules/test/public.php

Comme vous pouvez le constater c’est assez léger.

Le fichier “block.php” gère les entrées du bloc du module (le menu intégrable dans le template).
Le fichier “public.php” gère l’affichage du module.

Contenu du fichier “block.php” :

1
2
3
<?php
$block->addmenu('Mon menu', ploopi_urlencode("admin.php?ploopi_moduleid={$menu_moduleid}&ploopi_action=public"));
?>

Contenu du fichier “public.php” :

1
2
3
4
5
6
7
8
<?php
echo $skin->create_pagetitle($_SESSION['ploopi']['modulelabel']);
echo $skin->open_simplebloc('Mon premier module');
?>
<div style="padding:4px;">Hello World</div>
<?
echo $skin->close_simplebloc();
?>

Dans cet exemple, on affiche le nom du module en titre de page, puis on ouvre un bloc contenant ‘Hello World’ avec comme titre ‘Mon premier module’.

Mais l’ajout de ces 2 fichiers ne suffit pas pour voir apparaître le nouveau module dans Ploopi.

Installation

Ploopi dispose d’un système assez évolué permettant l’installation et la mise à jour de modules.
Ainsi un module doit d’abord être installé avant d‘être disponible via l’interface d’administration.

Nous allons donc voir comme créer le dossier d’installation de notre module “test”.

Le dossier d’installation doit avoir la structure suivante :

1
2
3
/install/test/files/
/install/test/description.xml
/install/test/structure.sql

Le dossier “files” contient les fichiers sources du module (php, javascript, css, images, etc…) sous la même forme que le contenu du dossier du module. Ainsi le dossier “/install/test/files” doit contenir les 2 fichiers dont nous allons avoir besoin dans “/modules/test”.

Le fichier “description.xml” contient la description du module (nom du module, auteur, version, etc.) ainsi que d’autres informations comme les paramètres, les actions, etc.. que nous verrons dans un autre chapitre.

Nous nous contenterons pour débuter d’un fichier simplifié :

1
2
3
4
5
6
7
8
9
10
<?xml version="1.0" encoding="ISO-8859-15"?>
<ploopi>
    <moduletype>
        <label>test</label>
        <version>0.1</version>
        <author>Moi</author>
        <date>20080218000000</date>
        <description>Mon module de test</description>
    </moduletype>
</ploopi>

Le label doit être identique au nom du répertoire de votre module dans le dossier install.

Le fichier “structure.sql” contient le script SQL exécuté à l’installation du module. Il contient en général la structure des tables et éventuellement des données. Ce fichier est optionnel. Vous pouvez créer un module sans base de donnée.

Pour notre exemple nous allons simplement créer une table avec 2 champs :

1
2
3
4
5
6
DROP TABLE IF EXISTS `ploopi_mod_test_matable`;
CREATE TABLE IF NOT EXISTS `ploopi_mod_test_matable` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `libelle` varchar(255) NOT NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1;

On doit donc se retrouver avec cette arborescence :

1
2
3
4
/install/test/files/block.php
/install/test/files/public.php
/install/test/description.xml
/install/test/structure.sql

Télécharger l’exemple du module test au format zip

Structure d’un module plus évolué

Comme on a pu le voir précédemment, un module peut n‘être constitué que de deux fichiers. Néanmoins c’est généralement insuffisant lorsque l’on veut développer un module plus conséquent. Si vous êtes libres de créer les fichiers que vous voulez dans le dossier du module (/modules/test), il existe cependant des fichiers qui ont une utilité particulière.

Interface utilisateur du module (Point d’entrée n°1)

Le fichier “public.php” est le point d’entrée de l’interface utilisateur du module.

1
/modules/test/public.php

Interface administrateur du module (Point d’entrée n°2)

Le fichier “admin.php” est le point d’entrée de l’interface administrateur du module.

1
/modules/test/admin.php

Exécutions planifiées (cron)

La gestion des exécutions planifiées doit s’effectuer via le fichier “cron.php”

1
/modules/test/cron.php

Gestion du backend RSS

La gestion du backend RSS du module doit s’effectuer via le fichier “rss.php”

1
/modules/test/rss.php

Constantes, variables globales, fonctions

L’ensemble des constantes, variables globales ou fonctions spécifiques du module peuvent être ajoutées au fichier “global.php” dans le dossier “include”

1
/modules/test/include/global.php

Gestion du bloc menu du module

Le bloc menu du module doit être modifié dans le fichier “block.php”

1
/modules/test/block.php

Feuilles de styles (css)

Si vous souhaitez inclure une feuille de style pour votre module, vous pouvez utiliser les fichiers “styles.css” et “styles_ie.css” dans le dossier “include”.

1
2
/modules/test/include/styles.css
/modules/test/include/style_ie.css

Javascript

Si vous souhaitez inclure du code javascript généré dynamiquement vous pouvez utiliser le fichier “javascript.php” dans le dossier “include”.
Si vous souhaitez inclure du code javascript statique vous pouvez utiliser le fichier “functions.js” dans le dossier “include”.

1
2
/modules/test/include/functions.js
/modules/test/include/javascript.php

Inclusions HTML

Si vous souhaitez insérer du code HTML en amont du module (au niveau du code HTML de la page générée) vous pouvez utiliser les fichiers “body.php” (inclusion après la balise <body>) et “head.php” (inclusion entre les balises <head> et </head>).

1
2
/modules/test/include/body.php
/modules/test/include/head.php

Gestion multilangue

Si vous souhaitez que votre module gère plusieurs langues vous devez ajouter un fichier par langue dans le dossier “lang”

1
2
/modules/test/lang/french.php
/modules/test/lang/english.php

Déclaration des paramètres utilisateur

Les paramètres utilisateur liés au module peuvent être définis dans le fichier “description.xml” contenu dans le dossier install du module.
L’interface de gestion des paramètres est directement intégrée à Ploopi ces paramètres peuvent être utilisé directement dans le code php du module.

1
/install/test/description.xml

Chaque paramètre est défini grâce à la structure XML suivante :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<paramtype>
    <name>doc_displayshortcuts</name>
    <label>Afficher les Raccourcis à la Racine</label>
    <default_value>1</default_value>
    <public>1</public>
    <description/>
    <paramchoice>
        <value>1</value>
        <displayed_value>oui</displayed_value>
    </paramchoice>
    <paramchoice>
        <value>0</value>
        <displayed_value>non</displayed_value>
    </paramchoice>
</paramtype>

name nom du paramètre
label intitulé visible du paramètre
default_value valeur par défaut du paramètre
public détermine si ce paramètre peut être modifié par l’utilisateur
description description du paramètre
paramchoice valeur possible du paramètre (propose une liste de choix au niveau de l’interface utilisateur)
paramchoice.value valeur enregistrée du paramètre
paramchoice.displayed_value valeur affichée du paramètre

Exemple avec le module News :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?xml version="1.0" encoding="ISO-8859-1"?>
<ploopi>
   <moduletype>
      <label>news</label>
      <version>2.30</version>
      <author>Netlor / Ovensia</author>
      <date>20080117000000</date>
      <description>Gestion d'Actualités</description>
      <paramtype>
         <name>nbnewsdisplay</name>
         <label>Nombre d'actualités affichées</label>
         <default_value>5</default_value>
         <public>1</public>
         <description/>
      </paramtype>
   </moduletype>
</ploopi>

Vous remarquerez que paramchoice n’est pas obligatoire.

Déclaration des actions

Les actions sont la base de la gestion des droits dans Ploopi. Une action permet d’autoriser ou non l’exécution d’une ou plusieurs fonctionnalité du module. Chaque module fourni ainsi une liste d’action et ces actions sont utilisée par Ploopi dans la gestion des Rôles. Chaque Rôle peut ensuite être affecté à un utilisateur ou un groupe d’utilisateurs (reportez vous à la documentation utilisateur pour de plus amples informations sur le fonctionnement des rôles).

Les actions sont définies dans le fichier “description.xml” grâce à la structure XML suivante :

1
2
3
4
5
<action>
    <id_action>1</id_action>
    <label>Rédiger</label>
    <role_enabled>1</role_enabled>
</action>

id_action identifiant de l’action (entier)
label intitulé visible de l’action
role_enabled Visible dans les rôles (0/1) (1 par défaut)

Exemple avec le module “News” :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<?xml version="1.0" encoding="ISO-8859-1"?>
<ploopi>
   <moduletype>
      <label>news</label>
      <version>2.30</version>
      <author>Netlor / Ovensia</author>
      <date>20080117000000</date>
      <description>Gestion d'Actualités</description>
      <paramtype>
         <name>nbnewsdisplay</name>
         <label>Nombre d'actualités affichées</label>
         <default_value>5</default_value>
         <public>1</public>
         <description/>
      </paramtype>
      <action>
         <id_action>1</id_action>
         <label>Rédiger</label>
      </action>
      <action>
         <id_action>2</id_action>
         <label>Modifier</label>
      </action>
      <action>
         <id_action>3</id_action>
         <label>Effacer</label>
      </action>
      <action>
         <id_action>4</id_action>
         <label>Publier</label>
      </action>
      <action>
         <id_action>5</id_action>
         <label>Gérer Catégories</label>
      </action>
   </moduletype>
</ploopi>

Chaque action est ensuite appelée par son identifiant au niveau du code php du module.
Pour simplifier leur utilisation il est recommandé d’attribuer une constante par action dans le fichier “global.php” situé dans le dossier “include” du module.

Exemple du module “News” :

1
2
3
4
5
6
7
<?
define ('_NEWS_ACTION_WRITE',       1);
define ('_NEWS_ACTION_MODIFY',      2);
define ('_NEWS_ACTION_DELETE',      3);
define ('_NEWS_ACTION_PUBLISH',     4);
define ('_NEWS_ACTION_MANAGECAT',   5);
?>

Gestion des versions et des mises à jour

Si vous souhaitez proposer une mise à jour de votre module, il suffit d’incrémenter le numéro de version du module dans le fichier “description.xml” du dossier “install” et éventuellement de fourni un script SQL pour les modifications de structure.

Lorsque vous utilisez l’interface d’installation des modules, pLoopi compare la version du module installé (stockée dans la base de données) avec le numéro de version inclus dans le fichier “description.xml”.

Ainsi modifiez la valeur de la balise “version” comme suit :

1
2
3
4
5
6
7
8
9
10
<?xml version="1.0" encoding="ISO-8859-15"?>
<ploopi>
    <moduletype>
        <label>test</label>
        <version>0.2</version>
        <author>Moi</author>
        <date>20080219000000</date>
        <description>Mon module de test</description>
    </moduletype>
</ploopi>

Si votre mise à jour inclut des modifications de structure SQL ou de données, vous pouvez ajouter un script SQL.
Ce script doit s’intituler “update_.X.y.z_.sql” avec X.y.z le numéro de la nouvelle version. (exemple : update_0.2.3.sql)

Les fichiers SQL de mise à jour doivent être déposés dans le dossier “update” du dossier “install” du module.

Dans notre exemple le fichier SQL doit s’intituler “/install/update/update_0.2.sql”.





Retour en haut de la page