Comment créer un Shortcode dans Wordpress ?

Un Shortcode (« code court » en Français) est un petit élément de texte à placer dans le wysywig editor de WordPress qui permettent de générer des composants dans le frontend.

Ils sont l’ancêtre des Blocks Gutenbergs mais restent parfois pratiques, en particulier si vous voulez créer des composants réutilisables très facilement et sans compliquer votre application.

D’ailleurs, leur syntaxe se rapproche beaucoup du JSX que l’on connait aujourd’hui dans la plupart les framework frontend.

Cependant…

L’expérience utilisateur des webmasters en est grandement appauvrie : ils sont compliqués à utiliser et il n’y a rien de visuel pour assister un non-développeur dans leur utilisation.

Qu’est-ce qu’un Shortcode ?

Un shortcode WordPress est une écriture balisée, délimitée par des crochets, conçue pour être insérée dans le contenu éditorial d’un site WordPress.

En général, ils s’insèrent dans l’éditeur de texte « classique » (le wysiwyg editor), mais il est également possible de les utiliser dans Gutenberg ou dans un champ wysiwyg d’ACF.

Cette annotation sert de point d’ancrage pour exécuter une fonction PHP prédéfinie, qui est traitée par WordPress lors du rendu de la page.

Quand WordPress rend une page, il cherche les shortcodes à l’intérieur et les remplace par l’HTML retourné par les fonctions qui lui sont associées.

Par exemple, si vous insériez [helloworld] dans votre éditeur et qu’un shortcode lui était associé, vous auriez sur votre page finale, en frontend, le markup suivant :

<p>Hello World!</p>

Bien sûr, ce n’est qu’un exemple simpliste. Les Shortcode sont beaucoup plus puissants, et ce, parce qu’ils peuvent prendre des arguments.

Par exemple [helloworld lang=fr] conduirait à :

<p>Bonjour le monde !</p>

Les shortcodes sont fréquemment exploités par divers plugins pour intégrer de manière transparente des fonctionnalités supplémentaires au sein du système de gestion de contenu, permettant ainsi une personnalisation et une extension efficaces du comportement standard de WordPress.

Une fonctionnalité du passé ?

Les shortcodes étaient très répandus dans WordPress avant 2019.

C’est en effet cette année-là qu’est sorti l’éditeur de bloc Gutenberg. Cet éditeur offre une expérience utilisateur nettement plus conviviale pour les webmasters, leur évitant de compter sur des compétences en balisage qui étaient essentielles à l’utilisation des shortcodes.

Cela dit, les shortcodes sont toujours massivement utilisés dans les plugins, y compris dans ceux qui implémentent des blocs Gutenberg.

En général, vous aurez les deux versions : le bloc et le shortcode.

D’ailleurs, si vous utilisez un builder de page comme Elementor ou Divi, ils utilisent des shortcodes. Bien sûr, ils importent toute une application pour vous permettre de les éditer visuellement, mais en base de données, il n’y a que des shortcodes qui sont ensuite rendus par WordPress.

Le fait est que, les blocs Gutenberg, c’est une super usine à gaz, ultra complexe et longue à mettre en place. Alors, parfois, utiliser les shortcodes pour une extension, c’est plus rapide et plus pratique.

Les shortcodes sont donc encore massivement utilisés de nos jours et il est important de les maîtriser pour devenir un développeur WordPress accomplie.

Les caractéristiques d’un Shortcode

Un Shortcode dispose de plusieurs caractéristiques :

• Il a un nom : Il permet de détecter le shortcode dans le contenu, par exemple `helloworld` est le nom du shortcode [helloworld]
• Il a des arguments (ou attributs, ou props, etc.) Ce sont des clés-valeurs ajoutées après le nom entre les crochets : [image id="15" size="medium" ] dispose de deux arguments : ID et Size. C’est l’équivalent des props dans un composant JSX.
• Il a des crochets ouvrants et fermants (les fermants n’étant pas toujours obligatoires) : [helloworld]Je suis le contenu[/helloworld].
• Il dispose d’un contenu : C’est ce qui se trouve entre le crochet ouvrant et le crochet fermant.

Tous ces éléments permettent de contrôler et de rendre le shortcode dynamique au moment de l’execution de la fonction de rendu.

Enfin, dernière caractéristique des shortcodes…

