API Addon - OVML : Différence entre versions

De OviWiki
Aller à : navigation, rechercher
(→‎Fonctionnement)
 
(12 révisions intermédiaires par 4 utilisateurs non affichées)
Ligne 1 : Ligne 1 :
 +
[[Catégorie:Développement de modules]]
 +
[[Catégorie:API Ovidentia]]
 +
[[Catégorie:Développement OVML]]
  
 
== Introduction ==
 
== Introduction ==
 +
L'API addon-OvML permet à un addon d'accéder à tous les containers OVML.
 +
Il est ainsi possible à un addon de lister les catégories, les thèmes d'articles, les articles,
 +
les contributions d'un forum etc ...
  
−
Il est indispensable de connaître le langage OVML pour comprendre la suite de ce chapitre (Voir la documentation OVML).
+
Tous les fonctionnalités offertes par l'OVML sont ainsi disponibles à un addon.
  
−
Le langage OVML apparaît dans Ovidentia afin de permettre aux administrateurs de personnaliser leurs pages d'accueil ou autres fichiers. L'avantage du langage est qu'il s'intègre facilement dans un code html et que son code reste compatible avec les nouvelles versions d'Ovidentia. Les données récupérées sont généralement présentes dans la base de données, la syntaxe du langage évite des accès directs aux enregistrements.
+
== Utilisation ==
−
Dans le cadre d'un module, il est parfois nécessaire de créer de nouvelles fonctions OVML si les fonctions existantes du noyau ne sont pas suffisantes.
+
Afin d'utiliser cette API, l'addon doit inclure le fichier '''''ovmlapi.php''''':
  
−
Syntaxe d'utilisation des containers OvML des modules :
+
<source lang="php">
 +
include_once $babInstallPath.'utilit/ovmlapi.php';
 +
</source>
  
−
<OCAddon name="" param1="" param1="" ...>
+
L'interaction de l'addon avec cette API se fait par l'intermédiaire de la classe '''''bab_ovmlAPI''''':
−
<OVvar1>
+
−
<OVvar2>
+
−
</OCAddon>
+
  
−
name : nom de l'add-on où se trouve la fonction (préfixe de l'add-on)
+
<source lang="php">
−
param1 : premier paramètre d'envoi au module, généralement le nom de la fonction à utiliser
+
include_once $babInstallPath.'utilit/ovmlapi.php';
−
param2 : deuxième paramètre d'envoi au module, généralement le premier paramètre de la fonction ovml du module
+
−
…
+
  
−
Explication :
+
function list_topics()
−
Lorsqu'on va utiliser le container OCAddon, le moteur ovml d'Ovidentia va envoyer au module plusieurs données ainsi que les paramètres du container OCAddon. De son côté, le module renvoit les valeurs correspondantes aux variables de la fonction utilisée (<OVvar1> et <OVvar2> dans cet exemple).
+
{
 +
global $babBody;
  
−
== Fonctionnement ==
+
class list_topics_class
 +
{
 +
function list_topics_class()
 +
{
 +
$this->tpl = new bab_ovmlAPI();
 +
}
 +
}
 +
...
  
−
Pour gérer de nouvelles fonctions OVML dans notre module, il faut ajouter un fichier ovml.php dans le répertoire du module contenant les fichiers PHP (dossier Programs dans le fichier zip ou $babInstallPath/addons/add-on prefix).
+
}
  
−
Le fichier ovml.php doit contenir la fonction :
+
</source>
  
−
function addon-name_ovml($args) {}
+
L'instantiation de cette classe créée un contexte global pour l'OVML.
−
où addon-name est le préfixe du nom de l'add-on
+
Il est possible de passer des variables à ce contexte en utilisant le paramètre '''''$args''''':
−
et $args est un tableau associatif qui contiendra les noms des paramètres envoyés ainsi que leurs valeurs
+
  
−
Le fonctionnement de cette fonction est laissé au programmeur.
+
<source lang="php">
−
Exemple de récupération des paramètres :
+
include_once $babInstallPath.'utilit/ovmlapi.php';
−
if (isset($args['param1'])) {
+
 
−
switch($args['param1']){
+
function list_topics()
−
case '1': ...
+
{
−
case '2': ...
+
global $babBody;
−
}
+
 
 +
class list_topics_class
 +
{
 +
function list_topics_class()
 +
{
 +
$args['babHtmlEntities'] = 1;
 +
$args['topics'] = bab_gp('topicid');
 +
$this->tpl = new bab_ovmlAPI($args);
 +
}
 +
}
 +
...
 
}
 
}
  
