Créer un shortcode avec WordPress

Plus de 7 minutes 🙂

Introduction

Les shortcodes kesako ? C’est assez simple, en fait un shortcode est un peu comme un tag html, il permet de donner du sens et avoir un comportement spécial en fonction des attributs que l’on peut lui donner.

Par exemple si je fais <br/> le navigateur va interpréter ça comme un saut de ligne, si je fais <b>mon texte</b> alors le texte entre les balises b sera mis en gras. Mais toutes ces manipulations sont transparentes pour nous ! Pour un néophyte il ne lui viendrait pas à l’idée que la page actuelle qu’il consulte est en fait une interprétation par le navigateur d’un fichier texte.

Les shortcodes c’est pareil, parfois dans un site WordPress on a des éléments qui sont plus que du texte, une vidéo ou de la mise en forme. On a besoin d’aller chercher dynamiquement, ou non, des informations dans le site pour les afficher. Un shortcode se comporte comme un élément HTML avant interprétation. Vous en avez déjà vu quelque par et nativement dans WordPress il y en à au moins un que vous connaissez : la galerie.

Les types de shortcodes

Il y a donc deux types de shortcodes dans WordPress comme pour le HTML, les éléments auto-fermants et les éléments qui englobent du contenu. Sachez bien que l’on peut faire comme la HTML mixer les shortcodes et les imbriquer autant que l’on veut. Il faut juste savoir que les shortcodes sont interprétés à l’affichage du contenu, sur le filtre ‘the_content’

Les tags auto-fermants, c’est le shortcode de la galerie par exemple : [galery] (j’ai mis un seul « l » pour gallery pour que WordPress ne l’interprète pas).

Les tags qui comportent du contenu, c’est alors que l’on va mettre du contenu pour lui donner du sens. Imaginons que l’on veuille afficher un contenu entre des balises spéciales en HTML, qui vont inclure toute une structure HTML avant et après le contenu. On va faire quelque chose du genre :

[structure-speciale]Mon beau contenu qui a un style avant et après[/structure-speciale]

Nous avons donc du contenu inséré entre deux « balises » qui le délimitent et permettent de manipuler le contenu.*

On peut même faire un mix des deux, comme ici :

[structure-speciale]Mon beau contenu qui a un style avant et après : [galery][/structure-speciale]

Nous avons donc un contenu dans un shortcode qui comporte un shortcode, c’est imbriqué et comme par magie ça marche ! 🙂

Les attributs

Vous allez me dire, c’est bien beau tes shortcodes mais là c’est vite limité, si je veux que ma mise en forme comporte aussi des petites améliorations comme la largeur du contenu ou alors les différentes images qui sont comprises dans la gallerie, si vous êtes un vieu de WordPress vous vous souviendrez du shortcode galerie qui prend toutes les images associées au post courant pour créer la galerie. Pratique mais pas toujours, on peut aussi choisir le colonage.

Pour parvenir a nos fins, dans l’API des shortcodes il y a la possibilité d’ajouter des paramètres, autant de paramètres que l’on veut et les utiliser de l’autre côté à notre guise. Par exemple on va pouvoir faire :

[structure-speciale color="red" type="list" columns="5" ]Mon beau contenu qui a un style avant et après[/structure-speciale]

Bref avec ça on va pouvoir modifier le comportement natif du shortcode et lui ajouter des petites améliorations au fur et à mesure.

Un cas concret

La théorie c’est bien beau mais passons à la pratique. Le shortcode permet à mon rédacteur d’afficher du contenu dynamique dans son contenu sans avoir à connaître le HTML ou le PHP.

Imaginons que notre site est en fait un site d’actualités de musique, qui comporte un type de contenu album qui contient lui même des informations quand à l’artiste, la date, la note etc…

Disons que mon rédacteur fait un article où il va vouloir afficher les informations d’albums au fur et à mesure de son article pour lier son contenu et les albums de son site. Sans les shortcodes, il doit aller chercher les images des albums, l’artiste, l’année. Si un autre auteur a fait une coquille dans cet album, alors il faudra aller le corriger sur les articles qui en font mention. Bref c’est fastidieux et long..

Nous allons donc faire un shortcode qui permet d’afficher un album dans le contenu et surtout permettre de plus finement mettre en valeur une information ou l’autre.

Le plugin

Le plugin va comporter quelques fichiers et permettre aux développeurs de thèmes de modifier le comportement de notre shortcode, voici la structure :

shortcode-album.php -> le fichier principal de notre plugin

–classes

— shortcode.php -> notre shortcode

–views -> les vues du plugin

—shortcode.php -> La vue d’affichage de notre shortcode

