WordPress : les shortcodes pour automatiser certains contenus
Si vous utilisez régulièrement WordPress, vous n’êtes sans doute pas passé à côté des shortcodes, ces petits bouts de texte pouvant créer toutes sortes de contenu. Si le nom shortcode ne vous dit rien, leurs formes va peut-être vous parler un peu plus : [nomdushortcode] ou bien encore [nomdushortcode attribut= »valeur »]. Ça vous revient ? On en trouve un peu partout, que ce soit dans le WordPress de base ou dans les plugins qu’on peut lui ajouter, et nous allons voir ici comment créer les nôtres.
La première question à se poser, c’est quand utiliser un shortcode. La réponse est simple : dès que vous voulez automatiser certains types de contenus. Par exemple, WordPress s’en sert pour ajouter une galerie : quand vous écrivez un article, le shortcode [ galley ids= »1,2,3″] (sans espace évidemment) suffit à ajouter une galerie affichant les images dont les IDs sont 1, 2 et 3. Dans l’article lui-même, il n’y a que ça, mais ce n’est bien évidemment pas ce qui est affiché : lors de l’affichage, WordPress a vu ce shortcode et sait ce qu’il doit faire.
Mais bien sûr, WordPress ne peut pas deviner l’usage que vous voulez pour votre shortcode, et il va donc falloir l’enregistrer pour que le CMS sache quoi chercher dans les contenus. Là où réside toute la puissance des shortcodes, c’est que ce simple enregistrement suffit, rien de plus n’est nécessaire : dès qu’un shortcode sera détecté, où qu’il soit, il sera transformé selon vos désirs. Pratique.
Tout le long de cet article, nous allons voir un exemple très simple, mais qui suffira à comprendre ce que nous voulons : notre shortcode sera [hello] et sera remplacé par un « Hello World! » dans l’article affiché. Nous verrons ensuite comment lui ajouter des attributs, tout un programme !
Enregistrer un shortcode
L’enregistrement d’un shortcode se fait de la même manière, que vous cherchiez à le faire pour un plugin ou dans un thème. Par exemple, dans votre thème, il suffira de rajouter tout ce que nous verrons dans le fichier functions.php. Comme d’habitude donc.
L’enregistrement en lui-même est d’une simplicité déconcertante puisqu’elle passe par la seule fonction add_shortcode() qui accepte deux arguments : le nom du shortcode qui sera dans notre cas « hello« , et la fonction à appeler dès que ce shortcode est trouvé.
<?php add_shortcode('hello', 'transformer_hello'); ?> |
Et voila. Dès que WordPress trouvera le shortcode [hello] dans un article ou une page, par exemple, il appellera votre fonction. C’est magique.
La fonction de gestion du shortcode
Une telle fonction n’est pas très difficile à créer : il s’agit d’une fonction toute bête, comme nous les connaissons bien et qui doit attendre un argument, qu’on l’utilise ou non. Cet argument, WordPress s’en servira pour nous transmettre les attributs donnés au shortcode et leurs valeurs. Dernier détail : le plus souvent, votre shortcode devra être remplacé par du texte, quel qu’il soit. Pour faire cela, il suffira de retourner le texte voulu. Comme un bon exemple vaut mieux que trois pages d’explications, voici :
<?php function transformer_hello($atts) { return 'Hello World!'; } ?> |
À ce stade, si nous ne voulions rien de plus, tout est prêt : dans un article ou une page, on indique le shortcode [hello] et, dès que le contenu sera affiché, WordPress transformera ce shortcode en « Hello World!« . Déconcertant de simplicité, n’est-ce pas ?
Histoire de compliquer un peu les choses, nous allons maintenant voir comment gérer des attributs. Enfin, compliquer, ce n’est pas vraiment exact puisque, là encore, c’est très simple.
Et les attributs ?
Comme nous l’avons déjà dit, les attributs transmis le seront via l’argument de notre fonction, soit la variable $atts dans notre exemple un poil plus haut. Cet argument, comme vous l’imaginez sûrement, est un array associatif : chaque clé représente le nom de l’attribut et la valeur associée est la valeur de l’attribut.
Par exemple, imaginons que l’utilisateur utilise ce shortcode : [hello nom= »Moi » n= »3″]. L’array contenant les attributs sera alors de cette forme :
Array ( [nom] => Moi [n] => 3 )
Bien sûr, dans l’état, le résultat sera le même puisque notre fonction se fout totalement du fait qu’on ait des attributs ou non. Justement, changeons cela.
Nous afficherons désormais « Hello [nom choisit dans l’attribut correspondant]!« . De plus, histoire de voir toute la puissance des shortcodes, nous afficherons ce message autant de fois qu’indiqué dans l’attribut n.
<?php function transformer_hello($atts) { $sortie = ''; for ($i = 0; $i < $atts['n']; $i++) $sortie .= 'Hello ' . $atts['nom'] . '!'; return $sortie; } ?> |
Pas grand-chose à dire de plus, je pense… Sauf peut-être répondre à une question que vous devriez vous poser : dans cet exemple, que se passe-t-il si l’utilisateur ne fournit pas les attributs utilisés, comme par exemple [hello nom= »Moi »] sans l’attribut n ?
La réponse est simple : PHP ira chercher dans l’array une clé qui n’existe pas et nous renverra donc une belle erreur. Pour changer cela, il nous faut gérer des valeurs d’attributs par défaut et, heureusement, WordPress a tout prévu grâce à la fonction shortcode_atts().
Gérer les valeurs par défaut des attributs
La fonction shortcode_atts() attend deux arguments, le deuxième étant la variable contenant les attributs utilisés par l’utilisateur (ceux de la variable $atts, donc). La premier argument est un autre array, entièrement géré par vous-même, contenant des attributs et leurs valeurs par défaut. Ainsi, nous pourrions modifier notre fonction et ajouter cette ligne en tout début :
<?php $atts = shortcode_atts(array('nom' => 'World', 'n' => 1), $atts); ?> |
En faisant cela, l’utilisateur peut appeler notre shortcode de différentes façons : [hello] affichera « Hello World! » une fois, [hello n= »55″] l’affichera 55 fois, [hello nom= »Moi »] affichera « Hello Moi! » une fois, etc..
Comme vous pouvez le constater, les shortcodes sont une API très puissante et pourtant très facile à utiliser. Elle permet d’éviter les expressions régulières de votre cru si vous vouliez les gérer vous-même et simplifie ainsi grandement la tâche.
