Nous avons déjà vu comment gérer des shortcodes sous WordPress pour faciliter l’insertion de certains contenus récurrents dans vos pages ou articles. Nos shortcodes utilisaient jusque-là différents attributs qui pouvaient d’ailleurs aussi être sans nom comme on l’a vu la dernière fois. Mais vous pensiez réellement qu’on avait fait le tour de l’API ? En réalité il nous faut encore voir quelques détails pour être sûrs d’avoir vu tout ce dont nous avons besoin, et c’est justement ce qu’on va faire ici.

WordPress

Du contenu dans nos shortcodes

Si vous êtes familier de WordPress, vous avez sûrement déjà croisé des shortcodes comme on en crée depuis les premières parties, mais pas seulement. Car un shortcode peut posséder une autre forme que celle utilisée jusque maintenant, une forme qui rappelle un peu les balises HTML : [shortcode]contenu[/shortcode].

Plutôt que de n’utiliser qu’une forme simple comme on le fait depuis le début, on peut en effet choisir d’utiliser une forme ouvrante / fermante. Ça a plusieurs avantages et inconvénients, et il vous revient de faire la part des choses pour savoir quelle solution vous conviendra le mieux.

Quoiqu’il en soit, gérer du contenu est d’une simplicité enfantine, tellement que c’en est presque risible de l’aborder : il suffit en effet de modifier notre fonction de callback, celle qui est appelée chaque fois que WordPress trouve l’un de nos shortcodes. Cette fonction peut en effet supporter un deuxième attribut qui contiendra justement le contenu envoyé. Peut-on seulement faire plus simple ?

Dans cet exemple tiré de la première partie, nous modifions ce qui sera affiché en concaténant simplement le contenu du shortcode à « Hello World!« . Ainsi, si l’utilisateur envoie [hello]toto[/hello], alors le shortcode affichera automatiquement « Hello World! toto« .

C’est tout ce qu’il y a à savoir sur la gestion d’un contenu dans les shortcodes. Le détail intéressant, c’est que vous pouvez bien sûr utiliser du contenu et des attributs, afin de créer un shortcode des plus puissants. Et ça c’est cool.

Plusieurs shortcodes pour une même fonction de callback

Nous arrivons ici dans une situation qui pourrait paraître plus délicate, à savoir la gestion de plusieurs shortcodes dans une seule et unique fonction de callback. C’est effectivement possible et peut être utile si plusieurs shortcodes font presque la même chose par exemple. Mais c’est très loin d’être insurmontable à gérer.

Imaginons deux shortcodes [hello] et [plop] (admirez l’imagination dans ces noms, c’est tout simplement remarquable) et faisons en sorte que ce soit la même fonction qui soit appelée :

Si on ne fait rien de plus, nos deux shortcodes seront exactement les mêmes, ce qui est un peu inutile. C’est pourquoi il existe un troisième (et dernier, enfin pour l’instant) argument possible pour les fonctions de callback : le nom du shortcode.

Dans l’appel de add_shortcode(), nous n’avons rien à faire, tout change dans la fonction de callback en question, où vous devez ajouter un troisième paramètre :

Et c’est à peu près tout en fait. Le paramètre $tag contiendra le nom du shortcode choisi par l’utilisateur et vaudra dans notre cas « hello » ou « plop« . La suite dépend donc de vous et de la différence que vous voulez donner aux shortcodes.

À noter que le WordPress Codex référence un comportement étrange lorsqu’on gère plusieurs noms. Selon cette page, si deux shortcodes utilisent la même fonction de callback et que le nom du shortcode diffère de celui de la fonction, alors l’entrée 0 de l’argument $atts vaudra la chaîne de caractère repérée par WordPress, c’est-à-dire tout le shortcode envoyé par l’utilisateur. Je n’ai cependant pas réussi à reproduire ce comportement et il semblerait donc qu’il ait été corrigé depuis. Quoiqu’il en soit, il ne vous affectera que si vous devez gérer des attributs sans nom.

Un shortcode dans un shortcode dans un shortcode…

… dans un shortcode. Vous l’aurez compris, nous allons aborder ici la question de shortcodes imbriqués, qui ne se pose que si vous gérez du contenu pour vos shortcodes. Un exemple ? Prenons deux shortcodes, dont notre bon vieux [hello] accompagné d’un shortcode [monde] qui affiche le mot « monde« . Parce que faire compliqué ne sert à rien.

Modifions notre shortcode [hello] qui ne dira plus que « Hello contenu!« , désormais, avec « contenu » remplacé par le contenu du shortcode. Notre shortcode [monde], lui, affichera simplement le mot « monde » là où il est. Je pense qu’il est inutile de vous montrer comment faire ces choses-là…

Si l’utilisateur écrit « [hello]World[/hello] [monde]« , tout va bien, nous afficherons « Hello World! monde » et c’est tout. C’est con, ça sert à rien, mais on s’en fout. Imaginons plutôt que l’utilisateur choisisse d’écrire « [hello]le [monde][/hello]« . Là, tout va mal.

WordPress ne fait qu’un seul tour pour gérer les shortcodes, et indiquer la chaîne précédente produira donc le résultat « Hello le [monde]! » : le shortcode [monde] n’a tout simplement pas été interprété !

Bien sûr, peut-être ne voudrez-vous pas qu’ils le soient justement. Mais selon les besoins, c’est un peu ennuyeux. Heureusement, WordPress a pensé à tout et nous fournit la fonction qu’il nous faut : do_shortcode().

Cette fonction s’utilise de façon très simple, en indiquant en paramètre la chaîne que WordPress doit traiter, celle où il faut éventuellement aller chercher des shortcodes. Aussi, nous pourrions l’utiliser comme ceci dans notre cas :

Et là, tout va bien : utiliser la chaîne qui posait problème jusque maintenant produira le résultat « Hello le monde!« , exactement comme on le souhaitait.

A-t-on vraiment fait le tour ce coup-ci ?

Pas vraiment. En fait, il reste encore toute une multitude de petits détails que je n’ai pas abordé. Cependant, ce sont vraiment de tout petits détails qui ne nécessitent guère d’explications et je vous laisse donc vous débrouiller seul pour ceux-ci. Bien sûr, n’hésitez pas à laisser un commentaire si jamais vous avez des questions concernant un détail à rajouter, ou si vous avez une idée de comportement qui nécessiterait un tutoriel entier.

Avec tout ce que nous avons vu, vous êtes normalement capable de créer des shortcodes très puissants. Pensez-y un peu, l’espace d’un instant : nous pouvons créer des shortcodes simples, sans aucun paramètre à indiquer, ou nous pouvons gérer des attributs plus complexes, avec du contenu et des attributs, avec ou sans nom.

Notez pour finir que vous pouvez bien sûr mixer les shortcodes avec des boutons, nous avons déjà vu comment insérer du contenu dans les éditeurs de WordPress. D’ailleurs, pour ceux qui se posent la question, c’est exactement ce qui est fait pour WP Photo Sphere : le bouton média « Ajouter un panorama » permet de sélectionner un panorama, inséré sous forme de shortcode lui-même géré par l’API de WordPress. Comme quoi, on peut en faire des choses.