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 le.

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.

Register the event handler by adding it to the global array for a given event. Hooks can be added from any point in the execution before the hook is called, but are most commonly added in, its included files, or, for extensions, in the file extension.json. All the following are valid ways to define a hook function for the event EventName that is passed two parameters, showing the code that will be executed when EventName happens:

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

When an event occurs, the function (or object method) that you registered will be called, the event's parameters, along with any optional data you provided at registration. Note that when an object is the hook and you didn't specify a method, the method called is 'onEventName'. For other events this would be 'onArticleSave', 'onUserLogin', etc.

The optional data is useful if you want to use the same function or object for different purposes. For example:

This code would result in ircNotify being run twice when a page is saved: once for 'TimStarling', and once for 'brion'.

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


 * no return value (or null): the hook handler has operated successfully. (Before MediaWiki 1.23, returning true was required.)
 * "some string": an error occurred; processing should stop and the error should be shown to the user
 * false: the hook handler has done all the work necessary, or replaced normal handling. This will prevent further handlers from being run, and in some cases tells the calling function to skip normal processing.

Returning false makes less sense for events where the action is complete, and will normally be ignored by the caller.

Documentation
Currently, hooks in MediaWiki core have to be documented both in (in the source code repository) and here on MediaWiki.org. In some cases, one of these steps may not yet have been completed, so if a hook appears undocumented, check both.

Pour documenter une accroche de wiki, utilisez MediaWikiHook.

Available hooks
Pour une liste complète des accroches, utilisez la catégorie, qui devrait être plus à jour