Comprendre les shortcodes WordPress : créer, personnaliser et utiliser ses propres shortcodes en PHP

• Que sont les shortcodes dans WordPress ?
• Où pouvez-vous utiliser les shortcodes WordPress ?
• Créez votre propre shortcode dans WordPress
• Créer un shortcode avec des attributs
• Utiliser un shortcode dans les publications et les pages
• Utiliser des shortcodes en PHP : Thème, Thème enfant, fonctions.php
• Shortcode de sortie en PHP
• Enregistrer le contenu du shortcode dans une variable
• Mise en mémoire tampon de sortie pour les codes courts qui utilisent l’écho au lieu du retour
• Personnaliser et étendre les shortcodes
• Avantages et inconvénients des shortcodes WordPress
• Sécurité et bonnes pratiques pour vos propres shortcodes

Si vous travaillez avec WordPress depuis longtemps, vous ne pourrez guère éviter les shortcodes. Qu’il s’agisse d’un formulaire de contact, d’une galerie, d’un curseur ou de zones d’information spéciales, ces fonctions contiennent souvent un code court entre crochets.

Dans cet article, je vais vous montrer ce que sont les shortcodes WordPress, comment créer vos propres shortcodes, comment les utiliser dans les articles et les pages et comment vous pouvez utiliser les shortcodes directement en PHP dans votre thème ou thème enfant. Nous examinerons également les avantages et les inconvénients des shortcodes ainsi que quelques bonnes pratiques pour que votre code reste maintenable plus tard.

Que sont les shortcodes dans WordPress ?

Les shortcodes sont de petits espaces réservés entre crochets, par exemple :

[gallery]
[contact-form-7 id="123"]
[mein_shortcode foo="bar"]

WordPress reconnaît ces codes courts lors du rendu du contenu et les remplace par du code HTML ou une autre sortie. La logique réelle réside dans les fonctions PHP enregistrées via l’API shortcode.

En bref :
Les shortcodes sont un raccourci permettant d’incorporer des fonctions complexes dans les articles et les pages WordPress sans que l’éditeur ait besoin d’écrire du PHP.

Exemples typiques de shortcodes WordPress :

• Formulaires de contact
• Galeries d’images et curseurs
• Boîtes d’informations, boutons, accordéons
• listes dynamiques, par exemple les derniers articles ou produits

Où pouvez-vous utiliser les shortcodes WordPress ?

Les shortcodes ne se limitent pas aux articles ou aux pages. Vous pouvez les utiliser à de nombreux endroits dans votre projet WordPress.

Emplacement	Exemple	Remarque
Articles et pages (Gutenberg)	Bloc de shortcode avec [mein_shortcode]	À propos du bloc « Shortcode » Insérer
Éditeur classique	Écrire directement dans le contenu	Le shortcode est remplacé lors du rendu
Widgets	Widget texte ou HTML avec [mein_shortcode]	En fonction du thème, les shortcodes dans les widgets doivent être activé
Modèles PHP	echo do_shortcode('[mein_shortcode]');	Idéal dans un thème ou un thème enfant
Générateur de pages / Champs personnalisés	De nombreux constructeurs traitent automatiquement les shortcodes	En fonction du plugin

Cela rend les shortcodes flexibles et particulièrement pratiques lorsque vous souhaitez réutiliser des fonctions ou les intégrer à différents endroits.

Créez votre propre shortcode dans WordPress

Vous pouvez créer vos propres shortcodes en utilisant la fonction add_shortcode(). Vous attribuez un nom et une fonction de rappel qui génère la sortie.

Un exemple très simple ressemble à ceci :

// In die functions.php deines Child Themes oder in ein eigenes Plugin
add_shortcode('my_shortcode', function ($atts) {
    $result = 1 + 1;

    return $result;
});

Quelques points importants :