Ils doivent être explicitement déclarés en PHP. Vous aurez donc besoin de créer un child theme ou un plugin pour mettre en place les vôtres.

Écrire un Shortcode

Dans un premier temps, il va vous falloir mettre en place un thème enfant ou un plugin afin de pouvoir écrire du PHP et y mettre votre code pour votre shortcode.

Si vous ne savez pas faire, vous pouvez suivre notre guide sur le sujet. Dans cet article, je vais partir du principe que vous utilisez un theme, mais pour un plugin c’est presque pareil.

Une fois fait, rendez-vous dans le fichier functions.php, à la racine de votre projet. (/wp-content/plugins/votre-plugin ou /wp-content/themes/votre_theme)

Si comme nous, vous n’aimez pas utiliser le fichier functions.php comme un immense fourre-tout désorganisé, je vous invite à créer un dossier « shortcode » dans lequel vous placerez tous vos fichiers PHP incluant des shortcodes.

C’est en général une bonne idée d’utiliser un fichier PHP par shortcode, avec un nom significatif pour vous y retrouver par la suite.

Voici à quoi ressemblerait votre architecture de fichier :

/votre-theme
    /assets
        /css
            - style.css
        /js
            - script.js
        /images
            - image1.png
            - image2.jpg
    /shortcodes
       - votre_shortcode.php
    /templates
        - template-part.php
    - functions.php
    - index.php
    - style.css
    - screenshot.png

