Ceci est le dernier article de ma suite sur les shortcode dans WordPress 2.5. Nous avons vu précédemment ce qu’était un shortcode et comment lui passer des paramètres. Dans cet article, nous allons voir comment les utiliser pour mettre en forme du contenu et les imbriquer entre eux.

Imaginons que nous souhaiterions utiliser deux styles spécifiques dans nos articles :

• un premier qui permet d’insérer un encart aligner à gauche ou droite de notre page pour y insérer des données complémentaires au contenu, un peu à la façon des encarts dans les journaux. Nous appellerons ce style encart
• un second pour mettre en évidence un contenu. Nous l’appellerons warning.

Dans le fichier style.css de notre thème, nous allons créer les règles pour ces deux classes :

.encart{
	width: 150px;
	border: 1px solid black;
	margin: 5px;
}

.warning{
	background: #ffb49d;
	font-weight: bold;
}

Dans notre fichier functions.php, nous allons créer une première fonction pour le shortcode de nos encarts. La fonction devra prendre pour paramètre le type d’alignement souhaité (gauche ou droite) et récupérer le contenu situé entre les balises du shortcode pour le mettre en forme. Soit la fonction suivante :

// [encart align=left|right]
function encart_func($atts, $content = null){

    // s’il n’y a pas de contenu, on s’arrête là…
    if (is_null($content))
    return false;

    // on extrait les paramètres pour savoir si on aligne le bloc à droite ou à gauche. Par défaut, à gauche
    extract(shortcode_atts(array(’align’ => ‘left’), $atts));

    if ( ‘left’ == $align ){
        $class = “alignleft”;
    } elseif ( ‘right’ == $align ) {
        $class = “alignright”;
    }

    // on crée notre encart
    $output = ‘<div class=”encart ‘. $class .’”>’ . $content . “</div>\n”;

    // on affiche le tout
    return $output;
}
add_shortcode(’encart’, ‘encart_func’);

C’est le second paramètre de notre fonction, $content qui va permettre de récupérer le contenu compris entre les balises du shortcode. Il est initialisé avec une valeur null par défaut ce qui permettra d’exécuter la fonction quand même (si besoin est) en l’absence de contenu et/ou de tester ceci à l’aide de is_null($content) et de déterminer un comportement approprié. Dans mon cas, sans contenu, j’arrête la fonction car elle n’aurait plus aucun sens (créer un div vide ne me servirait à rien).

Le paramètre $align permettra quand à lui d’ajouter la classe alignleft ou alignright qui fera “flotter” le contenu du côté désiré dans notre article.

Pour insérer un encart dans nos billets, il suffira désormais d’écrire [encart align="right"]Ceci est un petit encart de test… Qu’en pensez-vous ?[/encart]. Ci-dessous, un exemple du résultat obtenu :

Nous allons maintenant faire sensiblement pareil pour le shortcode warning :

// [warning]$content[/warning]
function warning_func($atts, $content = null){
    if ( is_null($content) )
    return false;

    $output = ‘<div class=”warning”>’. $content .”</div>\n”;
    return $output;
}
add_shortcode(’warning’, ‘warning_func’);

Voilà, nos deux shortcodes sont opérationnels. Maintenant, il se pourrait très bien que nous souhaitions mettre du contenu de type “warning” dans un encart ! Cependant, si on tente d’écrire dans un billet le code [encart align="right"][warning]ceci est un encart auquel il faut prêter attention ![/warning][/encart], nous risquons d’être surpris. En effet, seul le shortcode [encart] sera correctement interprété et pas le warning. Le résultat ne correspondra donc pas à notre attente.

Pour imbriquer des shortcodes, nous devons explicitement autoriser les “parents” à exécuter les shortcodes qui pourraient leur être imbriqués à l’aide de la fonction do_shortcode(). Nous allons donc modifier la fonction encart_func() pour que son contenu puisse avoir des shortcodes. Changeons la ligne $output = ... ainsi :

$output = '<div class="encart '. $class .'">' . do_shortcode($content) . "</div>\n";

Cette simple modification nous permettra d’obtenir le résultat attendu : [encart] peut contenir des [warning] (mais pas l’inverse !).

Il existe toutefois une limitation à cette technique ! Il est en effet impossible d’imbriqué des shortcodes du même nom actuellement, ainsi [encart][encart]mon test[/encart][/encart] par exemple ne fonctionnera pas correctement !

Voilà, nous avons terminé notre tour d’horizon des shortcodes dans WordPress 2.5. Il reste bien sûr quelques fonctionnalités à découvrir (je vous renvoie à la documentation officielle pour ça) mais nous avons déjà de quoi bien nous amuser avec ça ! N’hésitez pas à tester et à me faire part de vos remarques, questions ou commentaires…

articles précédents sur les shortcodes :