• Le nom du shortcode ici est my_shortcode. Vous pourrez l’appeler plus tard avec [my_shortcode].
• La fonction de rappel doit return et ne pas utiliser directement echo.
• Vous pourrez ensuite enregistrer le shortcode dans une variable ultérieurement et l’utiliser de manière flexible.

Créer un shortcode avec des attributs

En pratique, vous souhaitez souvent passer des paramètres, par exemple :

[box color="red" title="Hinweis"]
Mein Box Inhalt
[/box]

Vous pouvez utiliser shortcode_atts() pour définir les valeurs par défaut et traiter les attributs proprement :

add_shortcode('my_box', function ($atts, $content = '') {

    $atts = shortcode_atts([
        'color' => 'blue',
        'title' => '',
    ], $atts, 'my_box');

    $color = esc_attr($atts['color']);
    $title = esc_html($atts['title']);

    ob_start();
    ?>
    <div class="my-box my-box-<?php echo $color; ?>">
        <?php if ($title) : ?>
            <h3 class="my-box-title"><?php echo $title; ?></h3>
        <?php endif; ?>
        <div class="my-box-content">
            <?php echo do_shortcode($content); ?>
        </div>
    </div>
    <?php
    return ob_get_clean();
});

Ici, vous pouvez voir comment vous :

• Fournir aux attributs des valeurs par défaut
• sécurisez la sortie avec esc_attr et esc_html
• Utilise la mise en mémoire tampon de sortie pour les blocs HTML plus longs (ob_start() et ob_get_clean())

Cela permet de garder le code propre et facilement extensible.

Utiliser un shortcode dans les publications et les pages

En supposant que vous ayez créé le shortcode my_box à partir de l’exemple ci-dessus. Dans un article ou sur une page, vous pouvez l’utiliser comme ceci :

[my_box color="green" title="Info"]
Das ist eine grüne Box mit einem Info Titel.
[/my_box]

Dans l’éditeur Gutenberg, procédez comme suit :

1. Modifier le message ou la page
2. Cliquez sur le symbole plus
3. Recherchez « Shortcode »
4. Insérer un bloc de shortcode
5. Saisissez le texte du shortcode, par exemple [my_box color="green"]Inhalt[/my_box]
6. Enregistrer ou publier le message

WordPress remplace ensuite automatiquement le shortcode par le code HTML de votre fonction lorsque vous ouvrez la page.

Utiliser des shortcodes en PHP : Thème, Thème enfant, fonctions.php

Parfois, vous souhaitez utiliser des shortcodes directement dans les modèles PHP, par exemple dans single.php, page.php ou dans un modèle personnalisé.

C’est à cela que sert do_shortcode().

Shortcode de sortie en PHP

Si vous souhaitez afficher un shortcode directement dans le modèle, vous pouvez l’installer comme ceci :

echo do_shortcode('[my_box color="red" title="Achtung"]Inhalt aus dem Template[/my_box]');

• do_shortcode() traite le shortcode et renvoie une chaîne
• Avec echo vous affichez le résultat dans le modèle

Enregistrer le contenu du shortcode dans une variable

Vous pouvez également enregistrer le résultat d’un shortcode dans une variable et le réutiliser. Ceci est utile, par exemple, si vous avez besoin du contenu à plusieurs endroits ou si vous souhaitez néanmoins le modifier.

D’après vos notes :

$shortcode_content = do_shortcode('[my_shortcode]');

La sortie est maintenant dans $shortcode_content et vous pouvez la sortir plus tard ou la traiter davantage.

Mise en mémoire tampon de sortie pour les codes courts qui utilisent l’écho au lieu du retour

En fait, les shortcodes devraient toujours fonctionner avec return. En réalité, il existe des plugins qui utilisent echo directement dans le shortcode. Dans un tel cas, vous pouvez travailler avec la mise en mémoire tampon de sortie :

ob_start();
do_shortcode('[inconvenient_shortcode]');
$shortcode_content2 = ob_get_clean();

