Code court WordPress — PerfectPixels

Qu’est-ce qu’un code court WordPress?

Un code court WordPress (shortcode) est une balise entre crochets, comme [gallery] ou [contact-form id="12"], que WordPress remplace par le résultat d’une fonction PHP au moment d’afficher le contenu. Il permet aux rédacteurs d’insérer des fonctionnalités dynamiques ou complexes dans une publication sans écrire de code.

L’API des codes courts a été ajoutée dans WordPress 2.5, bien avant l’arrivée des blocs, et fait toujours partie du cœur. WordPress en fournit quelques-uns, dont [gallery], [caption], [audio], [video], [playlist] et [embed], et de nombreuses extensions s’en servent pour placer des formulaires, des carrousels ou des grilles de produits. Dans l’éditeur de blocs, on ajoute un code court avec le bloc Code court dédié, même si les blocs sont largement devenus la façon privilégiée de bâtir ces fonctionnalités.

Pourquoi les codes courts sont importants

Même sur les sites modernes, les codes courts sont partout; il est donc utile de comprendre leurs forces et leurs limites.

Réutilisation simple : une seule fonction peut afficher la même fonctionnalité partout où l’on peut saisir du texte : articles, pages, widgets et bon nombre d’options de thème.
Contenu dynamique : le contenu est généré à l’affichage; un code court qui liste les événements à venir présente donc toujours des données à jour.
Compatibilité avec l’existant : le contenu plus ancien et de nombreux constructeurs de pages dépendent des codes courts, qui doivent continuer de fonctionner pendant les refontes et les migrations.
Expérience d’édition limitée : les rédacteurs voient une balise entre crochets plutôt qu’un aperçu, et une faute de frappe dans un attribut échoue sans avertissement.
Dépendance du contenu : si l’extension qui enregistre un code court est retirée, la balise brute s’affiche en texte ordinaire sur la page publiée.

Comment fonctionne un code court

Enregistrement : une extension ou un thème appelle add_shortcode( 'tag', 'callback' ), qui associe un nom de balise à une fonction PHP.
Analyse : au moment d’afficher le contenu, WordPress le fait passer par do_shortcode(), repère les balises enregistrées et appelle leurs fonctions de rappel.
Attributs : des valeurs comme [team count="4"] sont transmises à la fonction de rappel sous forme de tableau; shortcode_atts() les fusionne avec les valeurs par défaut et écarte les clés inconnues.
Contenu encadré : un code court peut envelopper du contenu, comme dans [note]Text[/note], et la fonction de rappel reçoit ce texte intérieur comme deuxième argument.
Retourner, pas afficher : la fonction de rappel doit retourner son HTML sous forme de chaîne. L’afficher directement (echo) l’imprime au mauvais endroit dans la page, généralement au-dessus du contenu.

Erreurs courantes avec les codes courts

Afficher au lieu de retourner : le bogue le plus fréquent, qui fait apparaître le résultat en haut de la page.
Sortie non échappée : afficher les valeurs des attributs sans esc_html() ou esc_attr(), ce qui ouvre la porte aux attaques par script intersite (XSS) de la part de quiconque peut modifier le contenu.
Noms de balises génériques : utiliser des noms comme [button] qui entrent en conflit avec d’autres extensions. Ajoutez aux balises un préfixe propre au projet.
Enregistrement dans le thème : définir les codes courts dans functions.php, si bien qu’un changement de thème laisse des balises brutes partout sur le site.
Chargement des ressources sur chaque page : charger le CSS et le JavaScript d’un code court sur tout le site plutôt que seulement là où il est utilisé.

Pratiques exemplaires pour les codes courts

Placez-les dans une extension : enregistrez les codes courts dans une extension propre au site ou à la fonctionnalité pour qu’ils survivent aux changements de design.
Validez et échappez tout : nettoyez les attributs à l’entrée et échappez-les à la sortie.
Documentez chaque balise : dressez pour les rédacteurs la liste des attributs offerts et de leurs valeurs par défaut, avec un exemple.
Privilégiez les blocs pour les nouvelles fonctionnalités : un bloc personnalisé offre aux rédacteurs un aperçu en direct, de vrais contrôles et des réglages structurés. Notre fiche sur l’éditeur Gutenberg explique le fonctionnement des blocs.
Utilisez les codes courts là où les blocs ne vont pas : ils restent utiles dans les widgets classiques, certains réglages de thème et lorsqu’on appelle do_shortcode() à partir du code d’un modèle.
Faites l’inventaire avant de retirer une extension : cherchez les balises d’une extension dans la base de données avant de la désactiver, pour qu’aucun code court brut ne reste visible.

Les codes courts chez PerfectPixels

Dans le cadre de notre développement d’extensions WordPress sur mesure, nous bâtissons les fonctionnalités sous forme de blocs par défaut et ajoutons un code court lorsqu’un client en a besoin à des endroits où les blocs ne peuvent pas aller, ou pour assurer la compatibilité avec le contenu existant. Lors des refontes et des migrations, nous recensons aussi les anciens codes courts, souvent laissés par d’anciens constructeurs de pages, puis nous les convertissons ou les retirons pour que rien ne se brise au lancement.

Questions fréquentes

Les codes courts sont-ils encore pris en charge par WordPress?

Oui. L’API des codes courts fait partie du cœur de WordPress et fonctionne dans l’éditeur de blocs grâce au bloc Code court. Ce n’est plus l’approche recommandée pour les nouvelles fonctionnalités destinées aux rédacteurs, mais elle n’est pas obsolète.

Pourquoi un code court s’affiche-t-il en texte sur ma page?

La fonction qui le traite n’est pas enregistrée, généralement parce que l’extension ou le thème qui le fournissait a été désactivé ou retiré. Cela peut aussi se produire si le code court est placé à un endroit où WordPress ne traite pas les codes courts, comme certains champs personnalisés.

Devrais-je convertir mes codes courts en blocs?

Pour les fonctionnalités que vos rédacteurs utilisent souvent, oui : les blocs sont plus faciles à utiliser et affichent un aperçu. Pour le contenu rarement utilisé ou plus ancien, on peut souvent laisser les codes courts en place, tant que l’extension qui les gère est entretenue.

Ressources connexes

Pour aller plus loin : Shortcodes — WordPress Developer Resources.

Code court WordPress (shortcode)