dans functions.php, il vous faudra utiliser require_once(__DIR__ . "/shortcodes/votre_shortcode.php); afin de charger votre fichier, et dans ce fichier vous pourrez créer un shortcode d’exemple de la manière suivante :

<?php

function custom_shortcode() {
    return <<<HTML
      <p>hello world!</p>
    HTML;
}
add_shortcode('my_custom_shortcode', 'custom_shortcode');

Ce que vous voyez à l’écran, c’est un shortcode vraiment basique qui respecte les conventions énoncées par WordPress.

Chez Olympe Studio, on trouve ces conventions très mauvaises, et on utiliserait plutôt ce code-ci :

<?php

add_shortcode('my_custom_shortcode', function () {
    return <<<HTML
      <p>hello world!</p>
    HTML;
};

Ici, votre fonction est anonyme, et ça vous évite de devoir créer des fonctions avec des noms impossibles à retenir dans le seul et unique but d’éviter de redéclarer des fonctions qui sont déjà déclarées.

Ça va vous imposer d’utiliser une version de PHP > 7.3, mais étant donné que cette version n’est plus supportée, vous n’avez aucune raison de vous priver des fonctionnalités qu’elle apporte.

Afficher un shortcode dans une page web

Ce shortcode pourrait ensuite être affiché de deux manières différentes :

• Dans le contenu, en utilisant [my_custom_shortcode].
• Dans un fichier PHP, en utilisant la fonction do_shortcode.

Comme nous avons déjà largement traité l’usage de l’annotation avec les crochets, intéressons-nous un peu à l’usage de la fonction do_shortcode.

En fait, elle interprète une chaîne de caractère qui inclue une annotation à crochet, par exemple :

<?php

// Ne fonctionne pas.
do_shortcode('my_custom_shortcode');

// Fonctionne.
do_shortcode('[my_custom_shortcode]');

Vous l’aurez compris, cette fonction n’est pas super développeur « friendly ». Et WordPress ne propose pas d’alternative plus sympa, mais voici une fonction maison pour vous aider à effectuer ce genre de rendu de shortcode en PHP :

<?php

function renderShortcode($shortcodeName, $args = [], $content = '') {
  $shortcode = '[' . $shortcodeName;
  foreach ($args as $key => $value) {
    $shortcode .= ' ' . $key . '="' . esc_attr($value) . '"';
  }
  $shortcode .= ']';
  if ($content !== '') {
    $shortcode .= $content . '[/' . $shortcodeName . ']';
  }
  echo do_shortcode($shortcode);
}

// Rendu de la manière suivante : 
echo renderShortcode(
  'my_custom_shortcode',
  ['attr1' => 'value1'],
  'Contenu entre les crochets'
);

Vous pouvez maintenant utiliser cette fonction où vous souhaitez rendre votre shortcode avec les variables que vous souhaitez.

Ajouter des arguments à un shortcode

Jusqu’à maintenant, notre shortcode ne fait pas grand-chose.

Rendons le un peu plus dynamique en lui apportant deux arguments :

• Les arguments du shortcodes,
• Le contenu du shortcode.

<?php

add_shortcode('my_custom_shortcode', function ($args, $content) {
    return <<<HTML
      <p>$content</p>
    HTML;
};

Concentrons-nous en premier lieu sur le contenu : $content, le second argument.

Maintenant, lorsque vous utiliserez [my_custom_shortcode]Bonjour le Monde ![/my_custom_shortcode], votre shortcode affichera :

<p>Bonjour le Monde !</p>

Ajoutons ensuite un argument « class », qui va nous permettre d’ajouter une class CSS à notre élément HTML :

<?php

add_shortcode('my_custom_shortcode', function ($args, $content) {
    $cssClass = $args['class'];    
    return <<<HTML
      <p class="{$cssClass}">$content</p>
    HTML;
};

Maintenant, lorsque l’on va utiliser : [my_custom_shortcode class="hey"]Bonjour le Monde ![/my_custom_shortcode] nous allons rendre :

<p class="hey">Bonjour le Monde !</p>

Bien entendu, vous pouvez utiliser n’importe quel argument avec des types de base :

• Chaines de caractères,
• Caractères numériques,
• Booléens,

Cependant, il est important de prendre en compte que TOUS les arguments passés seront des chaines de caractères dans $args. Si vous souhaitez passer des types différents, il vous faudra manuellement modifier les types avec boolval($args['argument bool']) ou intval($args['argument int']).

Et on en vient au second problème : définir les arguments par défaut.

C’est assez simple parce que WordPress l’a anticipé : vous pouvez utiliser la fonction shortcode_atts() pour définir des valeurs par défaut à $args afin d’éviter les erreurs lorsque l’utilisateur oublie de les mentionner.

Voici à quoi ça pourrait ressembler dans notre exemple :

<?php

add_shortcode('my_custom_shortcode', function($atts) {
    $atts = shortcode_atts([
        'intarg' => '0', // Valeur par défaut
    ], $atts, 'my_custom_shortcode');

    $intArg = intval($atts['intarg']);

    return <<<HTML
      <p class="{$cssClass}">$intArg</p>
    HTML;
});

Ajouter vos styles et vos scripts

Si vous développez des Shortcodes, il y a fort à penser que vous ajoutiez du CSS ou du javascript à votre HTML afin d’embellir l’affichage.

En tant que développeur organisé, vous avez sans doute envie d’organiser votre shortcode dans un dossier qui va inclure :

• Le fichier PHP avec le shortcode en lui-même,
• Un fichier CSS, qui contient uniquement le CSS lié à ce composant,
• Un fichier JS qui contient uniquement le JS lié à ce composant.

Ainsi, si vous avez besoin de modifier un élément de votre shortcode pour répondre à la demande d’un client, vous saurez que 100% du code lié à cet élément ce trouve dans se dossier.

Voici une structure que vous pourriez utiliser :

/votre-theme
    /shortcodes
       /shortcode1
          - shortcode1.php
          - shortcode1.css
          - shortcode1.js
       /shortcode2
          - shortcode2.php
          - shortcode2.css
          - shortcode2.js
    - functions.php
    - index.php
    - style.css
    - screenshot.png

Ensuite, il vous faudra ajouter dans votre fichier PHP à chaque fois le code suivant :

<?php

add_shortcode('my_custom_shortcode', function ($atts) {
    wp_enqueue_style('my-shortcode-css');
    wp_enqueue_script('my-shortcode-js');

    // reste du shortcode
});

Procéder ainsi vous assure que :

• Votre shortcode n’importe son CSS et sont JS que lorsqu’il est utilisé.
• Les fonctions wp_enqueue_style/script s’assurent que ces fichiers ne son pas importés plusieurs fois sur votre page lorsque vous rendez plusieurs fois un même shortcode.
• Vous conservez un code clair et bien organisé.

En utilisant une bonne politique de cache pour les fichiers .css et .js, vous pourriez également importer vos fichiers sur toutes les pages.

C’est à vous de vous organiser comme vous le préférez.

Aller plus loin

Les shortcodes sont définie en PHP, ce qui signifie que vous n’avez pas à vous limiter à leur contexte dans la fonction qu’ils exécutent.

Dans un shortcode, il n’y a pas de restriction ni de limite, vous pouvez utiliser WP_Query, les global PHP, ou même encore charger un template avec get_template_part().

La seule contrainte, c’est qu’un shortcode doit RETOURNER ce qu’il veut afficher, et non pas l’afficher directement.

Donc, vous ne pouvez pas utiliser echo dans la callback.

Si vous voulez afficher une liste de post en bas d’un article de blog par exemple, vous pourriez utiliser ce shortcode :

add_shortcode('relatedPosts', function ($args) {
  $myQuery = new WP_Query([
    'post_type'      => 'post',
    'posts_per_page' => 3,
  ]);
  $html = '';

  if ($myQuery->have_posts()) {
    while ($myQuery->have_posts()) {
      $myQuery->the_post();
      $html .= '<h2>' . get_the_title() . '</h2>';
      $html .= '<div>' . get_the_content() . '</div>';
      $html .= get_the_post_thumbnail();
    }
  }

  wp_reset_postdata();
  return $html;
});

Attention dans cet exemple, vous ne pouvez pas utiliser les fonctions d’affichage direct the_title() ou the_content(), justement parce que vous ne pouvez pas utiliser echo à l’intérieur d’un shortcode.

Si vous voulez tout de même le faire, vous devrez utiliser les fonctionnalités d’output buffering de PHP, comme ceci :

add_shortcode('relatedPosts', function ($args) {
  $myQuery = new WP_Query([
    'post_type'      => 'post',
    'posts_per_page' => 3,
  ]);
  $html = '';

  if ($myQuery->have_posts()) {
    while ($myQuery->have_posts()) {
      $myQuery->the_post();
      ob_start();

      the_title();
      the_content();

      the_post_thumbnail();
      $html .= ob_get_clean();
    }
  }

  wp_reset_postdata();
  return $html;
});

Bien entendu, il en sera de même pour get_template_part, qui affiche directement l’HTML plutôt que de le retourner sous la forme d’une chaine de caractère.

Conclusion

Les shortcodes de WordPress représentent une fonctionnalité puissante et flexible, permettant aux développeurs de personnaliser le contenu des sites WordPress avec facilité.

Malgré l’émergence de l’éditeur Gutenberg, les shortcodes restent pertinents, offrant une alternative rapide et moins complexe pour l’intégration de fonctionnalités spécifiques.

Ils sont cependant beaucoup plus complexe à utiliser pour un non développeur, il faut donc rester prudent si vous voulez les utiliser avec vos clients.

Bien que les shortcodes puissent sembler être un héritage du passé, ils constituent toujours un outil essentiel dans la boîte à outils du développeur WordPress moderne.

Questions fréquentes

Les shortcodes WordPress peuvent-ils accepter des valeurs par défaut pour les attributs ?

Oui, les shortcodes WordPress peuvent avoir des valeurs par défaut. Lors de la définition de votre callback, vous pouvez utiliser shortcode_atts() pour spécifier les valeurs par défaut.

Voici un exemple :

add_shortcode('mon_shortcode', function ($args) {
    $args = shortcode_atts(array(
        'couleur' => 'bleu',
        'taille' => 'moyenne'
    ), $args, 'mon_shortcode');
    
    dd($args); // ['couleur' => 'bleu', 'taille' => 'moyenne']
});

Peux-t-on imbriquer des shortcodes dans WordPress ?

Oui, mais c’est un peu complexe pour un usage utilisateur.

Cela dit, il n’y a aucune limite avec la callback en elle-même, vous pouvez ainsi très bien utiliser la fonction do_shortcode ou la fonction renderShortcode qu’on vous a montrée plus haut pour imbriquer des shortcodes :

add_shortcode('mes_shortcodes_imbriqués', function ($args) {
    $content = "mon sous contenu";
    return '<div class="conteneur-personnalisé">' . renderShortcode("sous_shortcode", $args, $content) . '</div>';
});

Comment peut-on sécuriser un shortcode WordPress contre les injections SQL ou XSS ?

Effectivement, lorsqu’un utilisateur a la possibilité d’écrire des choses qui sont passés ensuite comme variables à des fonctions, il est important d’effectuer un nettoyage.

Pour cela vous pouvez utiliser les fonctions esc_attr(), esc_html() ou sanitize_text_field() avant de les utiliser dans des requêtes SQL ou avant de les injecter dans votre HTML.