Le guide du débutant pour écrire votre propre shortcode personnalisé

Les shortcodes sont une fonctionnalité populaire incluse dans de nombreux plugins et thèmes. Cependant, si vous n’avez jamais construit vos propres shortcodes auparavant, vous n’avez peut-être aucune idée de la façon de les ajouter à vos propres projets WordPress.

Heureusement, l’API Shortcode de WordPress rend la création de vos propres shortcodes assez simple. En faisant cela, les utilisateurs pourront profiter des fonctionnalités de votre plugin ou de votre thème à partir de n’importe quelle zone de texte sur leur site WordPress. Inclure des shortcodes dans vos projets est un moyen facile de s’appuyer sur les fonctionnalités que vous avez déjà créées, de sorte que vous obtenez le meilleur rendement pour votre argent.

Dans cet article, nous parlerons un peu plus du fonctionnement des shortcodes. Puis, nous vous montrerons à quel point il peut être simple de programmer les vôtres en trois étapes. Commençons !

Une introduction aux shortcodes et à l’API Shortcode

L’API Shortcode de WordPress est un outil pratique pour les développeurs.

Les shortcodes ressemblent à de petits morceaux de texte entre crochets, comme ceci : . Chacun d’eux représente une exécution unique d’un code prédéfini, qui est déclenché à la demande. Vous pouvez les utiliser presque partout où du texte peut être ajouté dans WordPress.

Bien que la plupart des shortcodes soient ajoutés par des thèmes et des plugins, le noyau de WordPress dispose de quelques shortcodes par défaut que vous pouvez utiliser. Quelques exemples de ceux-ci sont audio, galerie, et légende.

Par exemple, lorsque vous ajoutez une image avec une légende, WordPress génère un shortcode particulier :

Lorsque vous visualisez ceci sur le front-end, vous verrez une image avec une légende :

Heureusement, l’API Shortcode rend relativement simple la création de shortcodes personnalisés pour vos propres projets WordPress. C’est souvent une idée intelligente car cela facilite la vie de vos utilisateurs en leur permettant d’utiliser des fonctionnalités complexes en quelques frappes.

Comment écrire votre propre shortcode personnalisé (en 3 étapes simples)

Maintenant que vous comprenez le fonctionnement des shortcodes, apprenons à en ajouter un à votre propre thème ou plugin ! Bien sûr, ce que fait votre shortcode dépendra de vous. Dans cet exemple, nous utiliserons une simple fonction « Hello world ! » pour vous aider à démarrer.

Écrire la fonction shortcode

D’abord, vous voudrez ouvrir un nouveau fichier dans un éditeur de texte. Ensuite, écrivez une fonction avec un nom unique, qui exécutera le code que vous aimeriez que le shortcode déclenche :

function torque_hello_world_shortcode() { return 'Hello world!';}

Si nous devions utiliser cette fonction normalement, elle renverrait Hello world ! sous la forme d’une chaîne qui pourrait être sortie en HTML. Cette fonction peut également prendre des paramètres personnalisés. Par exemple, si vous voulez que quelqu’un puisse lui faire dire Hello Bob ! à la place, vous pouvez ajouter un paramètre de nom. Ces paramètres sont appelés attributs, et ils sont tous gérés à l’aide d’un seul tableau prédéfini comme $atts par WordPress.

Voici un exemple de la façon d’utiliser la fonction $atts du shortcode pour gérer correctement les attributs du shortcode dans WordPress. Vous pouvez en apprendre davantage sur le fonctionnement de cette fonction pour vos propres besoins dans le codex de WordPress :

function torque_hello_world_shortcode( $atts ) { $a = shortcode_atts( array( 'name' => 'world' ), $atts ); return 'Hello ' . $a . !';}

Cette fonction attribue par défaut à l’attribut name la valeur world si aucun autre nom n’est disponible. Si un nom est fourni, la fonction l’affichera à la place. Voici un exemple d’exécution avec un shortcode:

// Outputs "Hello world!" // Outputs "Hello Bob!"

Une fois que vous avez terminé, cela peut être utilisé dans toutes les zones de texte sur un site WordPress où le plugin ou le thème qui contient ce shortcode est installé.

Enregistrer le fichier et l’ajouter à votre projet

Une fois que votre shortcode est prêt, vous pouvez créer un nouveau fichier dans votre thème ou plugin personnalisé pour enregistrer la fonction. Un nom descriptif vous aidera à retrouver ce fichier par la suite (par exemple : shortcode-function-hello-world.php).

Maintenant, il est temps d’informer le reste de votre projet de ce nouveau fichier. Si vous travaillez avec un thème, vous voudrez l’inclure dans le fichier functions.php. Si vous construisez un plugin, vous pouvez l’inclure dans tout fichier déjà chargé dans le projet.

Voici un exemple de la façon dont vous chargeriez le fichier dans un thème en utilisant get_stylesheet_directory(). Veillez à modifier le chemin d’accès à votre fichier pour qu’il corresponde à la structure des dossiers à l’intérieur de votre thème :

include( get_stylesheet_directory() . 'path/to/shortcode-function-hello-world.php' );

D’autre part, voici à quoi ressemble le chargement du fichier dans un plugin, en utilisant plugin_dir_url(). Encore une fois, modifiez le chemin d’accès à votre fichier pour qu’il corresponde à la structure des dossiers de votre plugin :

include( plugin_dir_url( __FILE__ ) . 'path/to/shortcode-function-hello-world.php' );

À ce stade, votre fonction est maintenant disponible pour être utilisée ! Tout ce qui reste à faire est d’enregistrer activement le shortcode au sein de WordPress.

Enregistrer le shortcode

La dernière étape consiste à enregistrer votre nouveau shortcode auprès de l’API Shortcode. Cela se fait avec la fonction add_shortcode. Elle requiert deux arguments :

  1. La balise de shortcode à utiliser dans l’éditeur de texte
  2. Le nom de la fonction gérant l’exécution du shortcode

Sous votre fonction de shortcode, incluez cette ligne de code et mettez-la à jour pour qu’elle corresponde à vos propres valeurs :

add_shortcode( 'helloworld', 'torque_hello_world_shortcode' );

La première valeur ira entre crochets dans l’éditeur de texte. La seconde correspondra au nom de la fonction que vous avez écrite dans les deux étapes précédentes. Les deux doivent être suffisamment uniques pour ne pas interférer avec les autres shortcodes inclus par le noyau de WordPress, les thèmes ou les plugins.

Une fois que vous avez terminé, il ne reste plus qu’à le tester. Connectez-vous à l’administration de WordPress et essayez d’ajouter votre shortcode à un article :

C’est tout ce qu’il y a à faire ! Votre shortcode peut être aussi compliqué ou simple que vous le souhaitez – ce que vous décidez de construire en utilisant ce pouvoir ne dépend que de vous ! Pour les situations avancées où vous aimeriez modifier la sortie pour différentes situations, il pourrait être intéressant d’écrire une classe PHP unique pour gérer votre nouveau shortcode.

Conclusion

Ajouter des fonctionnalités complexes aux articles et pages WordPress est facile avec les shortcodes. Ils sont simples à programmer et ajoutent de la valeur à votre projet existant en rendant le contenu simple dynamique.

Dans cet article, vous avez appris qu’il suffit de trois étapes simples pour créer un shortcode :

  1. Écrire une fonction régulière qui exécute le code personnalisé souhaité.
  2. Enregistrer le code dans votre plugin ou thème WordPress.
  3. Enregistrer le shortcode dans WordPress.

.

Laisser un commentaire