API des fonctionnalités : Différence entre versions

Version actuelle en date du 22 mai 2009 à 10:19

Cette API est disponible à partir de Ovidentia 6.7.0

Introduction

L'API des librairies est utilisée pour partager du code entre différentes parties d'Ovidentia tel que le noyau et les modules. Dans Ovidentia, les librairies sont représentées sous forme d'un arbre visible par les administrateurs dans la page "Modules" sous l'onglet "Librairies partagées".

Proposer des librairies

Chaque fonctionnalité devra être nommée selon un "chemin" unique, par exemple "convertHtml/toPdf/openOffice", les caractères _ sont interdits dans le chemin.

Une fonction du noyau d'ovidentia permettra d'enregistrer un fichier php en tant que fonctionnalité, le fichier devra contenir une classe PHP nommée en utilisant le même chemin, par exemple :

<source lang="php"> class Func_ConvertHtml_ToPdf_OpenOffice extends bab_functionality {

}

</source>

Le nom de toutes les classes de librairies sont préfixées par Func_, dans le nom de la classe, le _ remplace le / , l'objet devra hériter de la classe bab_functionality.

Installation

Au moment de l'installation ou du programme de reprise, il faut enregistrer l'objet dans Ovidentia, exemple :

<source lang="php"> include_once $GLOBALS['babInstallPath'].'utilit/functionalityincl.php';

$func = new bab_functionalities(); $func->register('ConvertHtml/ToPdf/OpenOffice', $GLOBALS['babAddonPhpPath'].'convert.php'); </source>

La méthode register retourne un boolean, la valeur retournée sera false si la librairie n'a pas pu être enregistrée

Dans Ovidentia, un fichier "link.inc" sera créé dans un arbre de répertoire (sous le répertoire fonctionalities à la racine du site) avec pour contenu du code php pour inclure le fichier passé en 2ème paramètre.

De même, la méthode unregister() permet de désinstaller la librairie, le fichier de lien sera supprimé de l'arborescence.

<source lang="php"> include_once $GLOBALS['babInstallPath'].'utilit/functionalityincl.php';

$func = new bab_functionalities(); $func->unregister('ConvertHtml/ToPdf/OpenOffice'); </source>

Il existe deux événements qui peuvent être utilisés lors de l'appel à bab_functionalities::register() et bab_functionalities::unregister()

• bab_eventFunctionalityRegistered
• bab_eventFunctionalityUnregistered

Héritage des librairies

Il est possible de créer un objet qui hérite et utilise l'interface d'une autre librairie.

exemple : le module "convert" propose une fonctionnalité pour convertir du html

<source lang="php">

class Func_convertHtml extends bab_functionality { function getDescription() { return 'convertir du html vers un autre format'; }

function process($html) { return NULL; } }

</source>

Dans un autre module "convertToPdf", on propose de convertir du html en pdf en utilisant openOffice. Pour que l'objet de librairie soit acceptée par le programme d'installation, l'objet doit hériter de l'objet parent.

<source lang="php">

bab_functionality::includefile('convertHtml');

class Func_ConvertHtml_ToPdf_OpenOffice extends Func_ConvertHtml { function getDescription() { return 'convertir du html en pdf'; }

function process($html) {

} }

</source>

Utiliser une librairie

La fonction du noyau bab_functionality::get('convertHtml/toPdf/openOffice'); effectuera une inclusion du fichier "convertHtml/toPdf/openOffice/link.inc" ensuite l'objet Func_convertHtml_toPdf_openOffice sera instancié. Si la fonctionnalité n'existe pas, la fonction bab_functionality::get() retournera la valeur false.

Les niveaux supérieurs de l'arborescence seront complétés avec une copie du fichier link.inc si aucun fichier de lien n'est présent.

Un formulaire est disponible pour d'administrateur afin de changer les fichiers interfaces des niveaux supérieurs pour redéfinir les fonctions par défaut dans le cas de sous-répertoires multiples.

Pour simplifier l'exécution des fonctions d'interface, le contexte du module ne sera pas recréé avant que la fonction soit appelée. Par conséquent, les variables globales de l'environnement du module ne devront pas être utilisées. Pour pallier à ce problème, il faut utiliser l'API de gestion d'un module

Fonctions

Obtenir les sous-librairies d'un objet

La liste des sous-fonctionnalités permet de proposer à l'utilisateur un choix, et ensuite effectuer un appel direct à la fonctionnalité en utilisant un chemin plus complet.

<source lang="php">

$array = bab_functionality::getFunctionalities('path');

</source>

Obtenir l'instance de l'objet

Par défaut, l'objet retourné pour une fonctionnalité est un singleton

<source lang="php">

$singleton = bab_functionality::get('path');

</source>

Il est possible de passer un deuxième paramètre à la methode get() pour que l'instance retournée ne soit pas un singleton

<source lang="php">

$instance = bab_functionality::get('path', false);

</source>

inclure le fichier de l'objet librairie

inclure le fichier de la fonctionnalité afin d'effectuer un héritage

<source lang="php">

bab_functionality::includefile('path');

</source>

Tester la présence d'une librairie

Dans le fichier addonini.php d'un module, il est possible de tester la présence d'un fonctionnalité comme un pré-requis, afin d'empêcher l'installation du module si la fonctionnalité n'est pas installée.

bab_functionality::get() retourne false si la fonctionnalité n'est pas trouvée, il est possible d'utiliser cette méthode avec un @ devant l'appel pour ne pas voir le notice déclenché et utiliser uniquement la valeur de retour.

Les librairies

Voir la liste des librairies sur la page : Catégorie:Documentation des librairies.