En construction, n'hésitez pas à modifier, compléter, relier, traduire !

Il existe 2 types d'événements dans Elgg : les événements events et les hooks (littéralement : "crochets") des plugins. Les hooks sont activés lorsqu'une action a lieu et qu'une partie de cette action (de la fonction ou du code qui est exécuté) peut être remplacée ("overridée") par un plugin.

Bien qu'il existe d'autres manières de remplacer le fonctionnement d'un bout de code suite à une action, un hook a une portée plus générale qu'une action, et il peut être proposé et utilisé différemment. Il existe 4 différences fondamentales entres les plugin hooks et les Elgg events :

1. Un crochet de plugin est appelé avec un tableau de paramètres plutôt que juste l'objet qui vient d'être modifié/créé. Ceci procure plus de flexibilité pour le système de crochets.
2. Tous les crochets sont appelés quelque soit la valeur retournée par un crochet. Les gestionnaires d'évènements peuvent arrêter la pile d'évènement en retournant false.
3. A plugin hook is passed the return value of previously called plugin hooks and can modify it if it chooses.
4. Le code qui enclenche un crochet va plus sûrement prendre une action basée sur la valeur retournée que les évènements. C'est moins vrai pour le noyau d'Elgg.

S'enregistrer pour un gestionnaire de crochets (de plugin)

Pour déclarer un gestionnaire, utilisez la fonction register_plugin_hook comme sur cet exemple :

register_plugin_hook ('cron','hourly','myplugin_cronjob')

• $hook Le nom du crochet
• $entity_type le type de crochet ("user","object","view",...) ou 'all' (tous).
• $function le nom de la fonction qui doit être exécutée.
• $priority la priorité - 0 est le premier, la valeur défaut est 500.

 

Votre gestionnaire de crochets

Votre fonction de gestion de crochets devrait suivre le prototype suivant :

function my_plugin_hook($hook, $type, $returnvalue, $params)

{

... do stuff ...

}

Paramètres

• $hook Le crochet appelé.
• $type le type d'entité qui est en train d'être appelé.
• $returnvalue la valeur de retour. IMPORTANT: A moins que ovus n'ajoutiez ou que vous ne changiez la valeur de retour, NE RETOURNEZ RIEN.
• $params un tableau de paramètres.

 

Déclencher un Crochet de plugin

Vous pouvez déclencher un crochet dans votre plugin avec la fonction trigger_plugin_hook.

En ajoutant des appels à trigger_plugin_hook() dans votre code (généralement le code de votre action), vous permettez à d'autres développeurs de plugin de s'enregistrer pour ces crochets et étendre les fonctionnalités de votre plugin.

Exemple de déclenchement de crochet de plugin

// auto adjust contrast unless another plugin has registered to do this

if (!trigger_plugin_hook('photo_album_plugin','contrast', array('entity' => $image), false) {

   // no plugins returned true, so we auto adjust contrast

   ...

}

Special plugin hooks

cron

Le plugin cron permet à votre plugin de lancer vos propres fonctionnalités de manière régulièrement, déclenchées par le serveur. 

Le paramètre type ici devrait être une chaîne de caractère contenant la période cron à laquelle vous voulez attacher votre fonctionnalité. Les voici : 

• minute
• fiveminute
• fifteenmin
• halfhour
• hourly
• daily
• weekly
• monthly
• yearly
• reboot

Voir aussi : Développer des plugins avec cron, Cron reference

permissions_check

Le crochet permissions_check vous permet de surcharger les permissions d'accès par défaut d'Elgg. Cela signifie que vous pouvez permettre à l'utilisateur courant de modifier une entité qu'il ne devrait pas pouvoir modifier par défaut. (Notez que ca ne permet pas de récupérer des entités que l'utilisateur n'a pas la permission de voir.) Un exemple pourrait surcharger les permssions sur une entité groupe comme un album photo. Vous voudriez autoriser à tous les membres d'un groupe de charger toutes les photos qui ont été créées sous le groupe. Chaque album appartient à l'utilisateur qui l'a créé donc vous pourriez avoir besoin de surcharger les permissions par défaut et vérifier si l'utilisateur appartient au groupe avant d'accorder la permission d'écriture.

La fonction de crochet passe en paramètre un tableau avec le type de l'entité avec l'entité comme paramètre de l'entité et l'utilisateur courant comme paramètre utilisateur. On passe également un statut par défaut true ou false, que l'utilisateur courant peut modifier l'entité en question en tant que valeur de retour ou pas.

On doit employer cela avec précaution ! Avant de changer la valeur par défaut, assurez-vous de limiter la portée de votre fonction avec un test if qui vérifie que vous êtes dans le bon contexte. Pour utiliser le contexte, vous aurez besoin de déclarer les variables de contexte dans vos actions également. Ensuite, votre function de crochet devrait vérifier pour voir si c'est le bon type d'entité, et si l'exécution fait sens dans ce contexte avant de chanrger la valeur de retour des permissions. Autrement, vous pouvez interdire la modification à toutes les entités, ou pire, à accorder le droit d'écriture à tout le monde.

Pour plus d'exemples, voir Vérification des Permissions (lien à faire)

validation utilisateur

Par défault, les utilisateurs non validés déclenchent l'évènement validate user s'ils essaient de se connection ou demandent un nouveau mot de passe. Si le plugin uservalidationbyemail plugin est activé (comme dans toute installation standard Elgg), cela reverra un lien de validation à l'utilisateur et l'informera de ce qui s'est passé.

Si vous voulez un autre comportement à la place, vous pouvez définir les crochets unvalidated_login_attempt ou unvalidated_requestnewpassword. L'entité user est passé au paramère de l'entité.

Voir également

• Les évènements Elgg
• La liste des crochets dans le noyau Elgg

Traduction de http://docs.elgg.org/wiki/Plugin_Hooks