−
Une chose importante est de toujours renvoyer un tableau indexé comprenant des tableaux associatifs contenant les noms des variables (sans le préfixe OV) et leurs valeurs. Le tableau renverra plusieurs lignes donc plusieurs tableaux des mêmes variables dans le cas où plusieurs enregistrements sont retournés. Le container ovml <OCAddon> fera autant de boucles qu'il y a d'index dans le tableau.
+
</source>
  
−
Remarque : si aucun résultat, il faut renvoyer un tableau vide.
+
L'instantiation d'un container OVML se fait par la méthode '''''getContainer''''':
  
−
Exemple de renvoi du tableau :
+
<source lang="php">
−
$tab = array();
+
include_once $babInstallPath.'utilit/ovmlapi.php';
−
$feed['var1'] = "value var1";
+
 
−
$tab[0] = $feed;
+
function list_topics()
−
return $tab;
+
{
 +
global $babBody;
 +
 
 +
class list_topics_class
 +
{
 +
function list_topics_class()
 +
{
 +
$this->tpl = new bab_ovmlAPI();
 +
$args['topicid'] = 12;
 +
$args['archive']='No';
 +
$args['topicorder']='Yes';
 +
$this->cont = $this->tpl->getContainer('ArticleTopics', $args);
 +
}
 +
}
 +
...
 +
}
 +
 
 +
</source>
 +
 
 +
Dans ce qui précède, on instancie le container OCArticleTopics et on lui passe
 +
les paramètres ''topicid'', ''archive'' et ''topicorder''.
 +
 
 +
On peut ajouter des paramètres au contexte courant et en récupérer en utilisant les
 +
deux méthodes suivantes :
 +
 
 +
<source lang="php">
 +
$vars[] = array('name'=>'count', 'value' => $count);
 +
$vars[] = array('name'=>'index', 'value' => 0);
 +
$this->tpl->putVar($vars);
 +
$title = $this->tpl->getVar('ArticleTitle');
 +
$author = $this->tpl->getVar('ArticleAuthor', array('author'=>'%F %L'))
 +
</source>
 +
 
 +
La méthode ''''getContainer'''' retourne un objet implémentant la méthode ''''getnext''''
 +
permettant de récupérer les résultats du container.
 +
La méthode ''''getnext'''' retourne ''false'' quand il n'y a plus de résultats et ''true'' dans le cas
 +
contraire.
 +
Quand la méthode retourne false, elle détruit automatiquement son contexte.
 +
Sinon, vous avez la possibilité de détruire le contexte en appelant la méthode :
 +
 
 +
<source lang="php">
 +
 
 +
$this->cont = $this->tpl->getContainer('ArticleTopics', $args);
 +
$thsi->cont->destroyContext();
 +
</source>
 +
 
 +
L'appel à ''''destroyContext'''' détruit le contexte courant et supprime les variables.
 +
 
 +
Normalement, à chaque appel à la méthode ''''getnext'''', le système créé les variables du container
 +
dans l'objet implémentant la méthode ''''getnext'''':
 +
 
 +
 
 +
<source lang="php">
 +
include_once $babInstallPath.'utilit/ovmlapi.php';
 +
 
 +
function list_articles()
 +
{
 +
global $babBody;
 +
 
 +
class list_articles_class
 +
{
 +
function list_articles_class()
 +
{
 +
$this->tpl = new bab_ovmlAPI();
 +
$args['topicid'] = 12;
 +
$args['archive']='No';
 +
$args['topicorder']='Yes';
 +
$this->cont = $this->tpl->getContainer('ArticleTopics', $args);
 +
}
 +
 
 +
function getnextarticle()
 +
{
 +
if( $this->cont->getnext() )
 +
{
 +
$this->title =  $this->cont->ArticleTitle;
 +
return true;
 +
}
 +
else
 +
{
 +
return false;
 +
}
 +
}
 +
 +
}
 +
...
 +
}
 +
</source>
 +
 
 +
Si l'on souhaite créer ces variables dans un autre objet, on peut passer cet objet à chaque
 +
appel à la fonction ''''getnext'''':
 +
 
 +
<source lang="php">
 +
include_once $babInstallPath.'utilit/ovmlapi.php';
 +
 
 +
function list_articles()
 +
{
 +
global $babBody;
 +
 
 +
class list_articles_class
 +
{
 +
function list_articles_class()
 +
{
 +
$this->tpl = new bab_ovmlAPI();
 +
$args['topicid'] = 12;
 +
$args['archive']='No';
 +
$args['topicorder']='Yes';
 +
$this->cont = $this->tpl->getContainer('ArticleTopics', $args);
 +
}
 +
 
 +
function getnextarticle()
 +
{
 +
if( $this->cont->getnext($this) )
 +
{
 +
echo $this->ArticleTitle;
 +
return true;
 +
}
 +
else
 +
{
 +
return false;
 +
}
 +
}
 +
 +
}
 +
...
 +
}
 +
