Shortcode WordPress : Comment créer un code court WordPress ?

Un shortcode WordPress permet d’insérer facilement une fonctionnalité ou un contenu dynamique dans une page, un article ou une autre zone compatible de WordPress, sans devoir réécrire le code PHP à chaque utilisation.

Shortcode WordPress : quelle différence entre shortcode autofermant et shortcode avec contenu ?

Il existe donc deux grands formats.

Shortcode autofermant

[mon_shortcode]

Ou avec des paramètres :

[mon_shortcode titre="Bonjour"]

La fonction génère elle-même tout le contenu.

Shortcode avec contenu

[mon_shortcode]
Mon contenu
[/mon_shortcode]

Ici, le contenu situé entre les deux balises est transmis à la fonction sous la forme de $content.

Le choix dépend simplement de ce que vous souhaitez faire.

Pour afficher une information prédéfinie, un shortcode autofermant est généralement suffisant.

Pour créer un conteneur autour d’un contenu fourni par l’utilisateur, le shortcode avec fermeture est plus adapté.

Pourquoi utiliser return plutôt que echo dans un shortcode ?

C’est une erreur fréquente lorsque l’on crée son premier shortcode.

Dans votre fonction, vous pourriez être tenté d’écrire :

echo 'Bonjour !';

Mais un shortcode doit normalement retourner son résultat :

return 'Bonjour !';

WordPress insère ensuite le résultat retourné à l’endroit où le shortcode apparaît dans le contenu. La documentation officielle décrit précisément le fonctionnement des callbacks de shortcode autour de cette valeur de retour.

Prenez donc cette habitude :

function mon_shortcode() {
    return '<p>Mon contenu</p>';
}

plutôt que :

function mon_shortcode() {
    echo '<p>Mon contenu</p>';
}

Cette distinction devient particulièrement importante lorsque le shortcode génère du HTML plus complexe.

Comment utiliser un shortcode WordPress dans Gutenberg ?

Une fois votre shortcode enregistré, vous devez simplement l’insérer à l’endroit où vous souhaitez afficher son résultat.

Avec l’éditeur de blocs WordPress, vous pouvez utiliser un bloc Shortcode.

Insérez ensuite :

[mon_message]

WordPress interprétera le shortcode lors de l’affichage du contenu.

Vous pouvez également l’insérer directement dans certaines zones textuelles compatibles avec les shortcodes.

L’idée importante est de distinguer le code PHP qui crée le shortcode du code court que vous utilisez dans l’éditeur.

Le PHP peut être relativement complexe, tandis que l’utilisateur final peut simplement avoir besoin d’écrire :

[ma_banniere]

C’est justement l’un des grands intérêts de l’API Shortcode.

Comment créer un shortcode WordPress pour une bannière personnalisée ?

Prenons maintenant un cas plus concret.

Supposons que vous souhaitiez afficher une bannière avec un titre, un texte et un bouton.

Vous pourriez créer :

[banniere titre="Création de site web" texte="Découvrez nos services" url="/services"]

Le code pourrait être :

function ma_banniere_shortcode( $atts ) {

    $atts = shortcode_atts(
        array(
            'titre' => 'Découvrez nos services',
            'texte' => 'Une solution adaptée à votre projet.',
            'url'   => '#',
        ),
        $atts,
        'banniere'
    );

    return sprintf(
        '<div class="ma-banniere">
            <h2>%s</h2>
            <p>%s</p>
            <a href="%s">Découvrir</a>
        </div>',
        esc_html( $atts['titre'] ),
        esc_html( $atts['texte'] ),
        esc_url( $atts['url'] )
    );
}

add_shortcode( 'banniere', 'ma_banniere_shortcode' );

Vous pourrez alors réutiliser le même composant sur plusieurs pages :

[banniere titre="Site vitrine" texte="Présentez votre entreprise en ligne" url="/services/site-vitrine"]

ou :

[banniere titre="E-commerce" texte="Développez vos ventes en ligne" url="/services/site-e-commerce"]

Vous n’avez plus besoin de recopier le HTML à chaque fois.

C’est un excellent exemple de la manière dont un shortcode WordPress personnalisé peut simplifier la gestion d’un site.

Comment exécuter un shortcode WordPress dans du PHP ?

Il existe une autre situation fréquente : vous avez un shortcode et vous souhaitez l’appeler directement depuis un fichier PHP de votre thème ou de votre plugin.

