La création d'un shortcode nécessite trois étapes. J'ai ajouté des couleurs qui sont reprises dans les exemples plus bas. Ceci permet de voir quelles lignes de code correspondent à chacune des étapes.
/**
* Définit un shortcode qui affiche un texte bidon pour fins de démonstration.
* @author Christiane Lagacé <christiane.lagace@hotmail.com>
*
* Utilisation : [monprefixemonshortcode]
* Suppositions critiques : le style .textespecial doit définir l'apparence du texte
*
* @return String Code html généré par le shortcode
*
*/
function monprefixe_monshortcode( ) {
$code_html = "<span class='textespecial'>Voici le texte qui sera affiché à la place du shortcode</span>";
return $code_html;
}
add_shortcode( 'monprefixemonshortcode', 'monprefixe_monshortcode' );
Pour utiliser ce shortcode, il faut inscrire à l'endroit désiré son nom entre crochets carrés, par exemple dans le texte d'une page.
Lorem ipsum [monprefixemonshortcode] dolor sit amet.
Supposons que la règle CSS suivante a été définie :
.textespecial {
background-color: #f5e6ab;
}
Résultat à l'écran :
Si le shortcode doit être utilisé dans plusieurs sites WordPress, la déclaration de la fonction de rappel ainsi que l'appel à add_shortcode() seront codées dans une extension.
Dans le cas où le shortcode est écrit spécifiquement pour un site, ils seront plutôt codés dans le fichier functions.php du thème enfant.
Puisque ce fichier peut devenir très gros, plusieurs programmeurs préfèrent créer des sous-fichiers et placer ce code dans un sous-fichier nommé shortcodes.php.
Attention : si vous développez un thème que vous souhaitez distribuer, les bonnes pratiques veulent que vous n'utilisiez pas les shortcodes dans le functions.php du thème.
Malheureusement, cette règle est souvent escamotée par les concepteurs de thèmes. Elle a pourtant une raison d'être simple : puisqu'un site WordPress peut changer de thème facilement et que les shortcodes sont, la plupart du temps, écrits directement dans la BD (ex : dans le texte d'une page ou d'un article), le fait de changer de thème empêcherait le bon fonctionnement des pages ou articles qui utilisent les shortcodes de l'ancien thème. Si, par contre, le shortcode est écrit dans une extension, le changement de thème n'affectera pas son bon fonctionnement.
Le nom du shortcode ainsi que le nom de sa fonction de rappel seront tous deux écrits en lettres minuscules. Ils seront également préfixés pour éviter tout conflit de nom avec les shortcodes et fonctions du thème ou des extensions utilisées.
Par contre :
C'est dans la fonction de rappel du shortcode qu'on retrouvera la logique pour générer le texte et les balises que le shortcode doit afficher.
La fonction de rappel ne doit rien afficher (pas de commande echo ni aucun texte ou balise qui ne soit pas entre <?php et ?>).
Plutôt, elle doit bâtir la chaîne de caractères HTML qui sera affichée lorsque le noyau WordPress rencontrera le shortcode. C'est cette chaîne qui sera retournée par la fonction de rappel.
Si jamais une fonction de rappel d'un shortcode faisait un echo, on pourrait avoir des problèmes d'affichage lorsque le shortcode n'est pas seul sur une page ou dans un article.
Par exemple, si une page contient ceci alors que le shortcode fait un echo :
Avant le shortcode
[monprefixemonshortcode]
Après le shortcode
la chaîne envoyée en echo (dans cet exemple : "Résultat du shortcode") apparaîtra avant tout le reste, même s'il y avait du texte avant l'appel du shortcode :
Résultat du shortcode
Avant le shortcode
Après le shortcode
Lorsqu'un shortcode est codé dans une extension, sa fonction de rappel sera une méthode codée dans une classe. À ce moment, le second paramètre de add_shortcode() devra être un tableau. Le premier élément du tableau sera $this, soit l'objet sur lequel on travaille, et le second, le nom de la méthode.
class Monprefixe_Mon_Extension {
public function __construct() {
add_shortcode( 'monprefixefairequelquechose', array( $this, 'faire_quelque_chose' ) );
...
}
public function faire_quelque_chose() {
...
}
}
Remarquez que dans cet exemple, le nom du shortcode débute par un préfixe pour le distinguer des autres shortcodes. La méthode de rappel, quant à elle, n'a pas besoin de débuter par un préfixe puisqu'elle est définie dans une classe, ce qui enlève le risque de conflit de nom avec d'autres fonctions.
« Shortcodes Should Never Be Included With Themes. Period. ». ThemeLab. http://www.themelab.com/put-shortcodes-in-a-plugin/
▼Publicité
