🛠 Comment ajouter votre propre shortcode dans WordPress : décryptage de add_shortcode() [+2 exemples]

Vous avez créé un extrait de code, vous l'avez ajouté à functions.php, et WordPress vous répond «cheatin' uh?». Cela vous dit quelque chose? Les shortcodes, le mécanisme d'extension central de WordPress, et add_shortcode() le débloquent en 15 lignes de code. Mais entre un «Hello World» et un cas d'usage réel, il y a quelques pièges à éviter: return contre echo, l'ordre des paramètres de la fonction de rappel et les conflits de balises.

Les shortcodes sont apparus avec WordPress 2.5 et sont depuis devenus la base de l'écosystème: formulaires de contact, galeries, sliders, affichage de champs personnalisés, tout cela vit entre crochets. add_shortcode() n'a pas changé depuis des années, et vous pouvez le maîtriser en une demi-heure.

Voici une analyse complète de la fonction avec deux exemples prêts à l'emploi: de l'année qui se met à jour automatiquement dans le pied de page à une liste des utilisateurs du site.

💡 Aperçu rapide:

• Syntaxe et paramètres de add_shortcode(), balise et fonction de rappel
• La règle: toujours return, jamais echo
• Le hook init, et pourquoi votre shortcode peut ne pas fonctionner sans lui
• Deux façons de transmettre des données: le contenu entre les balises et les attributs
• Code prêt à l'emploi: un shortcode pour l'année automatique et une liste d'utilisateurs

Comment fonctionne add_shortcode() dans WordPress

La fonction add_shortcode() est le point d'entrée pour enregistrer tout shortcode personnalisé. Elle prend deux paramètres obligatoires: une balise unique et le nom de la fonction de rappel qui renverra le contenu.

Selon la documentation WordPress, la fonction de rappel reçoit trois arguments dans un ordre fixe:

• $attributes, un tableau des attributs passés dans le shortcode
• $content, le texte entre la balise ouvrante et la balise fermante
• $tag, le nom de la balise avec laquelle le shortcode est enregistré

Un exemple basique, un shortcode qui affiche «Hello World!»:

1
// Shortcode callback function
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello World!';
4
}
5
// Shortcode registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Le code se place dans le fichier functions.php de votre thème enfant ou via une extension comme Code Snippets. Ensuite, [hello-world] dans l'éditeur d'article affichera «Hello World!».

Pourquoi return, et non echo

Remarquez le return à l'intérieur de la fonction de rappel. Si vous utilisez echo, l'affichage se produit avant que WordPress ne construise le reste de la page, «Hello World!» se retrouve tout en haut, et le contenu environnant est déplacé.

La règle est simple: **une fonction de rappel de shortcode renvoie toujours une valeur via ****return**. Pas de echo, de print ou d'affichage HTML direct en dehors d'un tampon.

Le hook init est indispensable

Les développeurs de WordPress.org recommandent d'accrocher l'enregistrement du shortcode à init, et non d'appeler add_shortcode() directement dans le corps de functions.php. Sans init, WordPress peut ne pas avoir terminé l'initialisation de ses mécanismes internes, et le shortcode ne se déclenchera tout simplement pas.

Syntaxe et paramètres

Signature de la fonction:

1
add_shortcode( string $tag, callable $callback )

$tag, le nom du shortcode (sans les crochets). Si deux extensions enregistrent un shortcode avec la même balise, le dernier écrase le précédent. Pour éviter les conflits, ajoutez un préfixe unique: pas [gallery], mais [myplugin_gallery].

$callback, le nom de la fonction qui renvoie le contenu. Vous pouvez passer une chaîne avec le nom de la fonction, une fonction anonyme ou une méthode de classe (en passant un tableau [ $object, 'method_name' ]).

Comment utiliser les shortcodes dans l'éditeur

Dans l'éditeur WordPress, Gutenberg ou Classic, un shortcode s'insère entre crochets. Pour notre exemple:

[hello-world]

La forme complète avec une balise fermante fonctionne également:

[hello-world][/hello-world]

La deuxième option est nécessaire lorsque du contenu est passé entre les balises (nous y reviendrons plus bas).

Comment appeler un shortcode en PHP

Dans les templates de thème ou les extensions, les shortcodes sont exécutés via do_shortcode():

1
echo do_shortcode( '[hello-world]' );

La fonction prend une chaîne contenant un shortcode et renvoie le résultat de son exécution. C'est utile lorsque vous devez intégrer la sortie d'un shortcode dans une logique PHP, par exemple dans header.php ou à l'intérieur d'une boucle.

Transmettre des données à un shortcode: deux méthodes

Méthode 1: le contenu entre les balises

Encadrez les données entre la balise ouvrante et la balise fermante:

[hello-world]from John to Mary[/hello-world]

La fonction de rappel reçoit la chaîne from John to Mary via le deuxième paramètre $content:

1
// Callback with content substitution between tags
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello ' . $content . ' World!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Résultat: «Hello from John to Mary World!».

Méthode 2: les attributs

Passez les paramètres directement dans la balise ouvrante:

[hello-world from="John" to="Mary"][/hello-world]

Dans la fonction de rappel, les attributs sont disponibles via le premier paramètre $attributes, un tableau associatif dont les clés correspondent aux noms des attributs:

1
// Callback with reading shortcode attributes
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello from ' . $attributes['from'] . ' to ' . $attributes['to'] . '!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Résultat: «Hello from John to Mary!». Les attributs sont plus adaptés aux données structurées (prix, URL, ID), tandis que le contenu entre les balises convient mieux au texte libre.

