Selon la définition de WordPress.com, un code court (ou shortcode) est un code spécifique à WordPress qui vous permet de faire des choses pratiques avec très peu d’effort. Les codes courts peuvent avec une seule ligne intégrer des fichiers ou créer des objets qui nécessiteraient normalement beaucoup de code compliqué et laid. En d’autres termes, grâce aux codes courts WordPress, les utilisateurs n’ont pas besoin d’ajouter manuellement du code HTML dans le contenu de l’article et, en outre, il est possible de modifier dynamiquement l’affichage dans des conditions spécifiques (par exemple, l’utilisateur connecté, la date du jour, la localisation lieu de l’utilisateur, etc).

Si vous avez déjà utilisé le code courts [gallery], vous savez déjà comment fonctionnent les codes courts WordPress :

[gallery ids="129,130,131,132" order="DESC" orderby="title" columns="4"]

Dans cet exemple, gallery est la balise de code court, tandis que ids, order, orderby et colums sont les attributs du code court. Ces attributs déterminent le code HTML retourné.

Typologies et structure des codes courts

WordPress fournit deux typologies de codes courts :

  • Les codes courts de fermeture automatique ressemblent au code court [gallery], et ne nécessitent pas de balise de fermeture.
  • Les codes courts de fermeture nécessitent une balise de fermeture, et permettent la manipulation du contenu inclus.

Voici un exemple de code court de fermeture :

[gist]2314628[/gist]

Ce code court est fourni par l’extension Jetpack afin d’intégrer dans les article le code d’un Gist public spécifié par son ID. La chaîne de texte entre la balise d’ouverture et de fermeture est le contenu du code court.

Ce que vous apprendrez dans cet article

Nativement, WordPress fournit six codes courts, et les extensions peuvent ajouter beaucoup plus grâce à l’API de code court (Shortcode API).

L’API de code court est un ensemble simple de fonctions permettant de créer des codes courts WordPress à utiliser dans les articles et les pages.

Dans cet article, je vais vous présenter cette fonctionnalité utile de WordPress du point de vue d’un développeur. A partir de maintenant, nous allons plonger dans l’API de code court en suivant ces étapes :

Le code illustré dans les exemples suivants a été assemblé dans une extension disponible en téléchargement sur Github.

L'image affiche la structure de l’extension kinsta-shortcodes

L’image affiche la structure de l’extension kinsta-shortcodes

Codes courts WordPress pour les développeurs

Lorsque WordPress traite le contenu de l’article, il recherche les codes courts enregistrés. Une fois qu’un code court est trouvé, l’API du code court analyse la balise, les attributs et le contenu inclus, si disponible, et les transmet à une fonction de gestionnaire correspondante. Cette fonction exécute une tâche et retourne une chaîne de caractères à inclure dans le contenu de l’article. Donc, notre première étape est d’enregistrer la balise et le gestionnaire de code court grâce à la fonction add_shortcode :

add_shortcode( 'shortcode_name', 'shortcode_handler' );
  • Le nom du code court est une balise que WordPress recherchera dans le contenu de l’article. Il doit être en minuscules et ne nécessite que des lettres, des chiffres et des underscores
  • le gestionnaire de code court est une fonction de rappel à exécuter lorsque WordPress trouve le code court

La fonction de gestionnaire est définie comme suit :

function shortcode_handler( $atts, $content, $tag ){}

La fonction conserve trois arguments :

  • $atts (tableau) : un tableau d’attributs ou une chaîne vide ;
  • $content (chaîne) : le contenu inclus (disponible uniquement pour l’insertion de codes courts) ;
  • $tag (chaîne) : le nom du code court, utile pour les fonctions de rappel partagées.

Des codes courts peuvent être ajoutés au fichier functions.php d’un thème ou dans une extension. Dans les thèmes nous pouvons exécuter la fonction add_shortcode en l’état, mais dans les extensions nous devrions attendre que WordPress ait été initialisé :

function shortcodes_init(){
	add_shortcode( 'shortcode_name', 'shortcode_handler' );
}
add_action('init', 'shortcodes_init');

Mon premier code court à fermeture automatique

Notre premier code court inclut lélément suivant dans le contenu de l’article :

<a href="" id="" class="" target="">Button</a>

Les attributs et le texte seront définis par les utilisateurs comme suit :

[kinsta_btn href="" id="" class="" target="" label=""]

Maintenant que nous avons fixé notre objectif, ouvrons le fichier principal d’une extension et ajoutons le code suivant :

