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