Manual:Hooks/fr



Les accroches permettent au code utilisateur d'être exécuté lorsqu'un événement prédéfini (tel que l'enregistrement d'une page ou la connexion d'un utilisateur) se produit. Par exemple, l'extrait de code suivant déclenche un appel à la fonction  quand l'accroche   est sollicitée, en passant à sa fonction, les arguments spécifiques à.

Les accroches peuvent être enregistrées en établissant une correspondance entre le nom de l'accroche et la procédure de callback dans le fichier de l'extension:

""

MediaWiki fournit beaucoup d' accoches comme celle-ci pour étendre les fonctionalités du lociciel MediaWiki. Assigner une fonction (appelée gestionnaire d'événements) à une accroche fera que cette fonction sera appelée à l'endroit approprié du code principal MediaWiki, afin d'exécuter toute(s) tâche(s) supplémentaire(s) que le développeur pense utile(s) à cet endroit. Chaque accroche peut avoir de multiples gestionnaires qui lui sont atachés, auquel cas elle appellera les fonctions dans l'ordre où elles ont été assignées, les modifications laissées par une function étant passées à la fonction suivante de la chaîne.

Assignez les fonctions aux accroches à la fin de ou dans votre fichier personnel d'extension à la portée du fichier (non pas dans une fonction  ni dans l'accroche de ). Pour les extensions, si le comportement de la fonction de l'accroche est conditionné par une valeur de LocalSettings.php, l'accroche devra être assignée et la fonction se terminer plus tôt lorsque la condition n'est pas satisfaite.

Vous pouvez aussi créer de nouvelles accroches dans votre propre extension; si vous le faites, ajoutez les au registre des accroches des extensions.

Contexte
Une accroche est déclenchée par un appel à la fonction Hooks::run (décrite dans le fichier, et définie dans . Le premier argument de Hooks::run est le nom de l'accroche, le second est le tableau des arguments de cette accroche. Elle trouvera les gestionnaires d'événements à exécuter dans le tableau . Elle appelle la fonction PHP call_user_func_array avec les arguments qui seront ceux de la fonction appelée.

Voir aussi la.

Dans cet exemple de la fonction  de, doEditContent appelle Hooks::run pour exécuter l'accroche , en lui passant   comme argument :

""

Le appelle beaucoup d'accoches, mais  peut aussi appeler des accroches.

Ecrire un gestionnaire d'événements
Un gestionnaire d'événements est une fonction que vous assignez à une accroche, et qui sera exécutée à chaque fois que l'événement représenté par cette accroche se produit. Il consiste en :


 * une fonction avec quelques données optionnelles qui l'accompagnent, ou
 * un object avec une méthode et quelques quelques données optionnelles qui l'accompagnent.

Enregistrez le gestionnaire d'événements en l'ajoutant au tableau global pour un événement donné. Les attaches peuvent être ajoutées en tout point de l'exécution avant que l'accroche ne soit appellée, mais sont en général ajoutées dans, ses fichiers inclus, ou, pour les extensions, dans le fichier extension.json. Tout ce qui suit sont des manières valides pour définir une fonction d'accroche pour l'événement EventName à qui on passe deux paramètres, montrant le code qui sera exécuté quand l'événement EventName se produit:

Pour les extensions, la syntaxe est similaire dans le fichier  (correspondant au premier et au second cas ci-dessus):

Quand une erreur survient, la fonction (ou la méthode de l'objet) que vous avez enregistrée est appelée, avec les paramètres de l'événement, et toutes les données facultatives que vous avez fournies à l'enregistrement. Notez que lorsqu'un objet est l'accroche et que vous n'avez pas indiqué de méthode, la méthode appelée est 'onEventName'. Pour les autres événements cela serait 'onArticleSave', 'onUserLogin', etc.

Les données optionnelles sont utiles si vous voulez utiliser la même fonction ou objet pour différents objectifs. Par exemple :

Ce code résulterait en une double exécution de ircNotify quand une page est enregistrée : une fois pour 'TimStarling', et une fois pour 'brion'.

Les gestionnaires d'événements peuvent retourner l'une des trois valeurs possibles :


 * aucune valeur retournée (ou nul): le gestionnaire de l'attache s'est bien exécuté. (Avant MediaWiki 1.23, il était nécessaire de retourner la valeur vrai.)
 * "une chaîne de caractères": une erreur est survenue; le traitement doit s'arrêter et l'erreur doit être affichée à l'utilisateur
 * faux : le gestionnaire de l'attache a fait le travail demandé, ou s'est substitué au traitement normal. Cela empêche les autres gestionnaires d'être exécutés, et dans certains cas cela permet à la fonction appelante de sauter le traitement normal.

Retourner faux donne moins de sens aux événements pour lesquels l'action est terminée, et sera normalement ignoré par l'appelant.

Comportement de l'accroche avant MediaWiki 1.22 et après
Extrait de : change 500542: pour les accroches non abortables (cas de la plupart des accroches) retourner vrai est redondant depuis MediaWiki 1.22 (en 2015). Ceci a été fait pour réduire les chances d'un disfonctionnement accidentel parce que nous avons expérimenté plusieurs pannes et fonctionalités cassées à cause de fautes silencieuses où par exemple une fonction de callback quelque part a involontairement retourné un non booléen ou bien faux au lieu de vrai/void et a ainsi court-circuité tout le système.

(Returner non-vrai/non-void dans une accroche MediaWiki est équivalent à  et   pour les événements JavaScript, cela tue les autres écouteurs du même événement).

Par exemple, si l'accroche  devait retourner faux dans MobileFrontend, cela signifierait que Popups s'est arrêté car son callback ne s'exécute plus. Voir les différences ci-dessous, en supposant que l'accroche est.

Avant MediaWiki 1.22

ou

MediaWiki 1.22+

Documentation
Actuellement, les accroches du coeur de MediaWiki doivent être documentées à la fois dans (dans le dépôt de code source) et ici sur MediaWiki.org. Dans certaines situations, un de ces endroits peut ne pas encore être finalisé, aussi si une accroche paraît non documentée, vérifiez les deux cas.

Pour documenter une accroche de wiki, utilisez MediaWikiHook.

Accroches disponibles
Pour une liste complète des accroches, utilisez la, qui devrait être plus à jour.

Voir aussi

 * — documentation of the hooks in MediaWiki core
 * — contains examples of hooks
 * — the JavaScript/front-end system of hooks
 * — documentation of the hooks in MediaWiki core
 * — contains examples of hooks
 * — the JavaScript/front-end system of hooks
 * — the JavaScript/front-end system of hooks