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)$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 :

Continuez votre lecture

3 commentaires

bloingo a dit le 8 avril 2008 à 12:23

bon, ben, chuis vraiment une truffe 3.0 en code, mais je trouve tout cela extrêmement intéressant et surtout très pédagogique; je m’accroche mais c’est passionnant, bravo et merci .. :)

RépondreRépondre
burningHat a dit le 8 avril 2008 à 13:13

Content que ça te plaise et n’hésite pas à poser tes questions si tu en as ;)

RépondreRépondre
jbj a dit le 11 avril 2008 à 12:54

Merci pour cet article fort interessant. Allez hop, dans les favoris :)

RépondreRépondre

5 trackbacks

WordPress 2.5 et les ShortCodes #1 - Présentation « burningHat - 17 avril 2008 à 17:51

[...] WordPress 2.5 et les ShortCodes #2 – les paramètres [...]

WordPress 2.5 et les ShortCodes #3 - contenu et imbrication « burningHat - 17 avril 2008 à 17:53

[...] 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 [...]

» Pour réparer éditeur visuel bloqué, casses un flux RSS ^_^ « css4design - 10 juin 2008 à 11:03

[...] Je ne vais pas vous faire patienter plus longtemps pour vous livrer le coupable qui se cachait dans une fonction qui servait à insérer une vidéo Youtube via un shortcode. J’avais pourtant déniché cette petite perle chez quelqu’un de confiance [...]

WordPress 2.5.x: les shortcodes - Emmanuel GEORJON - 14 juin 2008 à 8:11

[...] (fr) WordPress 2.5 et les ShortCodes #2: Les paramètres – BurningHat.net [...]

Emmanuel GEORJON - 26 juin 2008 à 22:43

WordPress 2.5.x: les shortcodes…

Les shortcode sont l’une des plus intéressantes nouveautés de WordPress 2.5. Ils standardisent la façon d’insérer ce que l’on veut dans les articles ou les pages. Ils ouvrent la voie à une très grande quantité d’applicati…