Fonctions avancées · Leçon 15/20 · 15 min

Comprendre les actions et les filtres avec deux exemples simples

Comprendre les actions et les filtres avec deux exemples simples.

Durée indicative : 15 minutes.

Une action déclenche, un filtre transforme

WordPress propose des points d’accroche auxquels votre code peut se connecter.

Une action permet d’exécuter une fonction à un moment donné. Un filtre reçoit une valeur, permet de la modifier, puis doit retourner une valeur.

Retenez cette distinction :

MécanismeQuestion simple
Action« Que faut-il faire à ce moment-là ? »
Filtre« Quelle valeur faut-il renvoyer à la place de celle reçue ? »

Dans le module 2, vous avez utilisé l’action admin_notices pour afficher un rappel. Ici, nous allons utiliser l’action init pour déclarer un type de contenu.

Comprendre les types de contenu

WordPress possède déjà plusieurs types de contenu, notamment les articles et les pages.

Un type de contenu personnalisé ajoute une catégorie de contenus structurée séparément dans l’administration : « Ressources », « Réalisations » ou « Équipe », par exemple. Il ne crée pas à lui seul un annuaire complet, un moteur de recherche ou une mise en page sur mesure.

Avant d’en créer un, posez-vous cette question :

Mes contenus ont-ils réellement besoin d’une gestion différente, ou une catégorie d’articles suffit-elle ?

Fonction concrète 1 : créer un espace « Ressources »

Créez un snippet nommé :

T1PP | Type de contenu Ressources

Ajoutez ce code :

// Déclare un type de contenu indépendant du thème.
function t1pp_declarer_ressources() {
    register_post_type(
        't1pp_ressource',
        array(
            'labels' => array(
                'name'          => 'Ressources',
                'singular_name' => 'Ressource',
            ),
            'public'       => true,
            'show_in_rest' => true,
            'has_archive'  => false,
            'rewrite'      => false,
            'supports'     => array(
                'title',
                'editor',
                'custom-fields',
            ),
        )
    );
}

add_action( 'init', 't1pp_declarer_ressources' );

Lire les choix importants

  • t1pp_ressource est l’identifiant technique du type de contenu.
  • public permet son utilisation publique.
  • show_in_rest, associé au support de l’éditeur, permet son utilisation dans l’éditeur de blocs.
  • custom-fields autorise la prise en charge des champs personnalisés natifs.
  • has_archive désactive la création d’une archive dédiée.
  • rewrite désactive ici les règles d’URL réécrites propres à ce type.

Ce dernier choix limite les manipulations pour l’atelier. Nous ne construisons pas encore une architecture d’URL destinée à un site public.

Ne changez pas l’identifiant technique après avoir créé vos contenus sans prévoir une migration.

Tester la création

  1. Activez le snippet en exécution générale.
  2. Rechargez l’administration.
  3. Vérifiez qu’un menu « Ressources » apparaît.
  4. Ajoutez une ressource intitulée « Préparer une modification ».
  5. Ajoutez quelques lignes de contenu.
  6. Enregistrez d’abord un brouillon, puis testez l’aperçu.

Si vous publiez une ressource pour vérifier son URL, faites-le uniquement sur votre environnement de test.

L’affichage dépendra du thème. Un nouveau type de contenu ne garantit pas une présentation adaptée : un modèle spécifique peut devenir nécessaire.

Éditeur de blocs d’une ressource intitulée « Fiche démo : checklist de sauvegarde (fictive) » ; dans le menu latéral, l’entrée « Ressources » ouverte avec les sous-entrées « Ressources » et « Ajouter un article ».
Menu « Ressources » ajouté par le snippet et écran de création d’une ressource. Sous ce menu, WordPress affiche « Ajouter un article » : le code de la leçon ne définit que les libellés name et singular_name, et WordPress reprend pour les autres libellés ses valeurs par défaut, celles des articles. Pour un libellé adapté, il faudrait déclarer des libellés supplémentaires ; ce n’est pas nécessaire pour l’exercice.

Pourquoi ne pas mettre ce code dans le thème ?

Vos ressources doivent rester gérables même si vous changez de thème. La déclaration d’un type de contenu appartient donc plutôt à une extension ou, pour cet atelier, à votre extension de snippets.

La documentation WordPress précise qu’un type déclaré dans le thème disparaît de l’administration lorsque ce thème n’est plus utilisé.

Attention : désactiver notre snippet retire également sa déclaration. Les contenus ne sont pas supprimés par ce code, mais ils ne sont plus accessibles normalement par ce type tant qu’il n’est pas redéclaré.

Un exemple de filtre, sans nouveau snippet

Mécanicien au travail sur un moteur
Mécanicien au travail sur un moteur. Photo : Shixart1985, CC BY 2.0, via Wikimedia Commons.

Dans la leçon suivante, notre shortcode utilisera shortcode_atts() pour définir des valeurs par défaut.

Lorsque son troisième argument est fourni, WordPress propose un filtre nommé shortcode_atts_nom_du_shortcode. Une fonction reliée à ce filtre peut recevoir le tableau d’attributs, le modifier et le retourner.

Le raisonnement est différent de celui de notre action :

Action :
WordPress atteint init
→ notre fonction déclare Ressources.

Filtre :
WordPress prépare une valeur
→ une fonction la modifie
→ elle retourne la valeur à utiliser.

Nous n’ajoutons pas de filtre supplémentaire dans l’atelier : il n’est pas nécessaire pour répondre au besoin.

À vous de jouer

Expliquez avec vos mots :

  • pourquoi nous utilisons une action ;
  • pourquoi le snippet n’est pas limité à l’administration ;
  • ce qui se passe si vous le désactivez.

À retenir

Une action ajoute un comportement à un moment donné ; un filtre modifie une valeur avant son usage.

Toutes les formations

Formations connexes

Nos autres formations

Toutes les formations