Les « hooks » dans WordPress

▼Publicité

Un « hook », parfois appelé crochet, emprise ou point d'entrée, est un mécanisme permettant aux développeurs d'effectuer une action précise à un moment particulier. Les développeurs de WordPress ont ainsi prévu de placer un hook à différents endroits, comme par exemple lors de l'affichage du titre d'une page. Ceci permet au développeur d'un thème ou d'une extension de modifier la façon dont le titre de la page est affiché sans avoir à modifier le code de WordPress.

Action vs filtre

Les hooks sont classés en deux catégories : les actions et les filtres.

Les actions sont basées sur des événements. Par exemple, le hook publish_post permet d'ajouter des fonctionnalités qui seront exécutées à chaque fois qu'un article est publié.

Les filtres, quant à eux, permettent de modifier le texte qui sera affiché à l'écran ou enregistré dans la BD. Par exemple, le hook the_title permet d'ajuster la façon dont le titre d'un article ou d'une page sera affiché à l'écran.

Illustration d'un hook de type filtre

Tentons d'illustrer le fonctionnement d'un hook de type filtre.

Prenons une fonction hypothétique définie dans l'API WordPress. Disons que cette fonction s'appelle une_fonction(). Elle s'occupe de récupérer une donnée dans la base de données puis de l'afficher à l'écran.

Mais avant d'afficher la donnée, elle met à la disposition des développeurs un point d'ancrage où ils pourront s'accrocher pour intervenir sur la donnée avant qu'elle ne soit affichée.

Fonction API WordPress définissant un hook

Sans même utiliser les hooks, un thème peut utiliser cette fonction pour afficher la donnée à l'endroit où il le souhaite.

Fichier modèle qui appelle une fonction de l'API

Toujours sans utiliser les hooks, il est possible, pour un thème enfant, d'apporter une modification à cette donnée avant qu'elle ne soit affichée en copiant le fichier modèle dans le thème enfant. Le thème enfant pourrait, par exemple, appliquer une classe CSS différente selon que la donnée est affichée dans une page ou dans un article.

Fichier modèle copié puis adapté dans le thème enfant

Le problème avec cette approche, c'est que lors de la mise à jour du thème parent, si des ajouts ont été apportés à ce fichier modèle, il faudra recopier ces ajouts dans le thème enfant pour qu'ils soient effectifs.

C'est ici que les hooks deviennent intéressants : plutôt que de recopier le fichier modèle, on lancera notre crochet au point d'ancrage prévu par la fonction afin d'y apporter les ajustements souhaités­. Ainsi, lorsque le fichier modèle du thème parent appellera la fonction, la donnée affichée sera celle retournée par la fonction associée au hook.

Exemple d'utilisation d'un hook

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' );

Quelques exemples d'utilisation des hooks

Rien de mieux qu'un exemple concret pour comprendre.

Voici un exemple d'utilisation d'un hook d'action, permettant d'envoyer un courriel à chaque fois qu'un article est ajouté au blogue1.

WordPress (PHP)

function monprefixe_email_friends( $post_ID ) {

   $friends = 'bob@example.org, susie@example.org';

   wp_mail( $friends, "sally's blog updated", 'I just put something on my blog: http://blog.example.com' );

 

   return $post_ID;

}

 

add_action( 'publish_post', 'monprefixe_email_friends' );

Voici maintenant un exemple d'utilisation d'un hook de type filtre. Son rôle est d'englober le titre d'un article dans un <div> afin de pouvoir contrôler son apparence par CSS. Remarquez que la fonction reçoit en paramètre ce qui aurait été affiché sans le hook et qu'elle retourne ce qui sera effectivement affiché.

WordPress (PHP)

function monprefixe_englober_titre_dans_div( $titrearticle ) {

    return '<div class="titre">' . $titrearticle  . '</div>';

}

 

add_filter( 'the_title', 'monprefixe_englober_titre_dans_div' );

Dans ce dernier exemple, on utilise un filtre pour que les nouvelles pages et les nouveaux articles aient chacun leur texte par défaut quand ils sont créés dans le tableau de bord WordPress

Remarquez l'utilisation de global pour accéder à une variable définie par WordPress, donc en dehors de la fonction.

WordPress (PHP)

function monprefixe_texte_par_defaut_pour_pages_et_articles( $content ) {

    global $post_type;

 

    if ( $post_type == 'page' ) {

        $content = "Contenu par défaut pour les pages";

    } else {

        $content = "Contenu par défaut pour les articles";

    }

 

    return $content;

}

 

add_filter('default_content', 'monprefixe_texte_par_defaut_pour_pages_et_articles');

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

« Function Reference/add action ». Codex WordPress. http://codex.wordpress.org/Function_Reference/add_action

