Créer un shortcode personnalisé dans WordPress avec add_shortcode

Des milliers de plugins WordPress existent afin d’ajouter des shortcodes utiles à votre site… Ces petits bouts de code à placer dans vos contenu s’avèrent bel et bien pratiques, mais que faire si vous voulez insérer un shortcode affichant un contenu ou une fonctionnalité très spécifique à votre site ? Plongez dans ce tutoriel pour apprendre à créer des shortcodes personnalisés.

• Fonction add_shortcode WordPress : add_shortcode
  
• Code créé dans ce tutoriel : http://pastebin.com/S8GhbMHP
  

La fonction add_shortcode vous permet d’ajouter vos propres shortcodes à WordPress. Elle accepte deux paramètres : le premier représente le nom du shortcode en question (ce qui sera entre les crochets) et le deuxième paramètre indique à WordPress la fonction PHP qui se chargera d’afficher le contenu du shortcode.

add_shortcode('notre_shortcode', 'notre_fonction');

… créera un shortcode [notre_shortcode] qui utilisera la fonction notre_fonction().

Comment définir des paramètres dans mon shortcode ?

Ces petits bouts de code que sont les shortcodes sont très puissants : avec une syntaxe très simple, il est possible d’afficher un contenu dynamique. Encore mieux : des paramètres peuvent être écrits dans les shortcodes, pour modifier le comportement du shortcode et afficher des données différentes selon les paramètres définis par l’utilisateur.

Le code ci-dessous récupère les paramètres du shortcode, si ils ont été définis par l’utilisateur lors de l’écriture du shortcode, et définit les valeurs par défaut à utiliser si un paramètre n’a pas été défini.

function votre_fonction($param) {
  extract(
    shortcode_atts(
      array(
        'title' => 'Article n°<strong>%nb%</strong> de la série <em>%serie%</em>'
      ),
      $param
    )
   );
...

Analysons : on utilise shortcode_atts, une fonction WordPress qui mélange des valeurs par défaut (la première array passée en paramètre) et les valeurs à disposition dans notre shortcode écrit par l’utilisateur (l’array $param passée en deuxième paramètre). Couplée à la fonction PHP extract, nous avons donc accès à des variables ayant pour nom les paramètres de votre shortcode.

Un exemple vaut mieux qu’un long discours : si on utilise la fonction suivante pour l’affichage d’un shortcode [notre_shortcode]…

function notre_fonction($param) {
  extract(
    shortcode_atts(
      array(
        'prenom' => 'Jean',
        'nom' => 'Dupontel',
        'age' => 32
      ),
      $param
    )
  );
  return $prenom . ' ' . $nom . ' a ' . $age . ' ans.';
);

… nous aurons donc, dans notre fonction, accès aux variables $prenom, $nom et $age.

Si l’utilisateur utilise le shortcode [notre_shortcode prenom=’Edouard’ nom=’Baer’], la variable $prenom aura pour valeur Edouard, $nom aura pour valeur Baer mais $age aura pour valeur 32, valeur définie à partir des valeurs par défaut. Le shortcode affichera donc Edouard Baer a 32 ans.

Créer un shortcode ouvert

La vidéo et les exemples de code ci-dessus illustrent la création de shortcodes fermés (self-closing). Mais nous avons également la possibilité de créer des shortcodes qui « entourent » un contenu (enclosing), bien souvent pour modifier l’apparence de ce contenu avec une syntaxe ressemblant à ça :

[mon_shortcode]Mon contenu à embellir dans mon shortcode[/mon_shortcode]

Par exemple, créons un shortcode [grand_titre]Mon super grand titre[/grand_titre] qui offrira aux utilisateurs ne connaissant pas le HTML d’entourer un texte de tags <h1> et </h1> pour créer un titre de premier niveau.

function fonction_shortcode_grand_titre($param, $content) {
 return '<h1>' . $content . '</h1>';
}
add_shortcode('grand_titre', 'fonction_shortcode_grand_titre');

Quoi de nouveau ? Nous avons simplement ajouté un paramètre dans la fonction PHP qui détermine la logique de notre shortcode. Le deuxième paramètre $content peut être utilisé dans notre fonction pour afficher le contenu présent entre les 2 tags de notre shortcode (dans notre cas, le contenu entre [grand_titre] et [/grand_titre]).

Il suffit de modifier $content dans notre code ci-dessus par do_shortcode($content). La fonction WordPress do_shortcode interprète les shortcodes contenus dans un texte.

Dans un shortcode, pensez à return et non echo

Si vous avez suivi notre tutoriel vidéo ci-dessus, nous utilisons d’abord echo pour afficher des données à travers notre shortcode. C’est une mauvaise pratique (délibérément mise en place puis corrigée dans la vidéo :-)) : pour éviter des problèmes d’affichages de votre shortcode, pensez à toujours retourner (return) le contenu du shortcode en fin de fonction.
Si vous avez déjà écrit votre fonction en utilisant echo, suivez la solution présentée dans la vidéo et optez pour la bufferisation de sortie avec ob_start, ob_get_contents et ob_end_clean. Ainsi, le contenu généré par le shortcode s’affichera au bon endroit.

Maintenant que vous savez créer vos propres shortcodes, n’hésitez pas à nous faire partager vos shortcodes pratiques !