Comprendre les codes courts WordPress

Si vous utilisez WordPress depuis un certain temps, vous avez probablement déjà utilisé des shortcodes.

Les shortcodes sont de petits extraits pratiques qui vous permettent d'insérer une sorte de fonctionnalité spéciale dans votre contenu qui ne serait pas possible autrement. Par exemple : de nombreux plugins de galerie d'images et de curseurs vous donnent un shortcode que vous pouvez simplement insérer dans votre contenu où vous voulez pour y faire apparaître les images appropriées. Les shortcodes ressemblent généralement à ceci :

[example shortcode]

En d'autres termes : les shortcodes provoquent quelque chose de spécial où qu'ils soient placés dans votre texte.
Mais vous n'êtes pas limité aux shortcodes prédéfinis ; vous pouvez définir des shortcodes personnalisés pour faire ce que vous voulez ! Ils peuvent être simples, complexes ou n'importe quoi entre les deux.

Dans cette série, nous commencerons par un simple shortcode, et progresserons jusqu'à des exemples plus complexes (et encore plus utiles !).

Remarque : nous travaillerons principalement avec PHP ici, en particulier dans le fichier functions.php de votre thème. Si vous n'utilisez pas de thème enfant (ou un thème personnalisé/de démarrage qui peut être modifié sans crainte que les mises à jour écrasent vos modifications), vous souhaiterez créer un thème enfant avant de commencer.

Remarque également : vous n'avez besoin d'aucune connaissance en PHP pour parcourir cet article, mais connaître au moins les bases vous aidera. Le code impliqué ici est assez simple, et nous avons essayé de le rendre aussi simple que possible à copier et à personnaliser. Nous expliquerons chaque morceau de code au fur et à mesure, mais si vous êtes complètement nouveau dans le thème PHP de WordPress, sachez qu'un peu de mauvais code dans votre fichier functions.php peut casser le site.

Un exemple simple et utile de shortcode

Disons que nous voulons un shortcode qui injecte une section spéciale d'informations sur l'auteur dans un article, comme ceci :

Au lieu de créer et de styliser la boîte, l'image et le texte dans l'éditeur visuel WordPress, nous allons simplement créer un shortcode pour produire tout cela avec un simple extrait !

(Remarque : WordPress a de meilleures façons de travailler avec les profils d'auteur, mais nous nous en tenons à cet exemple car il montre bien à quel point il est facile d'utiliser des codes abrégés pour mettre des blocs de contenu spécifiques sur une page.)

Étape 1 : Ajoutez le Shortcode dans le fichier functions.php de votre thème

Vous utiliserez la fonction add_shortcode pour donner un nom à votre shortcode et dire à WordPress ce qu'il doit faire chaque fois que le shortcode est utilisé. Ajoutez cette ligne au fichier functions.php de votre thème :

 [php]add_shortcode( 'author_bio', 'create_author_bio' );[/php]

Peu importe où dans functions.php , mais pour éviter les conflits, nous vous recommandons de le mettre à la toute fin. (Si le fichier se termine par une balise de fermeture ?>, il doit être placé juste avant, pas après.)

Avant d'aller plus loin, décomposons un peu cette ligne, afin que nous comprenions ce qui se passe réellement ici. Les deux morceaux de texte, ou « arguments », à l'intérieur des parenthèses ne sont pas vraiment spéciaux ; ce ne sont que des noms. Passons en revue ce que chacun signifie :

1. Le premier argument : dans ce cas, author_bio – indique à WordPress le nom réel de votre shortcode. Ce sera le texte que les utilisateurs pourront taper, entre parenthèses, pour utiliser le shortcode. Donc, avec ce code tel qu'il est écrit, [author_bio] sera notre shortcode pour déclencher notre boîte de bio auteur.
   Ce texte peut être n'importe quoi, mais il est toujours préférable d'essayer d'être unique. De cette façon, vous ne courez pas le risque que votre nom de shortcode entre en conflit avec quelqu'un d'autre d'un autre plugin ou thème installé.
2. Le deuxième argument : dans ce cas, create_author_bio - pointe WordPress vers la fonction PHP réelle qu'il doit exécuter chaque fois que ce shortcode est utilisé. Nous allons créer cette fonction à l'étape suivante ; pour le moment, nous informons simplement WordPress de son nom. (Ce nom doit également être unique, pour éviter les conflits.)