On va faire un peu d’objet, surtout pour pouvoir ne pas entrer en collision avec d’autres fonctions.

Voici le contenu du fichier de base :

[pastacode lang= »php » path_id= »78e1357d51f4c7954c73#file-shortcode-album-php » highlight= » » lines= » » provider= »gist »/]

Dans ce fichier on déclare simplement l’en-tête de base de notre plugin, on charge les fichiers et quand on peut, on charge notre classe à shortcodes.

 

Voici le contenu du fichier pour la gestion de notre shortcode :

[pastacode lang= »php » path_id= »eba07ba51173a96dd48f#file-shortcode-php » highlight= » » lines= » » provider= »gist »/]

Au moment de la construction de la classe on se cale sur l’action init et on ajoute notre shortcode avec la méthode « add_shortcode »  qui attend un paramètre de callbakc, un peu comme un filtre. C’est un peu un filtre car il attend un retour de notre fonction, donc pas question d’afficher quoique se soit dans notre méthode.

Dans notre méthode « shortcode » nous avons en premier paramètre les attributs entrés, en deuxième le contenu optionnel. Dans notre cas nous n’entourons pas le contenu mais si jamais la personne se trompe, alors on va quand même retourner le contenu.

Avec la fonction ‘shortcode_atts’ on s’autorise à avoir des valeurs par défaut à nos attributs, la meilleure manière de faire est de bien remplir le troisième paramètre(optionnel) pour permettre à des plugins de filtrer les attributs en dernière seconde ou tout autre utilisation, mais j’y reviendrait en fin d’article.

Il faut alors faire quelques vérifications pour être sûr que notre utilisateur ait bien entré un contenu et on offre une variable ($album)  au développeur de la vue du shortcode pour faire ses opérations facilement dessus.

Et là on va chercher le template pour l’affichage, il va faire la chose suivante :

1. Chercher dans le thème enfant s’il existe
2. Chercher dans le thème parent s’il existe
3. Chercher en dernier recours le fichier dans le plugin

On propose donc un template par défaut de notre shortcode à notre utilisateur et s’il veut le transformer, il a juste besoin de dupliquer le fichier du plugin pour le mettre dans son thème pour qu’il soit chargé à la place et modifier l’apparence et la structure du template.

Le template le voilà :

[pastacode lang= »php » path_id= »e898dc2f2f587cde38e3″ highlight= » » lines= » » provider= »gist »/]

 

C’est un fichier assez simple, comme vous pouvez le voir les variables sont disponibles car nous incluons directement le fichier, pas comme avec « get_template_part » . On va alors utiliser notre objet pour aller chercher les données de l’album ainsi que les métas en faisant $album->year par exemple.

Si vous regardez bien on crée un buffer avec « ob_start » pour que le HTML généré dans la page s’affiche n’importe où dans la page, pensez aux filtres, ils attendent une valeur de retour.

Voilà vous avez fait votre premier shortcode !

Pour aller plus loin

Alors vous allez me dire « Oui mais la syntaxe est pas très user friendly, et mon client a pas envie de taper le code à la main et connaître les paramètres », et là je vous répond que oui c’est pas forcément pratique. Deux solutions s’offrent à vous :

1. Coder un bouton dans l’éditeur tinymce, mais ça peut être long et fastidieux
2. Utiliser un super plugin qui vient de sortir

Et ce plugin qui vient de sortir c’est Shortcake, on en parle sur WPTavern et ils ont un github. Le plugin est bien fait car il permet de donner les attributs à remplir par l’utilisateur et une interface pour interagir avec !

Et là le fait d’avoir rempli le 3ème paramètre de shortcode_atts prend tout son sens, ils peuvent alors voir tous les paramètres de base d’un shortcode et proposer automatiquement une interface même s’il n’est pas déclaré dans le plugin.

Il y a aussi Shortcode Suggest qui permet de proposer tous les shortcodes du site et les auto-compléter, il ya aussi un article sur WPTavern et un repository github.

Conclusion

Avec ce type de développement vous pouvez proposer une manière d’afficher le contenu dans votre site et surtout en tant que développeur une possibilité d’afficher des données dynamiques dans une contenu, là où l’utilisateur le souhaite. Par exemple le shortcode ’embed’ intégré à WordPress permet d’afficher des médias très facilement et surtout filtrer les données affichées et le développeur peut de lui même réécrire le contenu affiché.

Plusieurs plugins se basent exclusivement sur ça pour faire le contenu, le très connu Visual composer est un ensemble de shortcodes qui composent le contenu et à l’affichage du contenu, on va rendre les shortcodes il y a aussi beaucoup de plugins destinés à ajouter des shortcodes dans WordPress : https://wordpress.org/plugins/search.php?q=shortcode.