function kinsta_shortcodes_init(){
	add_shortcode( 'kinsta_btn', 'kinsta_button' );
}
add_action('init', 'kinsta_shortcodes_init');

Définissez ensuite la fonction de gestionnaire de codes courts :

function kinsta_button( $atts ){

	// normalize attribute keys, lowercase
	$atts = array_change_key_case( (array)$atts, CASE_LOWER );
	
	extract( shortcode_atts(
			array(
				'href'		=> '',
				'id'		=> '',
				'class'		=> 'green',
				'target'	=> '',
				'label'		=> 'Button'
			),
			$atts,
			'kinsta_btn'
		) );

	if( in_array( $target, array( '_blank', '_self', '_parent', '_top' ) ) ){
		$link_target = ' target="' . esc_attr( $target ) . '"';
	}else{
		$link_target = '';
	}

	$output = '<p><a href="' . esc_url( $href ) . '" id="' . esc_attr( $id ) . '" class="button ' . esc_attr( $class ) . '"' . $link_target . '>' . esc_attr( $label ) . '</a></p>';
	return $output;
}

Voici ce qui se passe dans cette fonction :

  • array_change_key_case est une fonction PHP qui retourne les clés d’un tableau en majuscules ou minuscules.
  • shortcode_atts est une fonction de WordPress qui combine les attributs de code court utilisateur avec les attributs existants et définit les valeurs par défaut si nécessaire.
  • Le tableau d’attributs qui en résulte est passé dans la fonction PHP extract qui importe les variables d’un tableau dans la table de symboles actuelle.
  • La condition suivante vérifie la valeur de l’attribut target et définit une chaîne vide si aucune valeur valide n’est trouvée.
  • La variable $output stocke le code HTML de l’élément d’ancre, qui est finalement retourné par la fonction.

Afin de convertir l’élément a en un élément CSS3 attractif, il faut s’enregistrer et mettre en file d’attente une feuille de style dans la liste des ressources disponibles :

function kinsta_enqueue_scripts() {
	global $post;
	if( is_a( $post, 'WP_Post' ) && has_shortcode( $post->post_content, 'kinsta_btn') ) {
		wp_register_style( 'kinsta-stylesheet',  plugin_dir_url( __FILE__ ) . 'css/style.css' );
    		wp_enqueue_style( 'kinsta-stylesheet' );
	}
}
add_action( 'wp_enqueue_scripts', 'kinsta_enqueue_scripts');

La fonction définit la variable globale $post, puis vérifie deux conditions :

  • si $post est une instance de l’objet WP_Post
  • si le contenu de l’article contient le code court kinsta_btn

Si les deux conditions sont remplies, la fonction enregistre et interroge la feuille de style. Je ne vous montrerai pas le code CSS ici, mais vous pouvez le trouver sur Github. Enfin, nous pouvons ajouter le code court [kinsta_btn] dans le contenu de l’article comme ceci :

[kinsta_btn href="http://www.google.com" class="blue rounded" target="_blank"]
CSS3 bouton

Avec le style CSS approprié, l’ancre sera présentée comme un incroyable bouton CSS3

Construction d’un code court de fermeture

Si nous voulions la même balise HTML à partir d’un code court de fermeture, nous n’apporterions que de petites modifications à la fonction précédente. Tout d’abord, nous allons enregistrer le code court [kinsta_btn_adv] :

function kinsta_shortcodes_init(){
	add_shortcode( 'kinsta_btn_adv', 'kinsta_button_adv' );
}
add_action('init', 'kinsta_shortcodes_init');

Ensuite, nous définirons le nouveau gestionnaire :

function kinsta_button_adv( $atts, $content = null, $tag = '' ){

	// normalize attribute keys, lowercase
	$atts = array_change_key_case( (array)$atts, CASE_LOWER );

	extract( shortcode_atts(
			array(
				'href'		=> '',
				'id'		=> '',
				'class'		=> 'green',
				'target'	=> ''
			),
			$atts,
			'kinsta_btn'
		) );

	if( in_array( $target, array( '_blank', '_self', '_parent', '_top' ) ) ){
		$link_target = ' target="' . esc_attr( $target ) . '"';
	}else{
		$link_target = '';
	}

	$output = '<p><a href="' . esc_url( $href ) . '" id="' . esc_attr( $id ) . '" class="button ' . esc_attr( $class ) . '"' . $link_target . '>' . esc_attr( $content ) . '</a></p>';
	return $output;
}

