Créer un plugin de fonctionnalités (4) – créer des shortcodes

Nous avons créé un plugin vide dans l’étape 1 de cette série d’articles intitulée Créer un plugin de fonctionnalités puis ajouté progressivement des fonctionnalités. Nous allons maintenant la quatrième étape : créer un shortcode qui nous aidera à faire certaines mises en page spécifiques.

Principe d’un shortcode

Lorsque j’écris un article, ou le contenu d’une page, sous wordpress, j’ai parfois besoin de donner des instructions très précises pour la mise en forme. Supposons par exemple que je doives souvent rédiger un contenu qui doit s’inscrire dans un cadre orange, en police italique et 120% plus grosse que la police habituelle. A chaque fois, il faudrait que j’aille dans l’onglet ‘texte’ de WordPress et que je donne les instructions précises. En plus, il faudrait que j’espère que WordPress les accepte…

Il y a une solution beaucoup plus simple. Je crée un shortcode dont j’écris la fonction ailleurs. Par exemple (voir d’autres exemples ici), je peux créer un shortcode ‘link-to-post » avec le code suivant :

// Add Shortcode
function post_link_shortcode( $atts ) {

	// Attributes
	extract( shortcode_atts(
		array(
			'id' => '',
		), $atts )
	);

	// Code
if ( isset( $id ) ) {
	return '<a href="' . get_permalink( $id ) . '">' . get_the_title( $id ) . '</a>';
}

}
add_shortcode( 'link-to-post', 'post_link_shortcode' );

Ensuite, il me suffirait de taper [link-to-post id=”248”] pour que WordPress affiche automatiquement le lien vers cet article.

Que voulons-nous faire ?

Je veux apprendre à créer des shortcodes et en profiter pour faire plus facilement une mise en page assez complexe lorsqu’il faut la coder en html. De temps en temps, sur un autre site, j’ai besoin de placer du texte et une image correspondante en vis à vis, avec l’image à droite ou à gauche. Ce n’est pas la même chose que simplement placer une image et l’aligner à gauche ou à droite.

Comment crée-t-on un shortcode ?

Pour tout savoir, lire le Codex WordPress sur les API de shortcodes (en anglais) ou WordPress Shortcodes: A Complete Guide, ou encore Getting Started With WordPress Shortcodes.

En anglais aussi, mais contenant essentiellement du code : le shortcode generator de GenerateWP. L’exemple ci-dessus en provient.

Donc concrètement dans mon plugin, je vais créer le shortcode  ‘bloc’, qui pourra prendre 2 attributs :

1. align : qui dira si le texte doit être à gauche ou à droite de l’image ;
2. hr : qui indiquera si je veux que le bloc soit suivi d’un trait continu pour bien le séparer du suivant.

préparons le code nécessaire

Nous allons d’abord réaliser ce qui est commun à tous les shortcodes :

1. créer une fonction « callback » pour le shortcode
2. enregistrer le shortcode dans WordPress
3. demander à WordPress de charger les shortcodes (pas seulement celui-là) lors de son démarrage

Dans le fichier de mon plugin, j’insère le code suivant :

/********************************************************************************
* faire fonctionner un shortcode
********************************************************************************/ 
function ald_bloc_texte_image() {
// contenu à mettre ici
}

function register_shortcodes(){
add_shortcode('bloc', 'ald_bloc_texte_image');
}

// pour que le shortcode soit chargé au démarrage de wordpress
add_action( 'init', 'register_shortcodes');

Maintenant, si je tape [[bloc]texte[/bloc]] (entre doubles crochets pour être inopérant ici) –>     <–, je ne vois rien apparaître, ni « texte », ni les contenus entre crochets. C’et normal puisque ma fonction ne contient rien… Tout à l’heure, j’avais écrit [aaa]mon texte [/aaa] et il s’affiche avec les contenus entre crochets car WordPress n’a aucune information sur un shortcode ‘aaa’. J’ai donc la preuve que mon shortcode est opérationnel.

Maintenant il ne reste que le détail de lui faire faire quelque chose…

Précisons ce que je veux faire

Ce que je veux faire exactement :

Je veux écrire le paragraphe suivant de telle sorte qu’il se situe à gauche d’une image. C’est ce que je viens de faire ici, simplement en insérant une image et en demandant qu’elle soit alignée à droite. Mais je ne veux pas que le texte qui suit continue à se mettre à gauche de l’image.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.