En pratique, vous devez immédiatement ajouter shortcode_atts() aux attributs, une fonction native de WordPress qui fusionne les attributs passés avec un tableau de valeurs par défaut. Sans cela, l'accès à $attributes['from'] générera une notice PHP si l'utilisateur n'a pas spécifié l'attribut. Avec shortcode_atts(), vous obtenez toujours un tableau complet: les clés définies ont des valeurs de repli, et les attributs inconnus sont filtrés automatiquement.

Deux shortcodes prêts à l'emploi pour WordPress

1. Année en cours automatique

Le shortcode [current-year] insère l'année en cours tout seul, plus besoin de mettre à jour la date dans le pied de page chaque mois de janvier:

1
// Callback: returns current year via date('Y')
2
function current_year_shortcode_callback( $attributes, $content, $tag ) {
3
    return date( 'Y' );
4
}
5
// Registration of shortcode [current-year]
6
function current_year_shortcode() {
7
    add_shortcode( 'current-year', 'current_year_shortcode_callback' );
8
}
9
add_action( 'init', 'current_year_shortcode' );

Placez [current-year] dans le pied de page ou le texte d'un article, et l'année se mettra à jour automatiquement.

2. Liste des utilisateurs enregistrés

Le shortcode [users-list] affiche les noms de tous les utilisateurs du site sous forme de liste à puces. Utile sur une page «Équipe» ou dans des rapports d'administration:

1
// Callback: gets all users and generates HTML list
2
function my_custom_users_list() {
3
    $users = get_users();
4
    $list_html = '<ul>';
5
    foreach ( $users as $user ) {
6
        $list_html .= '<li>' . $user->data->display_name . '</li>';
7
    }
8
    $list_html .= '</ul>';
9
    return $list_html;
10
}
11
// Registration of shortcode [users-list]
12
function register_my_users_list_shortcode() {
13
    add_shortcode( 'users-list', 'my_custom_users_list' );
14
}
15
add_action( 'init', 'register_my_users_list_shortcode' );

get_users() sans argument renvoie tous les utilisateurs. Pour limiter la requête par rôle, passez un tableau: get_users( [ 'role' => 'editor' ] ). Le code se place dans le fichier functions.php du thème actif ou dans une extension personnalisée.

Vidéo: créer des shortcodes dans WordPress

Une courte vidéo sur le sujet, de l'enregistrement d'un shortcode à partir de zéro, de l'écriture de la fonction au test dans l'éditeur:

⁉️🤔 Questions fréquentes

Que se passe-t-il si deux extensions enregistrent un shortcode avec la même balise?

WordPress exécute celui qui a été chargé en dernier. Le premier shortcode est écrasé silencieusement, sans erreur. C'est pourquoi vous devez toujours utiliser un préfixe dans vos shortcodes: [acme_gallery] au lieu de [gallery]. Cela élimine les conflits avec toute autre extension ou thème.

Peut-on appeler des shortcodes à l'intérieur d'autres shortcodes?

Oui. Si la fonction de rappel du premier shortcode renvoie une chaîne contenant la balise du second shortcode, WordPress traite automatiquement le shortcode imbriqué. Mais n'oubliez pas do_shortcode(): si vous construisez du contenu manuellement et qu'il contient des shortcodes, passez la chaîne explicitement dans do_shortcode(). Le comportement standard de the_content le fait tout seul, mais un appel direct à une fonction de rappel ne le fait pas.

Où le code du shortcode doit-il résider, dans le thème ou une extension?

Les shortcodes personnalisés relèvent de la fonctionnalité, pas de l'apparence, il est donc préférable de les extraire dans une extension dédiée. Changer de thème ne cassera pas le site: les shortcodes continueront de fonctionner. Au minimum, utilisez un thème enfant si vous êtes certain de ne pas changer le thème parent.

Y a-t-il des restrictions sur le nom de la balise?

Le nom doit être composé de lettres latines, de chiffres et de tirets. Les espaces, les tirets bas et les caractères spéciaux ne sont pas autorisés. La longueur recommandée est de 20 caractères maximum, en minuscules. Exemple: [my-plugin-shortcode].

Comment déboguer un shortcode s'il n'affiche rien?

Première étape, activez WP_DEBUG dans wp-config.php. Deuxièmement, vérifiez que la fonction de rappel renvoie une valeur via return, et non echo. Troisièmement, assurez-vous que le hook init est présent. S'il n'y a pas d'erreur mais que la sortie est vide, ajoutez error_log() à l'intérieur de la fonction de rappel et consultez les logs du serveur.

Ce qu'il faut retenir sur les shortcodes WordPress

Les shortcodes sont un mécanisme mature et stable. add_shortcode() n'a pas changé depuis des années: balise, fonction de rappel, hook init, return au lieu de echo. Retenez ces quatre éléments, et tout shortcode personnalisé fonctionnera du premier coup.

• Si vous affichez l'année dans le pied de page, utilisez le code prêt à l'emploi [current-year].
• Si vous avez besoin d'une liste d'utilisateurs, [users-list] avec un filtre par rôle.
• Si vous écrivez votre propre shortcode à partir de zéro, utilisez toujours un préfixe et toujours init.

Pour l'étape suivante, envisagez de packager un shortcode en tant qu'extension autonome et de le soumettre au répertoire WordPress.org, c'est la meilleure façon de séparer la fonctionnalité du thème et de faire progresser votre profil de développeur.