Nous n’avons pas besoin de l’attribut label pour le bouton, car les utilisateurs passeront la chaîne à travers le contenu du code court. Ayant deux codes courts, nous devons charger la feuille de style dans deux conditions. Donc, changeons la fonction kinsta_enqueue_scripts comme suit :

function kinsta_enqueue_scripts() {
	global $post;

	// see https://codex.wordpress.org/Function_Reference/has_shortcode
	$has_shortcode = has_shortcode( $post->post_content, 'kinsta_btn') || has_shortcode( $post->post_content, 'kinsta_btn_adv');
	
	if( is_a( $post, 'WP_Post' ) && $has_shortcode ) {
		// see https://codex.wordpress.org/Function_Reference/plugin_dir_url
		wp_register_style( 'kinsta-stylesheet',  plugin_dir_url( __FILE__ ) . 'css/style.css' );
		// see https://developer.wordpress.org/reference/functions/wp_enqueue_style/
		wp_enqueue_style( 'kinsta-stylesheet' );
	}
}
add_action( 'wp_enqueue_scripts', 'kinsta_enqueue_scripts');

Nous pouvons maintenant utiliser le code court de fermeture suivant :

[kinsta_btn_adv href="http://kinsta.com/blog/" class="red rounded" target="_blank"]It's Amazing! View more[/kinsta_btn_adv]

CSS3 button

Ajout du code court à partir de l’éditeur visuel

Saisir des codes courts WordPress peut être très ennuyeux et peu convivial. Heureusement, nous pouvons rendre cette tâche rapide et amusante grâce à la fonction API TinyMCE.

Dans ce dernier exemple, nous allons construire une interface qui permettra aux utilisateurs d’insérer facilement des codes courts complexes dans le contenu de la publication. Pour accomplir cette dernière tâche, nous avons besoin d’un TinyMCE et un bouton MCE. Revenons à notre extension WordPress, et ajoutons le code suivant :

// register TinyMCE buttons
function kinsta_register_mce_buttons( $buttons ) {
	$buttons[] = 'kinsta';
	return $buttons;
}
// add new buttons
add_filter( 'mce_buttons', 'kinsta_register_mce_buttons' );

Nous venons d’ajouter un nouveau bouton nommé kinsta. Maintenant, enregistrons une extension TinyMCE :

function kinsta_register_mce_plugin( $plugin_array ) {
   $plugin_array['kinsta'] = plugins_url( '/mce/kinsta/plugin.js', __FILE__ );
   return $plugin_array;
}
// Load the TinyMCE plugin
add_filter( 'mce_external_plugins', 'kinsta_register_mce_plugin' );

Ce code enregistre l’extension kinsta TinyMCE, qui se trouve dans le répertoire /mce/kinsta/. Ouvrez le fichier plugin.js et ajoutez le JavaScript suivant (vous pouvez voir le fichier sur Github) :

(function() {
	tinymce.PluginManager.add( 'kinsta', function( editor ){});
})();

La méthode PluginManager.add enregistre l’extension kinsta. Cette méthode nous permet d’ajouter un bouton personnalisé à l’interface de l’éditeur :

editor.addButton( 'kinsta', {
	title: 'Kinsta buttons',
	text: 'Kinsta',
	icon: 'code',
	onclick: function(){}
});

La propriété onclick définit une nouvelle fonction anonyme, qui définit les propriétés d’une boîte de dialogue :

onclick: function(){
	editor.windowManager.open({
		title: 'Kinsta buttons',
		body: 
		[
			{type: 'textbox', name: 'btn_url', label: 'URL'},
			{type: 'textbox',name: 'btn_label', label: 'Button label'},
			{type: 'textbox', name: 'btn_id', label: 'Button ID'},
			{type: 'listbox', name: 'btn_color', label: 'Button color', values: [
				{text: 'Green', value: 'green'}, 
				{text: 'Blue', value: 'blue'},
				{text: 'Red', value: 'red'},
				{text: 'Grey', value: 'grey'},
				{text: 'Black', value: 'black'}
			]},
			{type: 'checkbox', name: 'btn_corners', label: 'Button corners'}
		],
		onsubmit: function(e){
			var tag = 'kinsta_btn';
			var href = ' href= "' + e.data.btn_url + '"';
			var label = ' label="' + e.data.btn_label + '"';
			var id = ' id="' + e.data.btn_id + '"';
			var corners = e.data.btn_corners == true ? ' rounded' : '';
			var color = e.data.btn_color;
			var css_class = ' class="' + color + corners + '"';
			editor.insertContent('[' + tag + href + id + css_class + label + ']')
		}
	})
}

