Shortcode WordPress

Shotcode WordPress

Le shortcode WordPress est introduit avec la version 2.5 du CMS. Il permet à l’utilisateur d’injecter facilement dans ses pages ou ses posts (les articles WordPress) des fonctionnalités natives ou tièrce partie, avec un code simple se rapprochant du bbcode. Mais la plateforme nous permet aussi de créer nos propres raccourcis via une API simple.

Cet article est un tutoriel sur les shortcode WordPress. Il est peu long. Si vous n’êtes pas familiarisé avec cette API, il est fait pour vous. Prenez le temps de le parcourir !

Un bout de code user-friendly pour améliorer vos pages

Un shortcode est un raccourci pour créer du contenu. Ce contenu peut être appelé depuis la base de donnée, ou statique (créé une fois pour toutes et « servi » tel quel à vos visiteurs). Il peut présenter une information ou créer un formatage HTML prédéfini pour vous aider à mettre en forme vos articles ou vos pages.

Initialement, le BBCode est mis au point en PHP pour éviter l’injection de code dans les champs de texte et formulaires devant être soumis, et limiter ainsi les failles de sécurité. Ce code interdisant l’inclusion de balises HTML (délimités par « < » et « > »), ces derniers sont remplacés par des crochets ( ‘[ » et « ] »). Enfin, ce code étant destiné à l’utilisateur lambda, il doit être simple et intuitif.

Cette fonctionnalité exécute un callback : une fonction générant du contenu. Cette fonction pouvant accepter des options (des arguments), utilisables dans le bout de code lui-même avec une simple définition du type option=valeur. Donc, le shortcode est un raccourci (shortcut en anglais) prenant la forme d’un bbcode.

Où trouver les shortcodes

Le CMS met à disposition beaucoup de shortcodes (dits « natifs« ) difficle à lister ici de façon exaustive. Par exemple :

  • pour les vidéos : des raccourcis sont disponibles pour YouTube ([YouTube]), Vimeo ([vimeo]) ou Flirk ([flirk]) ;
  • pour l’audio : le shortcode [playlist] vous permet par exemple d’insérer facilement une playlist audio, les fichiers étant choisis depuis votre bibliothèque ;
  • pour les images : vous pouvez aussi importer une ou des images depuis votre compte Instagram avec [instagram].

Nombre de shortcodes sont aussi mis à disposition par votre thème WordPress premium. Ce dernier proposera généralement des shortcodes pour la création de titres formatés (type <h1>, <h2>, etc.), d’images animées, d’entrées d’articles récents ou de posts customisés (par exemple les membres de votre équipe), de galeries d’images, ou de barres de progression (très à la mode en ce moment).

Vous pourrez aussi trouver des shortcodes mis à disposition avec les plug-ins téléchargés sur la page des plug-ins WordPress, comme par exemple, le plug-in Gigpress, permettant d’afficher un agenda de dates de spectacle, paramétrable à l’aide d’un raccourci comme celui-ci : [gigpress_shows artists=8 limitr=10]. Ce bout de code très simple permet d’afficher les spectacles de 8 artistes référencés par groupe de 10.

Les options du short code

Le système de shortcode WordPress autorise généralement l’utilisation d’options, définies après le nom du raccourci entre les crochets, sous forme de paires clé= »valeur » (les guillemets sont optionnels) ou de valeur simple.


 	[un_shortcode option_simple option_numero=275 ]

