Formation PUB020 : WordPress, 2023 Les shortcodes WordPress

28.2 Création d'un shortcode personnalisé


La création d'un shortcode nécessite trois étapes. J'ai ajouté des couleurs qui sont reprises dans les exemples plus bas. Ceci permet de voir quelles lignes de code correspondent à chacune des étapes.

  • La déclaration de la fonction qui devra être exécutée par le shortcode. On appellera cette fonction fonction de rappel ou, en anglais, callback function;
  • L'appel à la méthode add_shortcode() qui indiquera à WordPress qu'il doit faire le lien entre une chaîne de caractères donnée et la fonction de rappel;
  • L'ajout du shortcode à un endroit donné du site Web : dans une page, dans un article, dans le pied de page, etc.
Fichier functions.php d'un thème enfant WordPress (ou son sous-fichier shortcodes.php)

/**
 * Définit un shortcode qui affiche un texte bidon pour fins de démonstration.
 * @author Christiane Lagacé <christiane.lagace@hotmail.com>
 *
 * Utilisation : [monprefixemonshortcode]
 * Suppositions critiques : le style .textespecial doit définir l'apparence du texte
 *
 * @return String Code html généré par le shortcode
 *
 */
function monprefixe_monshortcode( ) {
    $code_html = "<span class='textespecial'>Voici le texte qui sera affiché à la place du shortcode</span>";
    return $code_html;
}
 
add_shortcode( 'monprefixemonshortcode', 'monprefixe_monshortcode' );

Pour utiliser ce shortcode, il faut inscrire à l'endroit désiré son nom entre crochets carrés, par exemple dans le texte d'une page.

Texte entré dans une page WordPress 

Lorem ipsum [monprefixemonshortcode] dolor sit amet.

Supposons que la règle CSS suivante a été définie :

CSS

.textespecial {
    background-color: #f5e6ab;
}

Résultat à l'écran :

Résultat du shortcode

▼Publicité Le texte se poursuit plus bas

Où coder les shortcodes?

Si le shortcode doit être utilisé dans plusieurs sites WordPress, la déclaration de la fonction de rappel ainsi que l'appel à add_shortcode() seront codées dans une extension.

Dans le cas où le shortcode est écrit spécifiquement pour un site, ils seront plutôt codés dans le fichier functions.php du thème enfant.

Puisque ce fichier peut devenir très gros, plusieurs programmeurs préfèrent créer des sous-fichiers et placer ce code dans un sous-fichier nommé shortcodes.php.

Attention : si vous développez un thème que vous souhaitez distribuer, les bonnes pratiques veulent que vous n'utilisiez pas les shortcodes dans le functions.php du thème.

Malheureusement, cette règle est souvent escamotée par les concepteurs de thèmes. Elle a pourtant une raison d'être simple : puisqu'un site WordPress peut changer de thème facilement et que les shortcodes sont, la plupart du temps, écrits directement dans la BD (ex : dans le texte d'une page ou d'un article), le fait de changer de thème empêcherait le bon fonctionnement des pages ou articles qui utilisent les shortcodes de l'ancien thème. Si, par contre, le shortcode est écrit dans une extension, le changement de thème n'affectera pas son bon fonctionnement.

Nomenclature

Le nom du shortcode ainsi que le nom de sa fonction de rappel seront tous deux écrits en lettres minuscules. Ils seront également préfixés pour éviter tout conflit de nom avec les shortcodes et fonctions du thème ou des extensions utilisées.

Par contre :

  • le nom de la fonction de rappel utilisera des barres de soulignement pour séparer les mots (c'est la norme de programmation WordPress);
  • le nom du shortcode s'écrira en un seul mot. Il ne doit pas utiliser de traits d'unions pour séparer les mots. En effet, tel que documenté dans le Shortcode API de WordPress, dans certains contextes, WordPress pourrait confondre les shortcodes [tag] et [tag-a]. La documentation permet l'utilisation de barres de soulignement (ex : [tag_a]) mais on préférera généralement utiliser un seul mot (ex : [taga]).

Fonction de rappel

C'est dans la fonction de rappel du shortcode qu'on retrouvera la logique pour générer le texte et les balises que le shortcode doit afficher.

La fonction de rappel ne doit rien afficher (pas de commande echo ni aucun texte ou balise qui ne soit pas entre <?php et ?>).

Plutôt, elle doit bâtir la chaîne de caractères HTML qui sera affichée lorsque le noyau WordPress rencontrera le shortcode. C'est cette chaîne qui sera retournée par la fonction de rappel.

Si jamais une fonction de rappel d'un shortcode faisait un echo, on pourrait avoir des problèmes d'affichage lorsque le shortcode n'est pas seul sur une page ou dans un article.

Par exemple, si une page contient ceci alors que le shortcode fait un echo :

Texte entré dans une page WordPress 

Avant le shortcode

[monprefixemonshortcode]

Après le shortcode

la chaîne envoyée en echo (dans cet exemple : "Résultat du shortcode") apparaîtra avant tout le reste, même s'il y avait du texte avant l'appel du shortcode :

Résultat à l'écran

Résultat du shortcode

Avant le shortcode

Après le shortcode

Fonction de rappel définie dans une classe

Lorsqu'un shortcode est codé dans une extension, sa fonction de rappel sera une méthode codée dans une classe. À ce moment, le second paramètre de add_shortcode() devra être un tableau. Le premier élément du tableau sera $this, soit l'objet sur lequel on travaille, et le second, le nom de la méthode.

WordPress (PHP)

class Monprefixe_Mon_Extension {

    public function __construct() {
        add_shortcode( 'monprefixefairequelquechose', array( $this, 'faire_quelque_chose' );
        ...
    }
   
    public function faire_quelque_chose() {
        ...
    }

}

Remarquez que dans cet exemple, le nom du shortcode débute par un préfixe pour le distinguer des autres shortcodes. La méthode de rappel, quant à elle, n'a pas besoin de débuter par un préfixe puisqu'elle est définie dans une classe, ce qui enlève le risque de conflit de nom avec d'autres fonctions.

Pour plus d'information

« Shortcodes Should Never Be Included With Themes. Period. ». ThemeLab. http://www.themelab.com/put-shortcodes-in-a-plugin/

Veuillez noter que le contenu de cette fiche vous est partagé à titre gracieux, au meilleur de mes connaissances et sans aucune garantie.
Par Christiane Lagacé
Dernière révision le 18 novembre 2022
Merci de partager !

Site fièrement hébergé chez A2 Hosting.

Soumettre