Enclosing Shortcodes et attributs

Enclosing shortcodes

Nous avons vu précédemment un « self-closing shortcode »  [yoda].

L’API des shortcodes supporte également les « enclosing shortcode » comme par exemple [vador]Jean-Marc[/vador].

Comme leur nom l’indique, les enclosing shortcodes, vont entourer un contenu et ce dans le but de pouvoir le récupérer. Ainsi le shortcodes [vador]Jean-Marc[/vador] retournera :

Jean-Marc, Je suis ton père !

Comment récupérer le contenu

La fonction de rappel (callback) d’un shortcode peut récupérer trois paramètres :

  • $atts – tableau associatif contenant les attributs du shortcode ou une chaîne vide si aucun attribut passé
  • $content – le contenu encapsulé entre la balise d’ouverture et de fermeture
  • $tag – le nom du shortcode en cours, utile si on utilise la même fonction de rappel avec plusieurs shortcodes

Voici comment implémenter le shortcode [vador]...[/vador]

  1. /**
  2. * Shortcode qui retourne le célèbre "Luke, Je sui ton père !" dans un élément blockquote.
  3. * Le contenu du shortcode sera utilisé pour remplacer 'Luke'
  4. *
  5. * Exemples :
  6. * [vador] => <blockquote>Luke, Je sui ton père !</blockquote>
  7. * [vador]Serge[/vador] => <blockquote>Serge, Je sui ton père !</blockquote>
  8. */
  9.  
  10. function mon_plugin_vador_shortcode($atts, $content = "") {
  11. //Si contenu vide
  12. if (empty( $content )) {
  13. $content = 'Luke';
  14. }
  15. return "<blockquote>" . $content . ", Je suis ton père !</blockquote>";
  16. }
  17.  
  18. //Fonction de rappel qui retourne la célèbre citation de maître Yoda
  19. function mon_plugin_yoda_shortcode() {
  20. return "<blockquote>Que la force soit avec toi jeune padawan !</blockquote>";
  21. }
  22.  
  23. //Enregistre les shortcodes du plugin
  24. function mon_plugin_register_shortcode() {
  25. add_shortcode( 'yoda', 'mon_plugin_yoda_shortcode' );
  26. add_shortcode( 'vador', 'mon_plugin_vador_shortcode' );
  27. }
  28. add_action( 'init', 'mon_plugin_register_shortcode' );

Shortcodes avec attributs

Les shortcodes peuvent aussi avoir des paramètres de configurations appelés « attributs« .

Actuellement notre shortcode [vador] génère toujours une citation <blockquote>. Nous allons ajouter un paramètre $tag à ce shortcode pour que l’on aie le choix entre plusieurs éléments HTML.

  1. /**
  2. * Shortcode qui retourne le célèbre "Luke, Je sui ton père !" dans un élément blockquote.
  3. * Le contenu du shortcode sera utilisé pour remplacer 'Luke'
  4. * L'attribut tag du shortcode permet de remplacer l'élément blockquote par : p, h1, h2 ou div
  5. *
  6. * Exemples :
  7. * [vador] => <blockquote>Luke, Je sui ton père !</blockquote>
  8. * [vador]Serge[/vador] => <blockquote>Serge, Je sui ton père !</blockquote>
  9. * [vador tag="div"]Jean-Marc[/vador] => <div>Jean-Marc, Je sui ton père !</div>
  10. */
  11.  
  12. function mon_plugin_vador_shortcode($atts, $content = "") {
  13. // Tag par défaut
  14. $tag = 'blockquote';
  15. // Si $tag valide on le récupère
  16. if(isset($atts['tag']) AND in_array($atts['tag'], ['p','h1','h2','div'])) {
  17. $tag = $atts['tag'];
  18. }
  19. // Si contenu vide
  20. if (empty( $content )) {
  21. $content = 'Luke';
  22. }
  23.  
  24. return '<' . $tag . '>' . $content . ', Je suis ton père !' . '';
  25. }

Excécuter un shortcode en PHP

Il est parfois utile d’exécuter un shortcode en PHP, pour ce faire WordPress nous propose la fonction do_shortocde().

  1. echo do_shortcode('Exemple de shortcode : [yoda]');
  2. //Exemple de shotcode <blockquote>Que la force soit avec toi jeune padawan !</blockquote>

Cela peut être très utile si un shortcode a besoin d’intégrer un autre shortcode :

  1. //Fonction qui retourne le résultat d'un shortcode dans un élément strong
  2. function mon_plugin_strong_shortcode() {
  3.     return '<strong>' . do_shortcode( $content ) . '</strong>';
  4. }

Exercice

Afin de mettre en pratique vos connaissances vous pouvez essayer de réaliser l’exercice « shortcode ico ».