WordPress Shortcodes – Le guide complet – Partie 1

Les shortcodes WordPress ont été introduits dans la version 2.5, et depuis, ont montré qu’ils sont une des fonctionnalités les plus utiles. Un utilisateur ayant un rôle d’éditeur sur votre site pourra, avec les shortcodes, publier du contenu dynamique avec des macros, sans avoir besoin de notion de programmation (que ce soit HTML, CSS, Javascript…).

Cet article est fortement inspiré du guide publié par Smashing Magazine « WordPress Shortcodes: A complete guide« , qui a fait un travail énorme de documentation. J’essayerai de le compléter tant que je peux avec des notions qui me semblent importantes.

Mécanismes des shortcodes

Quand un shortcode est inséré dans un article ou une page de WordPress, il est remplacé par un autre contenu. En d’autres termes, on demande à WordPress de rechercher une macro qui se trouve entre des crochets droits ([]) et de le remplacer par le contenu dynamique approprié, produit par une fonction PHP.

Leur utilisation est très simple. Disons que nous souhaitons afficher les articles les plus récents dans un article donné. Nous pourrions utiliser ceci :

[recent-posts]

Pour une utilisation plus avancée de notre shortcode, nous pourrions définir un certain nombre d’articles à afficher en définissant un paramètre :

[recent-posts posts="5"]

Et pour aller encore plus loin, nous pouvons également définir un titre pour cette liste d’articles récents :

[recent-posts posts="5"]Posts Heading[/recent-posts]

Un shortcode simple

Dans la première partie du tutoriel, nous allons créer le code pour la version simple de notre shortcode, sans ses paramètres :

[recent-posts]

Le processus de création est simple et ne demande pas de notions avancées en PHP. Les étapes de bases sont :

  1. Créer une fonction qui sera appelée par WordPress lorsqu’il trouve un shortcode.
  2. Enregistrer le shortcode en lui donnant un nom unique.
  3. Lier la fonction d’enregistrement à une action WordPress.

Tout le code présent dans le tutoriel peut être placé dans le fichier functions.php ou dans un fichier PHP séparé qui sera inclut dans functions.php.

Création de la fonction de rappel

Lorsqu’un shortcode est trouvé, il est remplacé par un morceau de code, qui est la fonction de rappel (callback function). Créons donc un fonction qui récupère les articles récents dans la base de données.

function recent_posts_function() {
   query_posts(array('orderby' => 'date', 'order' => 'DESC' , 'showposts' => 1));
   if (have_posts()) :
      while (have_posts()) : the_post();
         $return_string = '<a href="'.get_permalink().'">'.get_the_title().'</a>';
      endwhile;
   endif;
   wp_reset_query();
   return $return_string;
}

Nous faisons donc une requête dans la base de données pour récupérer le dernier article et nous retournons une chaine de caractères associées à un lien. Il est important de noter que la fonction de rappel n’imprime rien, mais retourne une chaine de caractère.

Enregistrement du shortcode

Maintenant nous allons dire à WordPress que cette fonction est un shortcode :

function register_shortcodes(){
   add_shortcode('recent-posts', 'recent_posts_function');
}

Si un shortcode de [recent-posts] est trouvé dans le contenu d’un article, alors  recent_posts_function() est appelé automatiquement. Nous devons aussi nous assurer que le nom du shortcode est unique afin d’éviter de possibles conflits.

Branchement dans WordPress

Afin d’exécuter notre fonction register_shortcodes() , nous allons la lier à l’action d’initialisation de WordPress :

add_action( 'init', 'register_shortcodes');

Test du shortcode

Nous shortcode est prêt, et l’étape suivant est de tester qu’il fonctionne comme attendu. Créez un article (ou ouvrez-en un existant), et ajoutez la ligne suivante quelque part dans le contenu :

[recent-posts]

Publiez l’article et regardez le dans votre navigateur, vous devriez voir le lien du dernier article publié sur votre blog, comme dans ce screenshot :

shortcodes

Shortcode avancé

Paramètres du shortcode

Les shortcodes sont flexibles car ils nous permettent d’y ajouter des paramètres dans le but de les rendre plus fonctionnels. Disons que nous souhaitons afficher un certain nombre d’articles récents. Pour réaliser cela, nous avons besoin d’ajouter une option supplémentaire qui défini combien d’articles nous souhaitons afficher.

