Utilisation de filtres personnalisés avec des codes courts

Une fois que vous avez compris l’ API Shortcode et le fonctionnement des filtres, il est facile de les implémenter dans WordPress.

Et lorsque vous êtes capable de mélanger les deux, vous pouvez faire beaucoup plus que d’habitude que lorsqu’ils fonctionnent indépendamment l’un de l’autre.

Plus précisément, vous pouvez filtrer les données qui se trouvent dans le résultat du shortcode, ce qui peut être particulièrement utile pour les autres développeurs. Si vous êtes habitué à implémenter des filtres personnalisés, le faire dans le contexte d’un code court n’est pas très différent.

Mais si vous n’avez jamais utilisé l’API de shortcode ou la fonctionnalité auparavant, c’est toujours facile à faire.

Filtres personnalisés avec shortcodes

Pour cet article, nous utiliserons un exemple relativement artificiel. Autrement dit, le shortcode se traduira par quelque chose de statique. La raison en est que cela facilite la démonstration dans un article et l’implémentation dans votre code.

Le code court

Pour implémenter un shortcode, vous avez besoin de deux choses :

1. un nom personnalisé pour le shortcode,
2. une fonction utilisée pour déposer des informations là où le shortcode est utilisé.

<?php

namespace Acme;

add_shortcode('a_simple_example', __NAMESPACE__. 'aSimpleExample');
/**
 * Replaces [a_simple_example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 */
function aSimpleExample()
{
  return 'This is the result of an example shortcode.';
}

Notez dans le code ci-dessus; J’ai préfixé la fonction avec. __NAMESPACE__En effet, la fonction réside dans un espace de noms personnalisé (que vous pouvez voir en haut du fichier).

Sans ce préfixe, la fonction ne sera pas appelée. Si vous choisissez de ne pas utiliser d’espaces de noms, vous pouvez renoncer à la fois au préfixe et aux barres obliques du nom de votre fonction.

Notez que nous reviendrons sur cette fonction dès que nous aurons le filtre en place.

Le filtre

L’ajout d’un filtre personnalisé est similaire à l’ajout d’un shortcode. Vous avez besoin:

1. un nom de filtre personnalisé,
2. une fonction qui sert à filtrer les informations entrantes (et les filtres doivent généralement accepter au moins un paramètre qui est, bien entendu, les données à filtrer) :

Pour rester cohérent avec l’exemple ci-dessus disons que nous voulons juste remplacer quelques mots dans le shortcode :

<?php

namespace Acme;

add_filter('custom_shortcode_example', __NAMESPACE__. 'aSimpleShortcodeFilter');
/**
 * Replaces [a simple example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 *
 * @param string $input the input to filter.
 *
 * @return string       the result of the filter running on the input
 */
function aSimpleShortcodeFilter(string $input): string
{
  return str_ireplace(
    'an example shortcode.',
    'a filtered shortcode',
    $input
  );
}

Cela remplacera le contenu de :

Ceci est le résultat d’un exemple de shortcode.

À:

Ceci est le résultat d’un shortcode filtré.

Mais nous devons encore lier les deux ensemble.

Revisiter le shortcode

Pour associer les deux fonctions ensemble, nous devons nous assurer que la fonction du shortcode applique le filtre à la valeur qu’elle renvoie.

Heureusement, sa mise en œuvre est simple d’ autant plus que nous avons tout ce dont nous avons besoin :

<?php

namespace Acme;

add_shortcode('a_simple_example', __NAMESPACE__. 'aSimpleExample');
/**
 * Replaces [a_simple_example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 */
function aSimpleExample()
{
  return apply_filters('custom_shortcode_example', 'This is the result of an example shortcode.');
}

Dans un exemple plus concret, je recommande toujours de vérifier que le résultat du paramètre n’est pas vide, qu’il contient la chaîne que je recherche, ou quelque chose de similaire.

Autrement dit, j’aime souvent ouvrir avec une clause de garde. Si le test échoue, je renvoie simplement la valeur entrante ; sinon, je filtrerai les données et renverrai quel que soit le résultat de cette opération.