• ob_start() démarre le tampon de sortie
• tout ce que le shortcode génère finit dans le tampon
• avec ob_get_clean() vous récupérez le contenu sous forme de chaîne dans une variable et videz le tampon

Vous obtenez ainsi le contenu dans une variable même avec des codes courts « peu pratiques ».

Personnaliser et étendre les shortcodes

Dans de nombreux projets, vous souhaitez non seulement écrire de nouveaux shortcodes, mais également adapter ou étendre les shortcodes existants, par exemple :

• ajouter des classes CSS supplémentaires
• Modifier les valeurs par défaut
• ajuster la structure HTML

En gros, vous avez deux options :

• Créez votre propre shortcode avec un nouveau nom
• Supprimez un shortcode existant et réenregistrez-le

Exemple de suppression d’un shortcode :

add_action('init', function () {
    remove_shortcode('old_shortcode');
});

Vous pouvez ensuite stocker votre propre implémentation avec add_shortcode('old_shortcode', 'meine_neue_funktion');. Mais vous ne devriez le faire que si vous savez exactement quel impact cela aura sur le contenu existant.

Avantages et inconvénients des shortcodes WordPress

Les shortcodes sont utiles, mais pas parfaits. Surtout depuis l’introduction de l’éditeur de blocs, il vaut la peine d’en examiner les avantages et les inconvénients.

Avantage	Inconvénient
Facile à utiliser sans connaissances en programmation	Le contenu dépend fortement du thème ou des plugins
Des fonctions complexes peuvent être utilisées avec un texte court	Si un plugin est désactivé, il reste des fragments de shortcode comme [shortcode] dans le contenu
Fonctionne dans les articles, les pages, les widgets et les modèles PHP	De nombreux shortcodes dans le texte peuvent rendre l’éditeur déroutant
Idéal pour les blocs de construction réutilisables	Les shortcodes sont moins évolutifs que les natifs Blocs
Faciles à intégrer dans vos propres thèmes et thèmes enfants	Les shortcodes élaborés peuvent entraîner des problèmes de performances

Pour les nouveaux projets, il convient de se demander si un bloc Gutenberg ne serait pas une meilleure solution. Mais les shortcodes restent utiles, notamment :

• pour les petites fonctions d’assistance
• en combinaison avec des thèmes et plugins existants
• si vous souhaitez utiliser des fonctions à la fois dans l’éditeur et dans les modèles

Sécurité et bonnes pratiques pour vos propres shortcodes

Pour garantir que vos shortcodes WordPress restent sécurisés et performants, vous devez suivre quelques règles de base.

1. Utilisez des noms et des préfixes uniques Il est préférable d’utiliser un préfixe, par exemple le nom de votre blog ou l’abréviation de votre projet : add_shortcode('cosci_box', 'cosci_box_shortcode'); Cela réduira les conflits avec d’autres thèmes ou plugins.
2. Valider les attributs et échapper les sorties
   • Fournissez aux attributs des valeurs par défaut significatives via shortcode_atts().
   • Sortie sécurisée avec esc_html, esc_attr ou wp_kses
3. Les shortcodes doivent utiliser return au lieu de echo Si votre shortcode renvoie toujours une chaîne, vous pouvez l’utiliser dans les articles, les pages, les variantes, les conditions et les modèles sans aucune solution de contournement avec la mise en mémoire tampon de sortie.
4. Gardez un œil sur les performances Si un shortcode effectue des requêtes de base de données complexes ou des appels d’API externes, cela peut être un frein s’il y a de nombreuses occurrences sur une page. La mise en cache, les transitoires ou la logique de requête intelligente vous aident ici.
5. Il est préférable d’externaliser les shortcodes vers un plugin Si vous mettez vos propres shortcodes dans un petit plugin, ils survivront à un changement de thème. Cela signifie que votre projet reste plus flexible sur le long terme.

Cet article a été traduit à l’aide de l’IA.