Dans ce cas, vous pouvez utiliser do_shortcode().

Par exemple :

echo do_shortcode( '[mon_message]' );

Avec des attributs :

echo do_shortcode(
    '[banniere titre="Mon titre" url="/contact"]'
);

La fonction do_shortcode() demande à WordPress d’analyser une chaîne et d’exécuter les shortcodes qu’elle contient.

Cette technique peut être utile dans un template PHP lorsque vous voulez conserver la logique d’un shortcode tout en l’affichant directement dans votre thème.

Il faut cependant éviter d’utiliser cette méthode partout sans raison. Si vous contrôlez directement la fonction qui génère le contenu, il est souvent plus propre de réutiliser cette fonction plutôt que de construire une chaîne contenant un shortcode pour ensuite la faire analyser.

Comment éviter les conflits entre shortcodes WordPress ?

Le nom d’un shortcode doit être choisi avec soin.

Évitez par exemple un nom extrêmement générique :

[button]

Un plugin installé ultérieurement pourrait utiliser le même nom.

WordPress précise qu’un seul gestionnaire peut être associé à un nom de shortcode et qu’un enregistrement ultérieur avec le même identifiant peut prendre la priorité.

Pour vos propres développements, utilisez donc un préfixe spécifique à votre projet.

Par exemple :

[manu_button]

plutôt que :

[button]

Ou :

[npe_banner]

plutôt que :

[banner]

Cette petite précaution réduit considérablement les risques de conflit avec un thème ou une extension.

La documentation WordPress recommande également de privilégier des noms de shortcode en minuscules et d’éviter les tirets lorsque vous les définissez.

Pourquoi mon shortcode WordPress ne fonctionne pas ?

Plusieurs problèmes peuvent empêcher un shortcode de fonctionner.

Le shortcode apparaît sous forme de texte

Si votre page affiche :

[mon_shortcode]

au lieu du résultat attendu, vérifiez d’abord que le shortcode est réellement enregistré.

Si le shortcode provient d’un plugin, vérifiez également que celui-ci est toujours actif. Un shortcode fourni par une extension désactivée ne peut plus appeler sa fonction associée.

Vérifiez aussi l’orthographe :

[mon_shortcode]

n’est pas identique à :

[mon-shortcode]

Un simple caractère peut donc suffire à provoquer le problème.

La fonction n’est pas chargée

Si votre code se trouve dans functions.php, vérifiez qu’il n’y a pas d’erreur PHP dans le fichier.

Si vous utilisez un plugin personnalisé, vérifiez que celui-ci est activé.

Le shortcode porte le même nom qu’un autre

Un conflit de nom peut également produire un comportement inattendu. Utiliser un préfixe unique est donc une bonne pratique.

Vous utilisez echo au lieu de return

Votre fonction doit généralement retourner le contenu :

return $output;

et non l’envoyer directement avec :

echo $output;

Les attributs ne sont pas récupérés correctement

Si vous utilisez des paramètres, vérifiez leur nom et utilisez shortcode_atts() pour définir proprement leurs valeurs par défaut.

Faut-il créer un shortcode WordPress dans functions.php ou dans un plugin ?

La réponse dépend de la nature de votre fonctionnalité.

Si votre shortcode est intimement lié à l’apparence ou au fonctionnement d’un thème particulier, functions.php peut convenir.

En revanche, si votre shortcode représente une fonctionnalité métier que vous souhaitez conserver même après un changement de thème, un plugin personnalisé est généralement plus logique.

Imaginez un site qui utilise :

[prix-produit]

pour afficher une donnée importante dans ses pages.

Si ce shortcode se trouve uniquement dans le thème et que vous changez de thème, la fonctionnalité peut disparaître alors que vos contenus continuent de contenir les balises du shortcode.

Séparer les fonctionnalités du design permet donc de construire un site plus facile à maintenir.

Shortcode WordPress : plugin ou code personnalisé ?

Vous n’avez pas nécessairement besoin d’une extension pour créer un shortcode.

Un shortcode personnalisé peut être développé directement en PHP avec l’API native de WordPress. Plusieurs guides spécialisés présentent d’ailleurs cette approche, avec add_shortcode() et shortcode_atts().

Cependant, une extension peut être intéressante lorsque vous ne souhaitez pas modifier les fichiers de votre thème ou lorsque plusieurs shortcodes doivent être administrés.

