Insertions dans une page (shortcode)

Mise à jour le 14-06-2018 à 11:53

Présentation

Le « shortcode » est moyen simple pour que le rédacteur puisse insérer dans une page ou un article une partie qui n’est pas gérée par WordPress comme un diaporama ou l’affichage de liens RSS distants.

Nous prendrons ici comme exemple, l’affichage d’un élément HTML « iframe » dans la page.

Utilisation d’un shortcode

Avant de voir comment écrire le plugins, voyons son utilisation.

Le rédacteur insère dans une page une ligne ainsi constituée :

[nom_du_shortcode attributs]

Où « nom_du_shortcode » est le nom que le développeur à fixé pour l’utilisation de ce plugin (ce n’est pas nécessairement le nom du plugin).

Quant aux attributs, ils sont parfois facultatifs. S’il y en a, ils sont sous la forme :

attribut="valeur"

Il peut y en avoir plusieurs séparés par des espaces.

Le plugin

Pour notre exemple, il est très simple, donc constitué d’un seul fichier (à placer dans le répertoire des plugins).
Le voici en entier.

<?php
/*
Plugin Name: Iframe démonstation
Description: [iframe_demo src="http://site.com" {autres paramètres}] - Pour les paramètres voir : <a href='https://developer.mozilla.org/fr/docs/Web/HTML/Element/iframe' target='_blank'><iframe> - HTML (HyperText Markup Language) | MDN</a>
Version: 1.0.0
author: Jean-Michel
*/
defined( 'ABSPATH' ) OR exit;
function fct_iframe_demo( $atts ) {
  $defaults = array(
   'src' => '<?php echo $_SERVER["PHP_SELF"]; ?>',
   'style'=> '',
  );
  $atts= shortcode_atts( $defaults, $atts );

  $html = '<iframe';
  foreach( $atts as $att => $val ) {
    $html .= ' ' . esc_attr( $att ) . '="' . esc_attr( $val ) . '"';
  }
  $html .= '></iframe>'."\n";

  return $html;
}

add_shortcode( 'iframe_demo', 'fct_iframe_demo' );

 

Explications

Mise à par l’en-tête habituelle, commençons par la fin.

La fonction « add_shortcode » crée le shortcode, elle prend en premier paramètre le nom du shortcode que devra utiliser le rédacteur et en second le nom de la fonction qui gère le shortcode.

Il ne faut pas produire de sortie (avec « echo ») dans cette fonction car l’affichage ne se fera pas où on l’attend.

Cette fonction, ici « fct_iframe_demo » reçoit en paramètre le tableau des attributs qu’a utilisé le rédacteur, elle doit renvoyer sous forme de chaîne de caractère ce qui sera inséré à la place du shortcode.

Pour notre exemple la fonction, dans un premier temps, fait appel à la fonction WordPress « shortcode_atts », celle-ci reçoit en paramètre le tableau des attributs par défaut (« $defaults ») et celui des attributs reçus(« $atts »). Elle renvoie un tableau d’attributs « nettoyés » :

  • si un attribut est présent dans $defaults mais pas dans $atts, celui de $defaults est renvoyé ;
  • si un attribut est présent dans $defaults et dans $atts, celui de $atts est renvoyé ;
  • sinon (présent dans $atts mais absent de $default), il est ignoré.

Cela évite la transmission d’attributs non attendus qui peuvent être perturbateurs. En revanche, si l’on accepte de tels attributs, il ne faut pas utiliser cette fonction.

Dans notre exemple, on génère ensuite la chaîne que renverra notre fonction de shortcode, les fonctions « esc_attr » nettoient les valeurs transmises.

Remarque concernant le nom du shortcode et celui des attributs

Ces noms ne doivent comporter que des lettres minuscules (l’une des 26), des chiffres ou le souligné.

Exemple d’utilisation de l’exemple

Le rédacteur pourra écrire :

[iframe_demo src="https://unsite.com" style="width:100%;"]

Shortcode avec passage de contenu

Une autre possibilité est d’utiliser le shortcode sous la forme de deux balises : ouverture et fermeture, par exemple :

[mon_shortcode attribut= »attr »] quelque chose [/mon_shortcode]

Dans ce cas la fonction associée au shortcode recevra un second paramètre contenant ce qui est entre les deux balises.

Autre exemple

Nous voulons marquer certains passages de texte qui ne seront visibles que par les utilisateurs enregistrés et en fonction de leur rôle dans WordPress.

L’utilisation du shortcode pourrait être :

[cntres role="editor"] Voici un secret... [/cntres]

Le nom du shortcode est donc « cntres », seuls ce qui sont au moins éditeurs verront le secret. (on utilise ici pour « role » les noms internes de WordPress, donc en anglais).

Voici le code :

<?php
/*
Plugin Name: Contenu réservé
Description: N'affiche un contenu qu'aux utilisateurs disposant d'un certain rôle
Version: 1.0
Author: Jean-Michel
*/
defined( 'ABSPATH' ) or die( '' );

/* Gestion du short-code */
function contenu_reserve_shortcode($atts, $cnt) {
 /* Rôles d'origine : administrator, editor, author, contributor, subscriber */

 $this->tb_roles = array_keys(wp_roles()->role_names);
 $num_role_dem = ( isset($atts['role']) && ($r= array_search(trim($atts['role']), $tb_roles)) !== FALSE )
                   ? $r : count($tb_roles);
 
 $num_role_util= count($tb_roles);
 if (is_user_logged_in()) {
   $util= wp_get_current_user();
   foreach ($util->roles as $ut_role) {
     $nr = array_search($ut_role, $tb_roles);
     if ($nr < $num_role_util) $num_role_util = $nr;
   }
 }
 
 return $num_role_dem < $num_role_util ? '' : $cnt;
}
add_shortcode( 'cntres', 'contenu_reserve_shortcode' );

Explications

Pour ce qui est de la fonction de gestion du shortcode, on voit qu’elle reçoit un second paramètre « $cnt » qui contient ce est qui entre les balises.

La fonction WordPress « wp_roles() » ( https://developer.wordpress.org/reference/functions/wp_roles/ ) nous donne, par le champ « role_names » un tableau des rôles que WordPress gère (dans l’ordre des possibilités), les clefs de ce tableau sont les noms internes des rôles, on les range dans le tableau « $tb_roles ». Celui-ci sera donc un tableau indexé numériquement dans l’ordre des possibilités ( 0 => ‘administrator’, 1=>’editor’…).

La variable « $num_role_dem » contiendra l’index de ce tableau correspondant au rôle demandé depuis le shortcode ou au delà du tableau si celui-ci n’est pas reconnu.

Ensuite, on s’intéresse à l’internaute qui voit la page.

S’il est connecté, il est donné par la fonction « wp_get_current_user() » (https://codex.wordpress.org/Function_Reference/wp_get_current_user) qui nous renvoie un objet décrivant l’utilisateur, dont le champ « role » est un tableau des ses rôles dans le système. La boucle détermine son rôle le plus important (numéro le plus bas).

Sinon il a (par défaut) le numéro le plus haut.

Il suffit ensuite de comparer ce rôle utilisateur à celui demandé pour afficher le contenu ou pas.

En savoir plus :
https://codex.wordpress.org/Shortcode_API