mtweb

Faire un plugin

Cette page décrit, pas à pas, la création d'un plugin Hello world ! avec mtweb.

Ce plugin est disponible en téléchargement ici.

Le rôle d'un plugin

Un plugin permet d'ajouter des fonctionnalités sur mtweb sans intervenir sur l'application principale. Vous pouvez aussi altérer l'application principale en passant par un plugin, sans modifier le code du dossier mw/app.

Les plugins sont particulièrement utiles pour les mises à jour. Vos modifications sur l'application principales seront perdues si décidez de mettre à jour mtweb. Si vous avez fait vos développement dans des plugins, vous pourrez les ré-intégrer sur votre installation upgradée et les ré-activer dans l'administration du site.

Une organisation des dossiers similaire à celle de l'application principale

Comme dans l'application principale, un plugin peut avoir un dossier :

app

Dès lors qu'un plugin est activé dans l'administration, s'il contient un dossier app, ce dernier sera traité par le programme de la même manière que le dossier app de l'application principale. C'est dans ce dossier qu'un plugin va donc pouvoir ajouter des modules de données, des contrôleurs et des vues.

→ plus d'infos sur l'organisation du code

Créer un nouveau plugin

Un plugin doit suivre certaines conventions :

  • Il doit se trouver dans un dossier du répertoire plugins
  • Il doit contenir un fichier qui porte le même nom que celui de son dossier, avec une extention php
  • Ce fichier doit définir une classe qui s'appelle comme le dossier
  • Cette classe doit hériter de la classe mw_plugin

Dans notre exemple, on va créer un dossier :

plugins/mw_hello

Et créer dans ce dossier un fichier :

plugins/mw_hello/mw_hello.php

avec ce code :

<?php

  class mw_hello extends mw_plugin{

    function title(){
      return "Hello World !";
    }

    function description(){
      return "Un plugin qui affiche une page Hello World !";
    }

  }

?>

Si vous vous rendez dans l'administration du site, vous devriez voir le plugin, avec le nom et la description retournés par les méthodes ci-dessus.

Cliquez sur les liens "installer" puis "activer" dans le cadre du plugin.

Ajouter une action 

Rendez-vous maintenant sur votre installation, avec votre navigateur, à l'URL :

index.php?e=hello

Un message d'erreur devrait vous dire :

Impossible de trouver le controleur index pour le module hello

Ce qui est normal. Le module hello n'existe pas encore et ne contient donc aucun contrôleur. On va donc créer un module hello, en ajoutant dans le dossier du plugin un dossier app, avec dedans un dossier controllers, contenant notre dossier de module hello :

app/controllers/hello

Par la suite, si le plugin doit définir d'autres modules, ils se trouveront aussi dans ce dossier app/controllers.

Puis on va doter ce module hello d'un nouveau contrôleur index, en créant un fichier :

app/controllers/hello/index.php

Avec ce code :

<?php

  class mw_hello_index extends mw_controller{

    function index(){
    }

  }

?> 

Si vous retrounez maintenant sur la page :

index.php?e=hello

L'erreur devrait avoir disparu.

→ plus d'infos sur les actions

Une vue pour l'affichage

Pour le moment, notre plugin n'affiche pas grand chose. On va lui créer une vue, toujours dans le dossier du plugin, dans un nouveau fichier (avec les nouveaux dossiers qui vont bien) :

 app/out/default/views/hello/index.php

Quelques remarques sur le chemin de ce fichier. Il s'agit d'un fichier d'affichage, il est donc dans le dossier out. Ici, on utilise le template default, le fichier se trouve dans le dossier de ce template. pour le reste du chemin, c'est comme vous voulez.

Commeçons avec un affichage tout simple dans ce fichier :

<h2>Hello World !</h2>

Un layout pour faire le lien avec l'action