La bonne solution dépend donc surtout du niveau de personnalisation recherché.

Pour un simple shortcode, quelques lignes de PHP suffisent.

Pour un système plus complexe comprenant plusieurs composants, paramètres, styles CSS et logique métier, un plugin personnalisé peut devenir beaucoup plus intéressant.

Les bonnes pratiques pour créer un shortcode WordPress

Un shortcode peut être très simple, mais quelques règles permettent d’éviter des problèmes à long terme.

Commencez par utiliser un nom unique et préfixé. Ensuite, définissez clairement les attributs acceptés avec shortcode_atts() plutôt que de récupérer aveuglément toutes les données transmises.

Pensez également à sécuriser les données dynamiques avec les fonctions d’échappement adaptées à leur contexte : esc_html(), esc_attr(), esc_url() ou d’autres fonctions WordPress selon le type de donnée.

Enfin, gardez votre logique métier séparée lorsque le shortcode devient important. Une fonction dédiée peut générer le contenu tandis que le shortcode ne sert qu’à faire le lien entre WordPress et cette fonction.

Cette organisation rend le code plus lisible et facilite sa réutilisation.

Shortcode WordPress : un outil pratique pour personnaliser un site

Le shortcode reste particulièrement intéressant lorsqu’une fonctionnalité doit être répétée à plusieurs endroits tout en restant facile à utiliser depuis l’administration WordPress.

Vous pouvez par exemple créer des shortcodes pour :

• des boutons personnalisés ;
• des encarts promotionnels ;
• des appels à l’action ;
• des formulaires ;
• des informations dynamiques ;
• des listes de contenus ;
• des données provenant d’une API ;
• des blocs personnalisés ;
• des composants WooCommerce ;
• des éléments spécifiques à votre activité.

Le véritable intérêt n’est donc pas seulement de raccourcir du code. C’est surtout de transformer une fonctionnalité PHP en élément réutilisable dans l’éditeur WordPress.

FAQ sur les shortcodes WordPress

Qu’est-ce qu’un shortcode WordPress ?

Un shortcode WordPress est une syntaxe courte, généralement écrite entre crochets, qui permet d’appeler une fonctionnalité enregistrée dans WordPress. Exemple : [mon_shortcode].

Comment créer un shortcode WordPress ?

Il faut créer une fonction PHP qui génère le résultat souhaité, puis l’enregistrer avec add_shortcode(). Le shortcode peut ensuite être utilisé dans un contenu compatible.

Où mettre le code d’un shortcode WordPress ?

Vous pouvez le placer dans functions.php ou, pour une fonctionnalité indépendante du thème, dans un plugin personnalisé.

Peut-on créer un shortcode WordPress avec des paramètres ?

Oui. Les attributs peuvent être transmis directement dans le shortcode, par exemple [bouton url="/contact" texte="Me contacter"]. La fonction shortcode_atts() permet notamment de définir les valeurs par défaut.

Peut-on mettre du contenu dans un shortcode ?

Oui. Vous pouvez utiliser un format comme [encadre]Mon contenu[/encadre] et récupérer le contenu avec le paramètre $content.

Peut-on utiliser un shortcode directement dans un fichier PHP ?

Oui. La fonction do_shortcode() permet notamment de faire interpréter une chaîne contenant un shortcode depuis du code PHP.

Pourquoi mon shortcode WordPress apparaît-il directement sur ma page ?

Cela peut être dû à un shortcode mal écrit, à une extension désactivée, à une fonction qui n’est pas chargée ou à un conflit de nom. Vérifiez d’abord le nom exact du shortcode et son enregistrement.

Conclusion

Créer un shortcode WordPress n’est pas particulièrement compliqué dès lors que l’on comprend le fonctionnement de l’API Shortcode. Une fonction PHP génère le contenu, add_shortcode() l’enregistre, puis une syntaxe comme [mon_shortcode] permet de l’utiliser dans le contenu.

Pour aller plus loin, vous pouvez ajouter des attributs avec shortcode_atts(), accepter du contenu avec $content, sécuriser les données dynamiques et utiliser do_shortcode() lorsque vous devez exécuter un shortcode depuis du PHP. Ces mécanismes constituent les principales briques de l’API native de WordPress.

Si votre projet nécessite des shortcodes WordPress personnalisés, des fonctionnalités PHP, une intégration API ou une personnalisation avancée de votre site, vous pouvez également découvrir mes services de développement web.