• WordPress 2.5 et les ShortCodes #1 - Présentation
• WordPress 2.5 et les ShortCodes #2 - les paramètres

Il y a quelques jours, je vous présentais brièvement les shortcodes de WordPress 2.5. Nous allons aujourd’hui voir comment passer des paramètres à nos shortcodes et afficher correctement le retour dans nos billets.

Imaginons à nouveau une fonctionnalité totalement inutile en soit à titre d’exemple : un shortcode pour insérer rapidement et “proprement” une vidéo issue de Youtube dans nos billets ! Pour que ce code soit ré-utilisable, nous devrons pouvoir passer en paramètre de notre shortcode l’identifiant de la vidéo à afficher.

À titre d’exemple (et contribuer à la bonne cause), je vais utiliser la vidéo du 118 project dont j’avais déjà parlé et dont l’identifiant sur Youtube est gcHsyatfDhc (vous pouvez trouver ce code dans l’URL des vidéos).

Nous allons donc ré-ouvrir le fichier functions.php de notre thème et y insérer le code suivant :

// Ce code est indicatif et non-optimisé pour être utilisé tel quel en production !
// [youtube vid="vid_code"]
function youtube_func($atts){
    extract(shortcode_atts(array(’vid’ => ”), $atts));

    if ( ” == $vid ){
        return “<span class=\”error\”>Vous n’avez pas donné de lien valide !</span>\n”;
    } else {
        return ‘<object type=”application/x-shockwave-flash” width=”425″ height=”350″ data=”http://www.youtube.com/v/’ . $vid . ‘&hl=en”><param name=”movie” value=”http://www.youtube.com/v/’ . $vid . ‘” /></object>’;
    }
}
add_shortcode(’youtube’, ‘youtube_func’);

C’est tout ! Désormais pour insérer une vidéo issue de Youtube dans nos billets, il suffira d’insérer le shortcode [youtube] avec l’identifiant de la vidéo en paramètre. Par exemple : [youtube vid="gcHsyatfDhc"].

Alors détaillons un peu cet extrait de code car il mérite quelques éclaircissements. Vous remarquerez tout d’abord qu’on ne va pas passer à notre fonction youtube_func notre attribut vid directement mais un tableau $atts d’où sera extrait notre attribut par la suite. En fait, les fonctions définissant un shortcode n’acceptent que deux arguments précis : $atts qui sera un tableau contenant tous les attributs que l’on veut passer à notre fonction et $content qui servira à stocker le contenu situé dans le shortcode (nous verrons cela dans un prochain article ;)).

Pour extraire notre attribut, nous allons donc utiliser la fonction extract() (chose à laquelle on est habitué si on a déjà codé des widgets par exemple) et la fonction shortcode_atts(). shortcode_atts() sert à définir les valeurs par défaut des attributs (dans mon cas, j’ai défini $vid comme étant vide par défaut) et de nettoyer les attributs non-reconnus ou non-prévus par la fonction. Elle a donc deux attributs obligatoires et se présente sous la forme shortcode_atts($default_array, $atts) où $default_array est le tableau associatif contenant les noms des attributs attendus et leur valeur respective par défaut et $atts représente le tableau passé à notre fonction.

Afin de bien mesurer l’impact de ce système, imaginons la fonction suivante :

// [testAttributes]
function testAttributes_func($atts){
    extract(shortcode_atts(array(
        ‘title’ => ‘default_title’,
        ‘att1′ => ‘mon attribut’
    ), $atts));

    return $title . ‘ ‘ . $att1;
}
add_shortcode(’testAttributes’, ‘testAttributes_func’);

Et appelons-le dans un billet en mettant ceci [testAttributes att1="c'est excellent !" att2="cet attribut sera supprimé"]. Si vous publiez cet billet, vous verrez que le titre aura été inséré avec sa valeur par défaut puisque non défini dans l’appel, l’attribut att1 sera affiché comme attendu et l’attribut att2 aura été “nettoyé” car il n’était pas prévu par la fonction. Tout fonctionne donc comme prévu !

Pour terminer, vous aurez remarquez que j’utilise des return et non des echo dans cet article pour le rendu à afficher par les shortcodes. Si vous utilisez echo pour les sorties de vos shortcodes, attendez-vous à des surprises ! En effet, comme les shortcodes sont parsés par WordPress 2.5 au début de l’exécution de la boucle, tout ce qui sera en “echo” sera injecté au début du billet et ce quelque soit l’endroit où vous avez insérer votre shortcode dans l’article. Pensez donc à toujours bien utiliser return pour vos codes de sorties…

Voilà, c’est tout pour cette seconde partie sur les shortcodes dans WordPress 2.5.

autres articles sur les shortcodes :

• WordPress 2.5 et les ShortCodes #1 - Présentation
• WordPress 2.5 et les ShortCodes #3 - contenu et imbrication