</source>

Version actuelle en date du 10 novembre 2008 à 12:00


Introduction

L'API addon-OvML permet à un addon d'accéder à tous les containers OVML. Il est ainsi possible à un addon de lister les catégories, les thèmes d'articles, les articles, les contributions d'un forum etc ...

Tous les fonctionnalités offertes par l'OVML sont ainsi disponibles à un addon.

Utilisation

Afin d'utiliser cette API, l'addon doit inclure le fichier ovmlapi.php:

<source lang="php"> include_once $babInstallPath.'utilit/ovmlapi.php'; </source>

L'interaction de l'addon avec cette API se fait par l'intermédiaire de la classe bab_ovmlAPI:

<source lang="php"> include_once $babInstallPath.'utilit/ovmlapi.php';

function list_topics() { global $babBody;

class list_topics_class { function list_topics_class() { $this->tpl = new bab_ovmlAPI(); } } ...

}

</source>

L'instantiation de cette classe créée un contexte global pour l'OVML. Il est possible de passer des variables à ce contexte en utilisant le paramètre $args:

<source lang="php"> include_once $babInstallPath.'utilit/ovmlapi.php';

function list_topics() { global $babBody;

class list_topics_class { function list_topics_class() { $args['babHtmlEntities'] = 1; $args['topics'] = bab_gp('topicid'); $this->tpl = new bab_ovmlAPI($args); } } ... }

</source>

L'instantiation d'un container OVML se fait par la méthode getContainer:

<source lang="php"> include_once $babInstallPath.'utilit/ovmlapi.php';

function list_topics() { global $babBody;

class list_topics_class { function list_topics_class() { $this->tpl = new bab_ovmlAPI(); $args['topicid'] = 12; $args['archive']='No'; $args['topicorder']='Yes'; $this->cont = $this->tpl->getContainer('ArticleTopics', $args); } } ... }

</source>

Dans ce qui précède, on instancie le container OCArticleTopics et on lui passe les paramètres topicid, archive et topicorder.

On peut ajouter des paramètres au contexte courant et en récupérer en utilisant les deux méthodes suivantes :

<source lang="php"> $vars[] = array('name'=>'count', 'value' => $count); $vars[] = array('name'=>'index', 'value' => 0); $this->tpl->putVar($vars); $title = $this->tpl->getVar('ArticleTitle'); $author = $this->tpl->getVar('ArticleAuthor', array('author'=>'%F %L')) </source>

La méthode 'getContainer' retourne un objet implémentant la méthode 'getnext' permettant de récupérer les résultats du container. La méthode 'getnext' retourne false quand il n'y a plus de résultats et true dans le cas contraire. Quand la méthode retourne false, elle détruit automatiquement son contexte. Sinon, vous avez la possibilité de détruire le contexte en appelant la méthode :

<source lang="php">

$this->cont = $this->tpl->getContainer('ArticleTopics', $args); $thsi->cont->destroyContext(); </source>

L'appel à 'destroyContext' détruit le contexte courant et supprime les variables.

Normalement, à chaque appel à la méthode 'getnext', le système créé les variables du container dans l'objet implémentant la méthode 'getnext':


<source lang="php"> include_once $babInstallPath.'utilit/ovmlapi.php';

function list_articles() { global $babBody;

class list_articles_class { function list_articles_class() { $this->tpl = new bab_ovmlAPI(); $args['topicid'] = 12; $args['archive']='No'; $args['topicorder']='Yes'; $this->cont = $this->tpl->getContainer('ArticleTopics', $args); }

function getnextarticle() { if( $this->cont->getnext() ) { $this->title = $this->cont->ArticleTitle; return true; } else { return false; } }

} ... } </source>

Si l'on souhaite créer ces variables dans un autre objet, on peut passer cet objet à chaque appel à la fonction 'getnext':

<source lang="php"> include_once $babInstallPath.'utilit/ovmlapi.php';

function list_articles() { global $babBody;

class list_articles_class { function list_articles_class() { $this->tpl = new bab_ovmlAPI(); $args['topicid'] = 12; $args['archive']='No'; $args['topicorder']='Yes'; $this->cont = $this->tpl->getContainer('ArticleTopics', $args); }

function getnextarticle() { if( $this->cont->getnext($this) ) { echo $this->ArticleTitle; return true; } else { return false; } }

} ... } </source>

Récupérée de « https://wiki.ovidentia.fr/index.php?title=API_Addon_-_OVML&oldid=3473 »