La boîte de dialogue contient trois boîtes de texte, une zone de liste et une case à cocher. Lorsque le formulaire est soumis, la méthode insertContent inclut le code court dans le contenu de la publication.

MCE dialogue permet

Une boîte de dialogue permet aux utilisateurs d’insérer facilement des codes courts complexes dans le contenu.

En fait, ce n’est qu’un simple exemple. Nous pourrions donner aux utilisateurs plus de contrôle sur les codes courts WordPress, grâce à un bon nombre de champs de saisie et de contrôles qui sont listés dans le fichier Documentation TinyMCE.

Utilisations non conventionnelles des codes courts

WordPress n’admet les codes courts que dans le contenu des publications. Quoi qu’il en soit, en tant que développeurs d’extensions, nous pouvons dépasser cette limitation en filtrant tout contenu textuel n’importe où sur le site. Nous pouvons filtrer les widgets texte :

add_filter( 'widget_text', 'shortcode_unautop');
add_filter( 'widget_text', 'do_shortcode');

La première ligne applique la méthode shortcode_unautop au contenu des widgets texte afin d’empêcher WordPress d’envelopper automatiquement les codes courts dans les paragraphes. La deuxième ligne applique la méthode do_shortcode aux widgets texte.

Nous pouvons filtrer les extraits d’articles :

add_filter( 'the_excerpt', 'do_shortcode');

Et nous pouvons filtrer les descriptions des termes :

add_filter( 'term_description', 'do_shortcode' );

De la même manière, nous pouvons générer dynamiquement les titres des éléments du menu de navigation. Supposons que vous vouliez un élément de menu indiquant le nom d’utilisateur de l’utilisateur connecté. Tout d’abord, vous avez besoin d’un code court qui affiche le nom d’utilisateur :

function kinsta_shortcodes_init(){
	add_shortcode( 'kinsta_usr', 'kinsta_username' );
}
add_action('init', 'kinsta_shortcodes_init');

function kinsta_username( $atts = array() ){

	$id = get_current_user_id();
	
	if ( 0 == $id ) {
		// Not logged in
		return __( 'Guest' );
	} else {
		// Logged in
		$user = get_userdata( $id );
		return $user->user_login;
	}
}

Vous pouvez maintenant saisir « [kinsta_usr] » dans le contenu pour obtenir le nom d’utilisateur actuel. Pour utiliser ce code court dans les éléments de menu, nous devons filtrer la liste des éléments de menu à l’aide du filtre wp_nav_menu_objects :

function kinsta_dynamic_menu_items( $menu_items ) {

	global $shortcode_tags;

	foreach ( $menu_items as $menu_item ) {

		if ( has_shortcode( $menu_item->title, 'kinsta_usr' ) && isset( $shortcode_tags['kinsta_usr'] ) ){

			$menu_item->title = do_shortcode( $menu_item->title, '[kinsta_usr]' );

			if ( 0 == get_current_user_id() ){

				$menu_item->url = wp_login_url();
			
			}
		}
	}
	return $menu_items;
}
add_filter( 'wp_nav_menu_objects', 'kinsta_dynamic_menu_items' );

Tout d’abord, nous définissons la variable globale $shortcode_tags. Par la suite, nous vérifions deux conditions :

  • si un élément de menu contient le code court [kinsta_usr].
  • si le code court [kinsta_usr] existe

Si les deux conditions sont vraies, do_shortcode recherche « [kinsta_usr] » dans le titre d’un élément de menu et exécute le gestionnaire de codes courts. Pour les utilisateurs non connectés, nous changeons l’URL de l’élément de menu en wp_login_url(). Maintenant, allez dans l’écran Apparence > Menus et ajoutez un nouvel élément de menu au menu de navigation comme le montre l’image ci-dessous.

Menu item

Enregistrez le menu et visualisez le site.

Dynamic menu

Récapitulatif

Maintenant nous savons comment construire des codes courts WordPress, comment permettre aux utilisateurs de les ajouter n’importe où dans le site, et comment construire des dialogues TinyMCE pour configurer des codes courts complexes en quelques instants. Avez-vous déjà créé des codes courts personnalisés ? Faites-nous part de vos idées dans les commentaires ci-dessous.

25
Partages