Nous devons utiliser 2 fonctions. La première est une fonction native de WordPress, shortcode_atts() , qui combine les attributs de shortcode des utilisateurs avec des attributs natifs et remplis ceux par défaut en cas de besoin. La seconde est la fonction PHP extract() , qui fait ce que son nom suggère, elle extrait les attributs du shortcode.

En attendant notre fonction de rappel, nous ajoutons un argument, qui est un tableau d’attributs dont nous aurons extrait le paramètre pour le nombre d’article. Ensuite nous faisons notre requête dans la BDD pour récupérer le nombre souhaité d’article, et nous créons une liste HTML afin de les afficher.

function recent_posts_function($atts){
   extract(shortcode_atts(array(
      'posts' => 1,
   ), $atts));

   $return_string = '<ul>';
   query_posts(array('orderby' => 'date', 'order' => 'DESC' , 'showposts' => $posts));
   if (have_posts()) :
      while (have_posts()) : the_post();
         $return_string .= '<li><a href="'.get_permalink().'">'.get_the_title().'</a></li>';
      endwhile;
   endif;
   $return_string .= '</ul>';

   wp_reset_query();
   return $return_string;
}

Si l’utilisateur ne donne pas de paramètre, 1 sera la valeur par défaut. De la même manière, nous pouvons ajouter plus d’attributs, permettant au shortcode d’accepter plus de paramètres. Grace à cette fonction avancée, nous pouvons maintenant définir le nombre d’articles à afficher :

[recent-posts posts="5"]

Si vous regarder l’article dans votre navigateur, vous devriez voir les liens des 5 articles les plus récents dans le contenu de votre article :

shortcodes02

Advanced shortcode

Contenu dans les shortcode

Nous pouvons encore améliorer notre shortcode en lui donnant la possibilité de passer du contenu comme argument, ce qui dans notre cas sera un titre pour la liste des articles récents. Afin de réaliser cela, nous utilisons un paramètre supplémentaire, $content, dans notre fonction de rappel et nous l’ajouterons en tant que titre h3 avant notre liste. La nouvelle fonction est la suivante :

function recent_posts_function($atts, $content = null) {
   extract(shortcode_atts(array(
      'posts' => 1,
   ), $atts));

   $return_string = '<h3>'.$content.'</h3>';
   $return_string .= '<ul>';
   query_posts(array('orderby' => 'date', 'order' => 'DESC' , 'showposts' => $posts));
   if (have_posts()) :
      while (have_posts()) : the_post();
         $return_string .= '<li><a href="'.get_permalink().'">'.get_the_title().'</a></li>';
      endwhile;
   endif;
   $return_string .= '</ul>';

   wp_reset_query();
   return $return_string;
}

Ce type de shortcode est équivalent à une balise HTML. Nous entourons le contenu par notre shortcode :

[recent-posts posts="5"]This is the list heading[/recent-posts]

Le résultat est le même que précédemment, sauf pour le nouveau titre pour notre liste d’articles :

shortcodes03

Des shortcodes n’importe où, n’importe quand !

Autoriser les shortcodes dans les widgets

Par défaut, les shortcodes sont ignorés dans les widgets de sidebar de WordPress. Essayez par exemple cela :

[recent-posts posts="5"]

Si vous tapez cela dans un widget, il ne s’affichera simplement pas, sauf pour le texte tapé.

Avec WordPress, nous pouvons facilement activer cette fonctionnalité avec une simple ligne de code. Pour pouvoir ajouter des shortcodes dans les widgets, placez cette liggne dans votre fichier :

add_filter('widget_text', 'do_shortcode');

Maintenant, sans avoir à changer quoi que ce soit, le shortcode est affiché correctement dans les widgets.

De la même manière, nous pouvons activer les shortcodes dans les commentaires :

add_filter( 'comment_text', 'do_shortcode' );

Et dans les excerpts :

add_filter( 'the_excerpt', 'do_shortcode');

Un bouton pour notre shortcode dans l’éditeur TinyMCE

Alors même que les shortcodes peuvent de grands services pour ajouter du contenu dynamique dans les articles ou les pages, ils peuvent vite rendre confu un utilisateur moyen, surtout lorsqu’ils sont compliqués à utiliser (beaucoup de paramètres, un long shortcode …). La plupart des utilisateurs ne sont pas familiés avec les syntaxes qui ressemblent au HTML, mais ont pourtant besoin de se souvenir du format exact de la balise du shortcode et de ses attributs pour pouvoir les utiliser, car une erreurs de typo pourrait produire des effets indésirables dans le rendu du shortcode.