Donc, si cela peut vous aider, vous pouvez penser au code comme ceci :

 [php]add_shortcode( 'when_you_see_THIS_shortcode', 'do_THIS' );[/php]

Si vous êtes intéressé par des détails plus détaillés, consultez l'entrée add_shortcode du Codex.

Étape 2 : Créer la fonction pour gérer le shortcode

Maintenant, nous devons créer la fonction que nous venons de nommer !

Puisque nous venons de dire à WordPress à la dernière étape que le nom de notre fonction est create_author_bio, notre code devrait maintenant ressembler à ceci, une fois que nous aurons ajouté la nouvelle fonction :

 [php]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ //Code goes here! }[/php]

Vous remarquerez peut-être que cette fonction ne fait encore rien ; tout ce qu'il contient est un commentaire. Nous nous en occuperons à l'étape suivante. Pour l'instant, nous voulons simplement souligner qu'il n'y a vraiment que deux éléments ici : l'enregistrement du shortcode et la fonction qui se produit chaque fois qu'il est utilisé. WordPress PHP peut sembler intimidant, mais c'est vraiment aussi simple que ça !

Remarque : peu importe si la fonction create_author_bio vient après la fonction add_shortcode ou avant elle. L'ordre n'est pas important dans ce cas.

Étape 3 : Faire en sorte que la fonction fasse quelque chose

Il ne reste plus qu'à faire faire à notre fonction ce que nous voulons !

Une fonction comme celle-ci pourrait faire n'importe quoi, mais quoi qu'il arrive, elle devrait éventuellement renvoyer une valeur unique (comme une chaîne de texte ou un nombre). Cette valeur peut être de n'importe quelle longueur ou complexité, mais quel que soit le retour de la fonction, c'est ce qui apparaîtra partout où notre shortcode est utilisé.

Pour nos besoins, ce ne sera qu'un simple code HTML. Voici le balisage pour ajouter notre image d'auteur et notre biographie à l'intérieur d'un élément <aside> avec une classe personnalisée (mais ne le mettez pas encore n'importe où ; nous le regardons juste comme un aperçu pour le moment) :

 [html]<aside class="author-bio-box"></span> <img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"> <p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p> <p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p> </aside>[/html]

Finalement, nous utiliserons cette classe author-bio-box sur la première ligne pour styliser la bio avec CSS. (Nous utiliserons une classe au lieu d'un ID, juste au cas où vous voudriez ajouter plus d'un shortcode d'auteur pour le contenu écrit par plusieurs auteurs.) Mais rappelez-vous, cela pourrait être tout ce que nous voulons mettre dans la page !

Maintenant, tout ce que nous avons à faire est que la fonction de notre shortcode renvoie le code HTML ci-dessus !

Étant donné que le fichier functions.php ne doit contenir que… eh bien, des fonctions PHP (et aussi pour l'ordre), nous avons supprimé les sauts de ligne et les espaces entre les éléments HTML que nous venons de regarder et les avons insérés dans une chaîne (à l'intérieur de guillemets simples) . Mais fonctionnellement, c'est toujours le même extrait HTML que nous venons de voir ci-dessus, et voici à quoi devrait ressembler notre code PHP final :

 [html]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ return '<aside class="author-bio-box"><img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"><p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p><p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p></aside>'; }[/html]

Nous en avons fini avec PHP ! Une fois que nous avons enregistré notre fichier functions.php avec le code final ci-dessus, n'importe quel auteur peut simplement entrer [author_bio] dans n'importe quelle page ou publication, et le code HTML ci-dessus apparaîtra à la place du shortcode !

De plus, ce qui est vraiment cool, c'est que si nous avons besoin de mettre à jour notre biographie, nous n'aurons pas besoin de modifier chaque endroit où elle apparaît ! Au lieu de cela, tout ce que nous avons à faire est de modifier le code dans notre fichier functions.php , et il sera mis à jour partout en même temps. Propre, hein ?

Cependant, pour en tirer le meilleur parti, nous voudrons probablement ajouter un style spécial à la boîte bio.

Étape 4 : Ajouter du CSS

Le shortcode n'est pas génial sans un peu de style, alors ajoutons-le ! Vous devrez peut-être ajuster un peu certaines des valeurs, en fonction des polices de votre propre site (celle de l'image ci-dessus est Fanwood Text) et des règles CSS déjà en place. Ou vous voudrez peut-être simplement essayer quelque chose de différent !

