27.2 Utiliser un hook

Pour utiliser un hook, deux étapes sont nécessaires :

• Écrire la fonction qui devra être exécutée par le hook. On appellera cette fonction fonction de rappel (callback function). Les paramètres que la fonction doit recevoir dépendent du hook utilisé. Il est prudent de précéder le nom de chacune de nos fonctions par un préfixe de notre choix. Ceci permettra d'éviter les conflits de noms si un thème ou une extension définissait elle aussi une fonction du même nom.
• Associer le hook à la fonction de rappel ou, si vous préférez, enregistrer le hook. Ceci sera fait à l'aide de :

  • S'il s'agit d'un hook de type action :

    WordPress (PHP)

    add_action( 'nom_du_hook', 'nom_de_la_fonction_de_rappel' );

  • S'il s'agit d'un hook de type filtre :

    WordPress (PHP)

    add_filter( 'nom_du_hook', 'nom_de_la_fonction_de_rappel' );

Étapes détaillées

Les étapes présentées plus haut constituent le grand principe pour faire fonctionner le hook. Dans la pratique, une liste plus détaillée pourrait être nécessaire.

1. Commencez par trouver le bon hook.

   • Vous pouvez rechercher dans la documentation WordPress. L'article The WordPress Hooks Firing Sequence! est également un excellent point de départ.
   • Si vous n'arrivez pas à trouver dans la documentation WordPress, peut-être que le hook n'existe pas dans le noyau WordPress. Vérifiez si l'éditeur de votre thème ou de l'une de vos extensions a prévu un hook pour ce que vous recherchez.
   • Effectuez une recherche dans tout le code de votre site Web, incluant le noyau WordPress, le thème parent et les extensions que vous utilisez, sur les mots « do_action » et « apply_filters ». Il s'agit des fonctions qui permettent de définir le point d'entrée d'un hook. Vous verrez alors à quel endroit les hooks sont définis et comment ils sont définis.
   • En dernier recours, effectuez une recherche sur Google. La communauté WordPress est très grande, vous devriez trouver ce que vous cherchez, que ce soit un hook du noyau WordPress ou de votre thème.

2. Consultez la documentation du hook, si elle est disponible, afin de connaître les paramètres que la fonction de rappel doit recevoir et ce qu'elle doit retourner.

3. Choisissez où rédiger le contenu de la fonction de rappel du hook.

   • Si le code doit être rattaché au thème, la fonction fera partie de functions.php.
   • Si le code doit être rattaché à une extension, la fonction fera partie de la classe de l’extension.

4. Débutez la rédaction de la fonction de rappel.

   Créez le squelette en tenant compte des paramètres à recevoir et des valeurs à retourner. Inspirez-vous des exemples trouvés dans la doc.

   WordPress (PHP)

   function monprefixe_replace_content( $content ) {
       // votre code ici

       return $content;

   }

5. Trouvez la logique PHP à mettre en place pour parvenir à vos fins. Vous pouvez vous aider en consultant la doc PHP ou la doc WordPress.

6. Au besoin, ajustez le code pour qu'il ne soit exécuté que pour les pages ($post_type == 'page'), pour les articles (is_single()), pour la page d'accueil (is_front_page()), etc.

7. Rattachez la fonction de rappel au hook.

   Il faut ajouter le hook juste avant ou juste après la définition de la fonction de rappel.

   • Un hook de type filtre utilise add_filter().
   • Un hook de type action utilise add_action().
   WordPress (PHP)

   add_filter( 'the_content', 'monprefixe_replace_content' );

8. Testez le tout.

Pour plus d'information

« Plugin API ». Codex WordPress. http://codex.wordpress.org/User:Guigui/fr:Plugin_API

« Code Reference : hooks ». Developer.WordPress. https://developer.wordpress.org/reference/hooks/

« Plugin API/Action Reference ». Codex WordPress. http://codex.wordpress.org/Plugin_API/Action_Reference

« Plugin API/Filter Reference ». Codex WordPress. http://codex.wordpress.org/Plugin_API/Filter_Reference

« WordPress Hooks Database ». Adam R. Brown. http://adambrown.info/p/wp_hooks

« WordPress Essentials: The Definitive Guide To WordPress Hooks ». Smashing magazine. http://wp.smashingmagazine.com/2011/10/07/definitive-guide-wordpress-hooks/

«  The WordPress Hooks Firing Sequence! ». RachieVee: Rachel's Blog. http://rachievee.com/the-wordpress-hooks-firing-sequence/