Pour résoudre ça, nous pouvons ajouter un bouton à l’interface de l’éditeur TinyMCE, permettant à l’utilisateur d’utiliser un shortcode d’un simple clic. Il y a 2 étapes basiques pour réaliser ce bouton :

  1. Créer un fichier Javascript pour ce bouton.
  2. Enregistrer ce bouton et le fichier Javascript..

Fichier JavaScript pour le bouton

Le fichier Javascript est utilisé pour enregistrer le plugin TinyMCE via l’API de TinyMCE. Nous devons créer un fichier appelé recent-posts.js dans le répertoire js de notre thème (ou de notre plugin) et nous y mettons ces lignes de code :

(function() {
   tinymce.create('tinymce.plugins.recentposts', {
      init : function(ed, url) {
         ed.addButton('recentposts', {
            title : 'Recent posts',
            image : url+'/recentpostsbutton.png',
            onclick : function() {
               var posts = prompt("Number of posts", "1");
               var text = prompt("List Heading", "This is the heading text");

               if (text != null && text != ''){
                  if (posts != null && posts != '')
                     ed.execCommand('mceInsertContent', false, '[recent-posts posts="'+posts+'"]'+text+'[/recent-posts]');
                  else
                     ed.execCommand('mceInsertContent', false, '[recent-posts]'+text+'[/recent-posts]');
               }
               else{
                  if (posts != null && posts != '')
                     ed.execCommand('mceInsertContent', false, '[recent-posts posts="'+posts+'"]');
                  else
                     ed.execCommand('mceInsertContent', false, '[recent-posts]');
               }
            }
         });
      },
      createControl : function(n, cm) {
         return null;
      },
      getInfo : function() {
         return {
            longname : "Recent Posts",
            author : 'Mon nom',
            authorurl : 'http://www.kune.fr',
            infourl : 'http://www.kune.fr/a-propos',
            version : "1.0"
         };
      }
   });
   tinymce.PluginManager.add('recentposts', tinymce.plugins.recentposts);
})();

Comme montré plus haut, nous créons un nouveau plugin, appelant la méthode tinymce.create() , et nous y passons le nom du plugin et les attributs. La partie la plus importante de ce code est la fonction init() , où nous définissons un nom, une icône et un évènement pour le bouton en utilisant la fonction onclick().

Dans les 2 premières lignes de la fonction onclick() , on demande à l’utilisateur d’entrer les paramètres pour le nombre d’articles ainsi que le titre de liste de notre shortcode. Ensuite, en fonction des valeurs qui ont été entrées, le shortcode est généré et inséré dans l’éditeur.

Enfin, noter plugin TinyMCE est ajouté au PLuginManager en utilisant la fonction add() . Maintenant nous avons intégré avec succès le shortcode [recent-posts] dans notre thème WordPress.

Enregistrement du bouton et du plugin TinyMCE

Après avoir créé le fichier Javascript, nous devons l’enregistrer ainsi que le bouton pour notre shortcode. Nous créons donc 2 fonctions et nous les lions aux filtres WordPress correspondant.

La première fonction est nommée register_button() et elle mets le shortcode dans le tableau des boutons, ajoutant un séparateur entre le nouveau bouton et ceux existant :

function register_button( $buttons ) {
   array_push( $buttons, "|", "recentposts" );
   return $buttons;
}

La seconde fonction, add_plugin(), pointe vers le chemin et le nom de notre fichier javascript :

function add_plugin( $plugin_array ) {
   $plugin_array['recentposts'] = get_template_directory_uri() . '/js/recentposts.js';
   return $plugin_array;
}

L’étape suivante est d’ajouter un filtre avec les fonction précédentes. La fonction register_button() est liée au filtre mce_buttons , qui est exécuté quand l’éditeur charge les plugins, et add_plugin() est lié au filtre mce_external_plugins , qui est exécuté lorsque les buttons sont sur le point d’être chargés :

function my_recent_posts_button() {

   if ( ! current_user_can('edit_posts') && ! current_user_can('edit_pages') ) {
      return;
   }

   if ( get_user_option('rich_editing') == 'true' ) {
      add_filter( 'mce_external_plugins', 'add_plugin' );
      add_filter( 'mce_buttons', 'register_button' );
   }

}

