Créer un shortcode avec des paramètres dans WordPress

Ça faisait longtemps que je n’avais pas écrit de tutoriel, alors je me lance. Aujourd’hui c’est de Shortcodes dont nous allons parler.
Partons du principe que vous savez déjà de quoi il s’agit (sinon c’est ici).

Pour ce tutoriel, nous allons prendre un exemple simple mais à mon avis très utile, il s’agit d’afficher les derniers postes d’un type de contenu donné dans n’importe quelle zone du site acceptant les shortcodes. Autant dire à peut près partout !

1. Créer le shortcode

function recent_post_list( $atts, $content = null ) {
	//le contenu du shortcode
}
add_shortcode( 'recent_list_shortcode','recent_post_list');

Nous aurons donc un simple shortcode qui sera : [recent_list_shortcode]

2. Ajouter les paramètres

Les paramètres du shortcode sont des éléments facultatifs ou obligatoires pour le personnaliser.
(Ici, je les ai rendu obligatoires pour faciliter la compréhension de l’exemple.)

function recent_post_list( $atts, $content = null ) {

	//récupère les paramètres
	$atts = shortcode_atts(
	array(
		'post_type' => 'post',
		'limit' => 'limit'
	), $atts);
	//transforme les paramètres en variables
	extract($atts);

	//le reste de la fonction
}
add_shortcode( 'recent_list_shortcode','recent_post_list');

Notre shortcode avec ces 2 paramètres ressemblera maintenant à ceci : [recent_list_shortcode post_type= »post » limit= »9″].

3. Créer la requête

Nous allons ici créer une requête WordPress standard. Le but étant d’afficher des postes d’un type donné et dans une quantité donnée.

function recent_post_list( $atts, $content = null ) {	

	//...

	//créer la requête
	$query =  array(
		'post_status' => 'publish',
		'post_type' => $post_type,
		'posts_per_page' => $limit,
		'orderby' => 'date',
		'order' => 'DESC',
	);
	$post = query_posts($query);

	//...
}
add_shortcode( 'recent_list_shortcode','recent_post_list');

Comme je le disais dans le point 2, les paramètres du shortcode qui nous sert ici d’exemple sont obligatoires. En effet, les variables $post_type et $limit sont obligatoires pour la requête présentée fonctionne. On aurait très bien leur attribuer une valeur par défaut lorsque non définies.

4. Mise en place du loop

Le loop est ce qui permet d’afficher des contenus tant qu’il y en à afficher…pas très clair tout ça. En gros, il s’agit d’une boucle qui dit : tant que je trouve un nouveau poste qui correspond à ma requête (cf point 3), je l’affiche.

function recent_post_list( $atts, $content = null ) {

	//...

	echo '<div id="recent-list">';

		while (have_posts()): the_post();
			echo '<div class="grid one-third">';
			//ici j'appel le même template qui me sert à afficher mes posts dans les pages d'archives par exemeple
			get_template_part('content');
			echo '</div>';
		endwhile;					

		wp_reset_query();

	echo '</div>';

	//...
}
add_shortcode( 'recent_list_shortcode','recent_post_list');

Notez l’ajout de wp_reset_query() qui peut éviter certains conflits lorsque vous avez d’autres loops qui suivent l’affichage de votre shortcode (ce qui a été mon cas). Cette fonction permet de réinitialiser les paramètres de la requête personnalisée.Notez l’ajout de ob_start() avant le loop et de return ob_get_clean();.

5. La fonction complète

function recent_post_list( $atts, $content = null ) {

	//récupère les paramètres
	$atts = shortcode_atts(
	array(
		'post_type' => 'post',
		'limit' => 'limit'
	), $atts);
	//transforme les paramètres en variables
	extract($atts);

	//créer la requête
	$query =  array(
		'post_status' => 'publish',
		'post_type' => $post_type,
		'posts_per_page' => $limit,
		'orderby' => 'date',
		'order' => 'DESC',
	);
	$post = query_posts($query);

	ob_start();

	$return .= '<div id="recent-list">';

		while (have_posts()): the_post();
			echo '<div class="grid one-third">';
			get_template_part('content');
			echo '</div>';
		endwhile;					

		wp_reset_query();

	echo '</div>';
	return ob_get_clean();
}
add_shortcode( 'recent_list_shortcode','recent_post_list');

Ces deux fonctions PHP « standard » permettent de ne pas afficher le contenu du echo mais de le stocker temporairement dans le tampon. On s’assure ainsi du bon affichage du contenu du shortcode.

6. Alternative via plugin

Pour les plus pressés ou ceux qui n’aiment pas mettre les mains dans le code, voici un plugin qui vous permet d’arriver à un résultat identique et qui offre de nombreux paramètres supplémentaires.

Un must have !