Ce CSS peut être copié dans le fichier style.css de votre thème (enfant), ou si vous utilisez WordPress 4.7 ou supérieur (ce que vous devriez être !), vous pouvez simplement coller ce CSS dans la case « CSS supplémentaire » dans la fenêtre Personnaliser filtrer:

 [css].author-bio-box { background: #d4ead9; padding: 2em; overflow: auto; font-family: Fanwood Text; font-size: 1.2em; line-height: 1.4em; } .author-bio-box img { float: left; max-width: 128px; height: auto; margin: 0 1em 0 0; } .author-bio-box > p:first-of-type:first-letter { font-size: 3.1em; line-height: 1; float: left; margin-bottom: -.2em; } .author-bio-box > p:last-of-type { margin: 0; }[/css]

Maintenant, les choses devraient aller beaucoup mieux. Mais n'hésitez pas à jouer avec le CSS pour vous approprier la boîte d'auteur et la faire se sentir chez elle sur votre site !

Recommandé : rendre la fonction "enfichable"

Ce n'est pas spécifique aux shortcodes, et ce n'est pas strictement nécessaire pour que le code fonctionne, mais c'est la meilleure pratique, et c'est le bon moment pour le mentionner.

Tout d'abord, un petit retour sur le fonctionnement de PHP :

Vous vous souvenez comment nous avons nommé nous-mêmes notre fonction create_author_bio ? Eh bien, il n'y a rien de spécial dans le nom create_author_bio; nous aurions pu tout aussi facilement nommer notre fonction comme nous le voulions (bien qu'il soit préférable que le nom de la fonction vous donne au moins un petit indice sur ce qu'elle fait, c'est pourquoi nous avons choisi create_author_bio ).

Mais voici le problème : si deux fonctions PHP portent le même nom, le résultat sera une erreur fatale qui empêchera le chargement du site, puisque PHP n'aura aucune idée de quelle fonction est la bonne. PHP ne devine pas, donc il s'arrête.

Et ce n'est pas seulement notre code dont nous devons nous préoccuper ; un site WordPress peut utiliser du code provenant de dizaines, voire de centaines de développeurs différents, selon les plugins et les thèmes installés. Si le même nom de fonction est utilisé deux fois, tout s'effondre !

C'est mauvais, et évidemment, nous voulons nous assurer que cela n'arrive jamais.

Nous pouvons le faire en rendant notre fonction "pluggable" ; autrement dit, dire à WordPress de ne pas créer notre fonction si une autre du même nom existe déjà. C'est élégamment simple; nous encapsulons simplement notre code existant dans cette instruction conditionnelle simple :

 [php]if( !function_exists( 'create_author_bio' ) ){ //Our existing PHP goes here! }[/php]

Cette expression conditionnelle if vérifie simplement qu'une fonction nommée create_author_bio n'existe pas déjà. Tout notre code PHP que nous avons utilisé jusqu'à présent peut simplement être déplacé à l'intérieur de cette instruction, entre les accolades { } .

Cependant, il est toujours préférable de nommer les fonctions de la manière la plus unique possible ! Rendre notre fonction enfichable ne fait qu'éviter une erreur fatale. Donc, s'il y avait un conflit de nommage, notre shortcode ne fonctionnerait toujours pas, mais au moins le site serait toujours opérationnel et rien d'autre ne serait cassé.

Conclusion

C'est ça! J'espère que vous avez apprécié la création d'un shortcode de biographie d'auteur personnalisé ! Si vous avez suivi, tout ce que vous avez à faire est de taper [author_bio] n'importe où dans une page ou un message et votre code apparaîtra !

Ce shortcode peut facilement être adapté pour afficher n'importe quoi sur une page. Un gif, un bloc personnalisé de HTML et/ou JavaScript, une image ou une vidéo… tout ce que vous voulez !

Cependant, bien que cet exemple soit utile si vous avez juste besoin de sortir une seule valeur statique sur la page quelque part, il n'est pas très flexible. Il renverra toujours exactement la même chose à chaque fois, et nous avons souvent besoin de codes abrégés pour être plus adaptables que cela.

Bonne nouvelle : nous n'avons couvert que les bases des shortcodes, et ils sont capables de beaucoup, beaucoup plus !