Module les événements

De Cms Made Simple France
Aller à : navigation, rechercher

Comment créer un événement, Comment se connecter à un événement existant

Notion générale

La notion d'événement en informatique est large. Ici nous évoquerons le pattern observateur/observable dans sa plus simple définition.

Un observable est un événement qui peut être déclenché selon des modèles pré-définit dans CmsMadeSimple :

  • je me connecte à l'administration
  • je me déconnecte
  • j'édite une page
  • du contenu est compilé par Smarty
  • du contenu compilé est retourné au client
  • ...

Vous pouvez trouver cette liste complète dans l'onglet Extensions > Gestion des événements.

En créant une balise utilisateur (UDT) vous pouvez depuis cette interface lier l'observateur (votre balise) à un evénement observable. Ainsi il est aisé de s'envoyer un email à chaque fois qu'une personne se connecte.

Nous allons voir comment gérer ce mécanisme dans un module.

Se plugguer à un événement existant

Si l'on souhaite connecter notre module à un événement observable déjà existant il faut déclarer cette fonction dans votre fichier MonModule.module.php

  function RegisterEvents() {
    $this->AddEventHandler( 'Core', 'ModuleInstalled', false );
    $this->AddEventHandler( 'Core', 'ModuleUnInstalled', false );
  }

  function DoEvent($originator,$eventname,&$params) {

    if($originator == 'Core' && $eventname == 'ModuleInstalled'){

      //Votre traitement

    } else if($originator == 'Core' && $eventname == 'ModuleUnInstalled'){

      //Votre traitement 2

    }
  }

voir l'api de AddEventHandler()


La première fonction déclare l'association entre votre module aux événements d'installation / désinstallation d'un module. Ainsi la seconde fonction DoEvent() sera appelée à chaque install/désinstall de module dans CmsMadeSimple. Tous les événements existant dans votre interface d'administration peuvent être associés.

La seconde fonction doit contenir le code à exécuter à chaque fois qu'un événement est déclenché. Pensez bien à découper ce code afin de différencier les différents événements selon leur origine (Core ou nom du module généralement) et leur nom interne à CmsMadeSimple.

Un dernier point est d'appeler la fonction RegisterEvent durant l'installation de votre module. Cela se passe en une ligne dans le fichier method.install.php

  $this->RegisterEvents();

N'oubliez pas dans method.uninstall.php de nettoyer vos liaisons !

  $this->RemoveEventHandler('Core', 'ModuleInstalled');
  $this->RemoveEventHandler('Core', 'ModuleUninstalled');

voir l'api de RemoveEventHandler()

Créer un événement observable

La déclaration d'un événement se fait également dans le fichier principal de votre module MonModule.module.php

  function GetEventDescription( $eventname ) { return $this->lang('eventdesc-' . $eventname); }
  function GetEventHelp( $eventname ) { return $this->lang('eventhelp-' . $eventname); }

Pensez à ajouter dans votre fichier de lang en_US.php les wording correspondant : eventdesc-monEvenement1 et eventhelp-monEvenement1

Ces deux fonctions ne sont dédiée qu'à de l'information et ne créé en réalité aucun événement. Pour créer un événement il faut en plus dans votre fichier method.install.php ajouter ce code :

  $this->CreateEvent('monEvenement1');
  $this->CreateEvent('monEvenement2');

Voir l'api de CreateEvent()

A ce point du tuto, les autres modules peuvent déjà s'abonner aux événements.

N'oubliez pas de nettoyer vos événements durant la désinstallation de votre module dans le fichier method.uninstall.php

  $this->RemoveEvent('monEvenement1');
  $this->RemoveEvent('monEvenement2');

voir l'api de RemoveEvent()

Un dernier point : il faut bien évidement savoir déclencher un événement afin d'informer les observateurs.

  $this->SendEvent('monEvenement1', array($param1, $param2, ... ));

voir l'api de SendEvent()

Et c'est ainsi que tous les observateurs recevront les paramètres à chaque fois que votre événement se déclenchera.


Déjà finit...

Voilà pour cette partie, vous êtes maintenant capable de vous interfacer avec les événements déclenchés dans CmsMadeSimple

Retourner sur la liste des tutoriaux