La fonction précédente ne fait rien si l’utilisateur n’a pas les permissions pour éditer les articles ou les page ou si l’utilisateur n’est pas dans le mode éditeur visuel.

Finalement, nous ajoutons la fonction dans l’action init de WordPress qui est exécutée lorsqu’une page est chargée :

add_action('init', 'my_recent_posts_button');

Utilisation du bouton

Pour vérifier que le bouton de notre shortcode fonctionne correctement, créons un nouvel article, ou éditons le dernier créé. Un nouveau bouton, avec l’icône que nous avons défini précédement, devrait être ajouté à la droite des autres, sur la première ligne des boutons TinyMCE, comme dans ce screenshot :

shortcodes06

Lorsque l’on presse le bouton, une fenêtre de dialogue devrait apparaître nous demandant d’entrer le paramètre de notre shortcode pour le notre d’articles à afficher :

shortcodes07

Après avoir ajouté le nombre d’articles, une seconde fenêtre apparait pour nous demander de d’entrer le titre de notre liste :

shortcodes08

Si aucun paramètre n’est entré, notre shortcode sera affiché avec les valeurs par défaut.

Enfin, le shortcode doit apparaître dans l’éditeur :

shortcodes

Shortcode pour le texte sélectionné

Ces boutons sont très utiles lorsque l’on place des shortcodes sur du contenu qui n’existe pas. Cependant, si l’on souhaite entourer un texte déjà tapé par notre shortcode, voilà une fonction pratique à ajouter dans votre fichier javascript :

(function() {
   tinymce.create('tinymce.plugins.wrapmytext', {
      init : function(ed, url) {
        ed.addButton(wrapmytext', {
            title : 'Wrap me',
            image : '...',
            onClick : function(){
               ed.focus();
               ed.selection.setContent('[wrapme]' + ed.selection.getContent() + '[/wrapme]');

            }
        });
      } ....

À vous de créer et d’innover dans l’utilisation des shortcodes maintenant.
Dans une prochain article, la suite du guide avec des exemples concrets de shortcodes bien utiles.

Mat_

Au départ on sort avec un diplôme d’ingénieur de l’ESIL (devenu Polytech’Marseille) en Informatique, réseau et multimédia, spécialisé dans les Systèmes d’Informations et Services E-Business. En même temps on bosse, on développe, on apprend. Et maintenant on entreprend.Passionné de nouvelles technologies, et évangéliste de WordPress, j’aime découvrir, tester, rechercher.

Vous aimerez aussi...

8 réponses

  1. xavier dit :

    Merci pour cette aide.

    • Mathieu dit :

      Avec plaisir ! N’hésitez pas à proposer d’autres sujets ou à poser vos questions!

      • xavier dit :

        J’aimerai plus de POO avec WordPress, mais c’est peut-etre limite avec la conception de wp.
        Je trouve cela assez complique et chronophage de faire une fonction pas shortcode.

      • Mathieu dit :

        C’est aussi possible je pense. Mais il faut revoir la logique du code. Et pas vraiment de faire une fonction par shortcode, il est toujours possible d’utiliser une seule fonction, avec un paramètre qui représenterai un shortcode (bien que je trouve ça bien moins user friendly).

  1. 20 octobre 2013

    […] la partie précédente de notre guide complet sur les shortcodes wordpress, nous vous avons montré comment mettre en place des shortcodes dans vos thèmes WordPress. Du plus […]

  2. 23 octobre 2013

    […] Première partie du guide complet sur l'utilisation des shortcodes WordPress. Créer des shortcodes, ajoutez un bouton à l'éditeur visuel de WordPress.  […]

  3. 7 mars 2014

    […] WordPress Shortcodes – Le guide complet – Partie 1 – Kune.fr […]

  4. 14 mars 2014

    […] en plus de la description d’une catégorie, vous pouvez envisager de placer des shortcode pour mettre par exemple des sliders ou autres widgets que vous aimeriez voir uniquement sur […]

Suivez Kune.fr sur les réseaux sociaux !

Kune.fr est votre site de ressources web. Vous y trouverez de nombreux outils utiles pour le web.
Alors n'hésitez plus, aimez notre page !

  • Ressources Wordpress, tutoriels, plugins et thèmes
  • Ressources design, packs d'icônes, kits UI ...
Fermer cette popup
%d blogueurs aiment cette page :