« Function Reference/add filter ». Codex WordPress. http://codex.wordpress.org/Function_Reference/add_filter

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

« Hooks WordPress ». GeekPress. http://www.geekpress.fr/hooks-wordpress/

« Comment traduiriez-vous « hook » ? ». WordPress francophone. http://www.wordpress-fr.net/2008/08/20/comment-traduiriez-vous-hook/

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

Source

1. « Function Reference/add action ». Codex WordPress. http://codex.wordpress.org/Function_Reference/add_action

Merci de partager ! Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInPin on PinterestShare on StumbleUponEmail this to someone
Catégories

9 commentaires

  1. sadou

    Bonjour;

    merci pour le tuto !

    Est-il possible d’utiliser un hook ( add_filter) sur une fonction d’un plugin
    où cela est-il uniquement permis sur les fonctions natives wordpress ?

    d’avance merci de votre réponse.

    • Christiane Lagacé

      Bonjour Sadou,

      Je ne suis pas certaine de bien comprendre votre question. Est-ce que vous développez ce plugin ou bien vous utilisez un plugin existant? C’est faisable dans les deux cas, et autant pour les plugins que pour les fonctions natives de WordPress.

      Si vous travaillez avec un plugin existant et que ce plugin met des hooks à votre disposition, vous pouvez bien entendu utiliser ces hooks à votre convenance à l’aide de add_filter() et de add_action().

      Et si vous le développez, vous pouvez créer de nouveaux hooks, autant des filtres que des actions, avec apply_filters() et do_action().

      Bon développement !
      Christiane

  2. sadou

    Bonjour Christiane,

    Merci beaucoup de votre réponse rapide !

    En fait, je souhaite apporter une modification à un fichier source d’un plugin existant.
    J’obtiens bien le résultat attendu en modifiant ce fichier.
    Mais je préfère utiliser add_filter pour ne pas faire de modifications directes dans le plugin.
    Par contre je ne sais pas si ce plugin a prévu des hooks.
    Comment et où puis-je vérifier cela.

    D’avance merci de votre réponse.

    Bonne journée.

    Sadou.

    • Christiane Lagacé

      Un bon plugin devrait être accompagné de documentation qui donne la liste des hooks disponibles.

      Si ce n’est pas le cas, il est possible de rechercher dans le code source les lignes faisant appel à apply_filters() ou do_action(). Ce sont ces fonctions qui permettent aux développeurs de créer de nouveaux hooks dans leurs plugins. Leur premier paramètre est le nom du hook et le ou les paramètres suivants sont les valeurs qui seront passées à la fonction de rappel dans votre code.

      Autre possibilité : vous pouvez redéfinir un shortcode sans toucher le code original si le développeur du plugin qui définit le shortcode a pris soin de passer un troisième argument dans l’appel à shortcode_atts(). Ce troisième argument permet la création d’un nouveau hook dont le nom sera « shortcode_atts_ » suivi de la chaîne passée comme 3e argument (voir http://christianelagace.com/wordpress/les-shortcodes-wordpress/).

      Si par malheur le développeur du plugin n’a pas prévu de hook, il est possible de simplement redéfinir les fonctions désirées à condition que le développeur ait utilisé if ( ! function_exists() ) avant de définir ses fonctions. Une dernière possibilité, qui dépend également de la façon dont le plugin a été codé, consiste à créer votre propre classe dérivée de celle du plugin original.

      Bonne chance !
      Christiane

  3. Marie-Hélène

    Bonjour,
    Je me heurte moi aussi à la modification d’un plug-in, et hélas je crains d’avoir quelques lacunes de base.
    Pas de hooks définis dans la doc, bien sûr, mais seulement des paramètres qui ne sont pas suffisants pour les modifs que je veux effectuer.
    Admettons que je choisisse la solution de « modifier une fonction » de ce plug-in.
    Cette fonction est définie dans un php (qui contient d’autres fonctions) qui est par exemple : www/wamp/mon-site/wp-content/plugins/le-plug-in/le-script.php
    Où et comment redéfinir cette fonction ?

    • Christiane Lagacé

      Bonjour Marie-Hélène,

      Tout dépend de la façon dont ce plugin a été défini.

      Si le développeur du plugin a utilisé if ( ! function_exists() ) avant de définir sa fonction, vous pourrez définir la fonction dans le fichier functions.php de votre thème. Cette fonction aura exactement le même nom que la fonction à modifier. Vous pouvez y copier-coller le code de la fonction originale et y apporter vos modifications.

      Dans le cas où le développeur du plugin n’a pris aucune précaution, vous devrez modifier le code du plugin directement. Le défaut de cette approche, c’est que vos modifications seront perdues lorsque le plugin sera mis à jour.

      J’espère que ceci répond à votre question.

      Bonne chance !

      Christiane