Par exemple, le shortcode YouTube attend de recevoir l’URL de la vidéo partagée :


 	[YouTube https://www.youtube.com/watch?v=WVbQ-oro7FQ] 

Les dimensions de la vidéo affichée seront insérées directement dans l’URL YouTube, à l’inverse du shortcode Vimeo, qui attend que ces valeurs soient fixées avec une paire d’options « w=500&h=280 » séparée par « & » et définie entre les crochets :


 	[vimeo 44633289 w=500&h=280] 

Un dernier exemple de shortcode natif est [list-pages], qui permet d’afficher toutes les pages de votre site. Il vous permet d’afficher une liste des pages WordPress, mais aussi d’assigner des options de tri, d’exclusion ou inclusion de pages spécifiques, de statut (publiée ou non) ou d’appartenance à un groupe de pages-enfants. Voici quelques exemples d’utilisation du shortcode WordPress « list-page » :

Affichage de la liste de toutes les pages WordPress


 	[list-pages] 

Trie par date de création


 	[list-pages sort_column=’post_date’] 

Exclusion des pages enfants


 	[list-pages depth=1] 

affichage d’un en-tête de liste avant les liens vers vos pages


 	[list-pages title_li='Mes méga pages'] 

affichage d’un en-tête de liste avant les liens vers vos pages


 	[list-pages title_li='Mes méga pages'] 

Pour en savoir plus, consultez la page du codex WordPress portant sur le shortcode «list-pages».

Creez votre shortcode WordPress

WordPress met à notre disposition une API très simple pour créer vos propres shortcodes. Directement dans votre fichier functions.php (à la racine du répertoire de votre thème) ou au sein d’un plug-in, vous définissez une fonction retournant ce que vous souhaitez afficher (cette fonction n’affiche rien par elle-même). Par exemple :


<?php
	function mes_coords( $attrs, $content=null){
		$coords = '<ul>';
		$coords .= '<li>Le méga Moi</li>';
		$coords .= '<li>23 rue machin</li>';
		$coords .= '<li>75000 Paris</li>';
		//Options par défaut insérées ici
		return $coords
	}

Cette fonction créée une liste non ordonnée (pas de numéro) reprenant les éléments de coordonnées que je souhaite afficher, et la retourne. Maintenant, il suffit d’assigner une fonction à mon raccourci, chargée d’exécuter ce que je souhaite&nbsp;:0


	<?php add_shortcode( 'mon_shortcode', 'mes_coords' ); ?>

Notre shortcode WordPress déclaré, intéressons-nous aux options. L’argument $attrs correspond aux options que vous souhaitez donner aux utilisateurs pour votre shortcode. Nous l’avons vu, ces options sont passées au code par l’utilisateur lui-même. $attrs est en fait un tableau associatif d’éléments qui sera utilisés par notre fonction. Si vous utilisez ce mécanisme, il vous faudra créer un tableau de valeurs par défaut pour les options, à assigner en cas de non-déclaration ou de mauvaise déclaration par l’utilisateur. Ce tableau par défaut sera fusionné avec les valeurs reçues. Ici on créé, à l’endroit indiqué plus haut, un tableau d’options pour des éléments ‘nom’, ‘adresse’, ‘code_postal’ et ‘ville’ :

Votre devis en 48 H chrono !

Demandez à être rappelé !

Nous préciserons ensemble votre projet
de vive voix 


	$default = array(
		"nom" 		=> "Leméga Moi",
		"adresse"	=> "23 rue machin",
		"code_postal"	=> "75000",
		"ville"		=> "Paris"
	);
	// Ici le formatage du contenu retourné

Ensuite, on fusionne le tableau avec les valeurs déclarées. On utilise pour cela la fonction shortcode_atts( $default, $attrs );

Le premier argument est le tableau par défaut, le second les options définies par l’utilisateur, reçues sous forme de tableau. On note ici que la fonction shortcode_atts() créée un tableau de sortie, passe en revue les éléments du tableau par défaut, vérifie pour chacun si une entrée existe dans le tableau d’options passées, et créé une entrée similaire dans le tableau de sortie, assignée de la valeur définie en option, ou par défaut suivant qu’elle existe ou non dans l’argument $attrs.

Pour un confort d’utilisation, on pourra du même coup fusionner ces valeurs et créer les variables accessibles à partir du tableau de sortie avec la fonction PHP extract(). Les entrées du tableau $default seront accessibles via des variables de forme $entrée ($nom, $adress, $code_postal, $ville) :


	<?php extract( shortcode_atts( $defaults, $atttrs ) ); ?>

Toutes les variables nécessaires étant disponibles, notre fonction ‘mes_coords’ se contentera donc de formater le contenu que nous souhaitons proposer en raccourci dans nos pages, en utilisant les variables extraites et leur valeur :


	$output = '<ul class="mes-coords">';
	$output .= '<li>'.$nom.'</li>';
	$output .= '<li>'.$adresse.'</li>';
	$output .= '<li>'.$code_postal.'</li>';
	$output .= '<li>'.$ville.'</li>';
	$output .= '</ul>';
	// Ici le traitement du contenu textuel
	return $output;

On se retrouve du coup avec un shortcode pleinement fonctionnel et paramétrable directement depuis la page d’administration :


	[mon_shortcode nom="Bibi" adress="58 rue truc" code_postal="44000" ville="Nantes" ]

Du contenu dans un shortcode WordPress

L’API Shortcode nous permet d’insérer du contenu textuel avec notre bout de code. Imaginons que l’on souhaite pouvoir afficher un message au visiteur, facilement mis à jour (par exemple en fonction de la période de l’année).

On utilise pour cela, les crochets fermants comme délimiteur. Ils reprennent le nom du raccourci entre crochets en le faisant précéder d’un slash « / ». Les deux blocs entre crochets enveloppent donc notre contenu textuel comme ceci :


	[mon_shortcode]Du contenu textuel à afficher[/mon_shortcode]

Nous allons récupérer ce texte avec la variable $content de la fonction liée (le callback) :


	<?php function ma_fonction( $attrs=array(), $content=null){…}?>

On veillera à sécuriser l’entrée textuelle avec des fonctions WordPress comme sanitize_text_field() ou wp_kses(), ou simplement avec la fonction PHP htmlspecialchars(), suivant ce que l’on souhaite faire. J’utilise ici htmlspecialchars() pour simplifier (on inséré ce code à l’endroit précité) :


	<?php if( $content)  $output .= '<p class="alert-coords">'. htmlspecialchars( $content );.'</p>'; ?>

Notre liste est renvoyée, agrémentée d’un paragraphe d’alerte si le contenu est renseigné.

Des shortcodes dans les shortcodes

WordPress nous permet de chaîner les shortcodes. Cela peut s’avérer très pratique pour créer rapidement un layout pour les pages, ou combiner deux fonctionnalités différentes. Ceci est expliqué plus en détail dans l’article [jst_a class= »underligned » href= »/shortcode-wordpress-empilements/ »]Shortcode WordPress : Attention aux empilements[/jst_a], mais en gros voilà le mécanisme :

Imaginons que nous ayons créé un shortcode [mystars] mettant un valeur un contenu en l’entourant d’étoiles :


	<span class="mystars">***</span>  ici mon contenu textuel  <span class="mystars">***</span>

On pourrait tout à fait insérer du code dans le code comme ceci :


	[mon_shortcode nom="Bibi" adress="53 rue machin" code_postal="75000" ville="Paris"]
		[mystars]Le contenu à afficher[/mystars]
	[/mon_shortcode]

Le contenu doit être parsé avec do_shortcode(), pour rechercher et exécuter les éventuels shortcodes imbriqués. Directement dans le callback, nous traitons le contenu récupéré avec notre variable $content, avant de l’utiliser dans le HTML formaté renvoyé :


<?php
	$content = do_shortcode( $content ); 
	$output = '<ul><!-- Ici notre liste représentant nos coordonnées --></ul>';
	$output .= '<p class="star-p">' . $content . '</p>';
	return $output;

Notre premier shortcode WordPress possède bien contenu incluant un shortcode, traité comme tel, avant sont affichage.

Conclusion sur le shortcode WordPress

Que vous soyez simple utilisateur ou développeur en devenir, le shortcode WordPress vous apparaîtra bientôt comme incontournable tant il permet d’afficher à sans effort des fonctionnalités puissantes.

Pour aller plus loin

Voilà vous en savez beaucoup. Pour en apprendre d’avantage n’hésitez à consulter :