Nous avons une action, nous avons aussi une vue. Il ne reste plus qu'à faire le lien entre les deux. Pour cela, nous allons créer un fichier de layout dans lequel nous allons indiquer à l'application que pour notre action, c'est ce fichier de vue que nous voulons utiliser.

Dans un template, les fichiers de layout sont dans un dossier layouts et portent le nom de leur module. On va donc créer un fichier :

app/out/default/layouts/hello.xml

Avec ce code :

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

  <hello page="index.php">
    <index>
      <index content="views/hello/index.php" />
    </index>
  </hello>

</layout>

Rechargez maintenant la page :

index.php?e=hello

Et vous devriez voir un magnifique Hello World !

→ plus d'infos sur les fichiers d'affichage 

Ajouter un lien vers la page

Pour finioler la chose, il ne manque plus qu'un lien pour aller sur la page sans avoir à taper l'URL. On va pour ça utiliser la méthode init de notre fichier de plugin :

plugins/mw_hello/mw_hello.php

Qui devient :

<?php

  class mw_hello extends mw_plugin{

    function title(){
      return "Hello World !";
    }

    function description(){
      return "Un plugin qui affiche une page Hello World ! avec une citation aléatoire";
    }

    function init($env){
      $env->set_link("menu_top/hello", $env->url("hello"), "Hello");
      return true;
    }

  }

?> 

La méthode init du plugin sera appelée à chaque requête, durant l'initialisation de l'application, avant le traitement des actions. Cette méthode doit retourner TRUE si l'initialisation s'est bien passée (sinon l'application sera arrétée avec un message d'erreur indiquant qu'elle n'a pas pu charger les plugins).

On utilise ici la méthode set_link qui ajoute un lien dans l'arborescence des liens, au chemin "menu_top/hello" qui correspond, dans le template default, à un lien situé dans le header. Le deuxième paramètre indique l'URL du lien, et le troisième son intitulé.

Installation / activation

Dès lors qu'un plugin est ajouté dans le repertoire plugins de l'application, des liens d'installation et d'activation pour ce plugin deviennent disponibles dans l'administration.

Au niveau de l'application, un plugin doit être installé ET activé pour que ses fonctionnalités soient prisent en compte. Si par exemple vous désactivez le plugin Hello World, le lien "Hello" disparaîtra et l'URL :

index.php?e=hello

Aboutira à nouveau sur un message d'erreur.

Au niveau du plugin, l'installation et l'activation peuvent déclancher des traitements. Un plugin peut implémenter, en plus des méthodes title, description et init vues plus haut, les méthodes suivantes :

install 

function install($env)

Cette méthode sera appelée à chaque fois que le lien installer du plugin sera cliqué dans l'administration du site. La méthode doit retourner TRUE si l'installation s'est bien passée, ou une chaine de caractères avec un message d'erreur en cas d'erreur.

Cette méthode peut par exemple être utilisée pour ajouter des tables nécessaires au plugin dans la base de données.

uninstall 

function uninstall($env) 

Cette méthode sera appelée à chaque fois que le lien désinstaller du plugin sera cliqué dans l'administration du site. La méthode doit retourner TRUE si le désinstallation s'est bien passée, ou une chaine de caractères avec un message d'erreur en cas d'erreur.

Un clique sur ce lien affiche un popup demandant confirmation et averti que si le plugin gère des données, elles seront perdues. C'est dans cette méthode qu'on pourra effacer les tables ajoutées dans la méthode précédente.

enable 

function enable($env)

Cette méthode sera appelée à chaque fois que le lien activer du plugin sera cliqué dans l'administration du site. La méthode doit retourner TRUE si l'activation s'est bien passée, ou une chaine de caractères avec un message d'erreur en cas d'erreur.

disable 

function disable($env)

Cette méthode sera appelée à chaque fois que le lien désactiver du plugin sera cliqué dans l'administration du site. La méthode doit retourner TRUE si la désactivation s'est bien passée, ou une chaine de caractères avec un message d'erreur en cas d'erreur.