Concrètement, je vais écrire [[bloc align= »gauche » hr= »oui »]] Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.

ecrire [[al-image]] et Mettre l’image, mais sans alignement (alignement aucun lors de l’incorporation du media, comme ici.

puis terminer par[ [/al-image]][ [/bloc]]

Et je veux que ça me donne ce qui suit (je l’ai intégré en tapant du html, et avant la fin de l’article, j’aurai modifié le css généré par ce plugin) :

Ceci est le titre du bloc créé en HTML !

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.

Alors quel code écrire dans ma fonction pour arriver à ça ?

Je ne vais pas expliquer ici comment j’ai codé la fonction. Sachez que  je me suis inspirée des articles cités en référence précédemment, et que j’en ai bavé !

Et voilà le résultat :

Ceci est le titre du bloc créé avec le shortcode !

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum. Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Curabitur sodales ligula in libero. Sed dignissim lacinia nunc.

et voici le code de la fonction

/********************************************************************************
* faire fonctionner un shortcode
********************************************************************************/ 

// shortcode to enclose an image between div tags

function ald_image( $atts, $content = null ) {
 $return_string = '</div><div class="image-holder">' ; 
 $return_string .= $content ; 
 return $return_string ;
 // this will return both text and image enclosed between the shortcodes
 // even if $content = '' instead of $content = null but NOT if $atts, is ommited...
}

// to enclose text and image in a specific div tag
function ald_bloc_texte_et_image( $atts, $content = null ) {
 // le shortcode 'image' pour lire le code HTML d'une image
 // See http://wordpress.stackexchange.com/questions/116012/using-html-as-shortcode-attribute
 
 extract( shortcode_atts(
 array(
 'align' => 'gauche', // default align value is gauche
 'hr' => 'oui', 
 ), $atts )
 );
 
 $class_text = 'ald-functions-gauche' ;
 if( $align == 'droite' ) {
 $class_text = "ald-functions-droite" ;
 } 

 $return_string = '<div class="'. $class_text . '"><div class="text-holder">' ;

 // should change $ald_hr coming from the image shortcode
 $ald_hr = '</div></div><hr />' ;
 if( $hr == 'non' ) {
 $ald_hr = '</div></div>' ;
 } 
 
 $return_string .= do_shortcode( $content ) . $ald_hr ; // allows nested shortcodes

 return $return_string ; // renvoie l'ensemble du texte généré
 
} 
 


function register_shortcodes(){
 add_shortcode('bloc', 'ald_bloc_texte_et_image');
 add_shortcode('al-image', 'ald_image');
}

// should change $ald_hr coming from the image shortcode
$ald_hr = '</div></div><hr />' ;
if( $hr == 'non' ) {
$ald_hr = '</div></div>' ;
} 

$return_string .= do_shortcode( $content ) . $ald_hr ; // allows nested shortcodes

return $return_string ; // renvoie l'ensemble du texte généré

}

et le css correspondant :

@charset "UTF-8";

/* 
css test du plugin ald-functions-knowledge

*/

/*****
* pour les shortcodes
*****/
.ald-functions-gauche, 
.ald-functions-droite {
color: green ; 
overflow: hidden;
width: 95%;
/* padding-right: 30px;
padding-left: 30px; */
}

.ald-functions-gauche > .image-holder,
.ald-functions-droite > .image-holder {
float: left;
width: 20%;
line-height: 200px; /* see http://www.vanseodesign.com/css/vertical-centering/ */
}

.ald-functions-droite > .text-holder {
float: right;
width: 75% ;
}

.ald-functions-droite > .image-holder {
float: left;
}

.ald-functions-gauche > .text-holder {
float: left;
width: 75% ;
}

.ald-functions-gauche > .image-holder {
float: right;
}

Ca y est, j’ai terminé cette partie du plugin !!!!

Vous pouvez voir le contenu complet de cette extension telle qu’elle est à la fin de cet article ici, sur github.

Conclusion :

Notre plugin nous permet donc de d’utiliser un shortcode pour mettre en forme du texte. Le prochain article de cette série Créer un plugin de fonctionnalités concernera l’internationalisation du plugin (rendre possible les traductions sans aller dans le code).