Personnaliser le bloc Requête (Query) GenerateBlocks avec ACF et aller plus loin

Le bloc Requête (Query) de GeneratePress permet d’afficher des contenus dynamiques, dans WordPress sans écrire une ligne de code. C’est un outil puissant, que vous pourrez personnaliser si vous avez des besoins plus avancés.

Si vous utilisez ACF, vous aurez peut-être besoin de filtrer des publications selon la valeur d’un champ personnalisé. Et il est évidemment possible d’étendre les possibilités du bloc Query avec un peu de code personnalisé, pour des boucles vraiment sur mesure.

Le bloc Query (Requête) de GenerateBlocks

Le bloc Query proposé par GenerateBlocks (l’extension de blocs associée à GeneratePress) permet d’afficher automatiquement une liste de publications, une « boucle » (loop), en fonction de critères choisis : articles récents, types de contenus personnalisés, taxonomies, auteur, etc.

Directement dans l’éditeur, vous pouvez configurer :

• Le (ou les) type de contenu à afficher (articles, pages, CPT…) ;
• Le nombre d’éléments, l’ordre d’affichage et la pagination ;
• Des filtres de taxonomie (inclure et exclure, parents et enfants, par terme…) ;
• Des conditions dynamiques simples (publications spécifiques, par état, recherche par mot-clé…).

Le tout par l’interface visuelle du bloc WordPress, sans besoin de code. Chaque publication affichée utilise un bloc « Élément de boucle » (Loop Item) que vous pouvez personnaliser pour définir l’apparence de chaque élément de la liste.

C’est très pratique, rapide à mettre en place, et qui couvre la majorité des cas standards. Mais dès que vous avez besoin de filtrer selon des champs personnalisés (ACF) ou de gérer des affichages conditionnels plus poussés, il faut aller plus loin…

Et en version Pro vous pouvez afficher les valeurs d’un champ (Post Meta) en tableau pour une publication, dont la publication courante (pratique si vous créer un modèle de page), ou les valeurs d’une page d’options.

Mais qu’en est-il si vous souhaitez afficher uniquement les publications dont un champ ACF a une certaine valeur ? Par exemple, les publications dont un champ est coché, ou un nombre minimum, une option spécifique. C’est possible, en modifiant la requête du bloc Query. Voyons ça.

Exemple de filtre de publications d’une requête (loop) avec un champ Relation ACF

Le bloc Query ne propose pas nativement de filtrer les publications en fonction de la valeur d’un champ ACF. Heureusement, nous pouvons utiliser un filtre WordPress pour le faire.

L’idée est simple : on utilise un hook, generateblocks_query_loop_args, pour modifier dynamiquement les arguments de la requête générée par le bloc Query. Ce hook nous permet d’ajouter des conditions personnalisées, comme on le ferait avec WP_Query.

Dans cet exemple on cible un bloc Requête (Query) spécifique grâce à une classe CSS ajoutée dans l’éditeur de WordPress :

Cela permet de n’appliquer la logique qu’à certains blocs Query sans impacter les autres.

On récupère ensuite la valeur d’un champ ACF, ici un champ Relation qui contient une liste d’IDs de publications, puis on ajuste la requête pour afficher uniquement ces publications.

Pour retrouver le nom de votre champ ACF, allez dans ACF > Groupes de champs, cliquez sur le groupe où il se trouve puis sur l’icône visible au survol de son nom dans la colonne Nom :

Ce modèle peut bien sûr être adapté à d’autres types de champs ACF (valeur booléenne, champ texte, case à cocher, nombre, date, etc.) en ajustant la requête selon le besoin.

Dans votre fichiers functions.php, vous ajouterez le code suivant :

// Personnaliser une Requête (Query) GenerateBlocks avec un champ Relation ACF 
 
add_filter( 'generateblocks_query_loop_args', function( $query_args, $attributes ) {
    $relation = 'nom_champ_acf';
    $elementClass = 'isg-loop-acf--nom_champ_acf';
    if (
        ! empty( $attributes['className'] ) &&
        strpos( $attributes['className'], $elementClass) !== false &&
        ! is_admin()
    ) {
        // get the relate post ID
        $queried_object = get_queried_object () ;
        $relationship = get_field( $relation, $queried_object );
        // Merge the current $query_args with the new args
        return array_merge( $query_args, array(
            'post__in' => $relationship,
        ) );
    }

    return $query_args;
}, 10, 2 );
Langage du code : PHP (php)

Et vous remplacerez les informations des lignes 4 et 5 ci-dessus par vos propres données, ici :

$relation = 'mon_champ_relation_acf'; // Nom de votre champ ACF
$elementClass = 'ma-classe-css'; // votre classe CSSLangage du code : PHP (php)

Si votre champ ACF est présent sur une page d’options ACF, remplacez la ligne suivante :

$relationship = get_field( $relation, $queried_object );Langage du code : PHP (php)

Par celle-ci :

$relationship = get_field( $relation, 'option' );Langage du code : PHP (php)

Créer un filtre dynamique avancé basé sur des classes CSS pour vos requêtes (query)

Mais créer un filtre ACF spécifique pour chaque bloc Query peut vite devenir laborieux, surtout quand les cas d’usage se multiplient.

Pour éviter d’écrire une fonction dédiée à chaque fois j’ai pensé à générer dynamiquement les paramètres de la requête à partir des classes CSS du bloc.

C’est ce que permet le code ci-dessous. Il lit les classes ajoutées manuellement dans l’éditeur de blocs pour extraire automatiquement les informations nécessaires à la requête.

// Requête (Query) GenerateBlocks avec informations dynamiques (ACF et paramètres)

add_filter( 'generateblocks_query_loop_args', function( $query_args, $attributes ) {
    if ( is_admin() || empty( $attributes['className'] ) ) {
        return $query_args;
    }

    $class_string = $attributes['className'];

    // Extraire la clé ACF de la classe CSS
    if ( ! preg_match('/isg-loop-acf--([a-zA-Z0-9_\-]+)/', $class_string, $acf_match) ) {
        return $query_args;
    }

    $acf_key = $acf_match[1];

    // Extraire la valeur de comparaison (classe CSS)
    if ( ! preg_match('/isg-acf-valeur--([a-zA-Z0-9_\-]+)/', $class_string, $val_match) ) {
        return $query_args;
    }

    $acf_value = $val_match[1];

    // Valeurs par défaut (=)
    $map_compare = [
        'egal'   => '=',
        'diff'   => '!=',
        'sup'    => '>',
        'inf'    => '<',
        'supeq'  => '>=',
        'infeq'  => '<=',
    ];
    $compare = '=';
    $type    = 'CHAR';

    // Détection de paramètres personnalisés : isg-loop-arg--compare--xxx, etc.
    preg_match_all('/isg-loop-arg--([a-zA-Z0-9_\-]+)--([a-zA-Z0-9_\-\.]+)/', $class_string, $arg_matches, PREG_SET_ORDER);
    foreach ( $arg_matches as $match ) {
        $param = strtolower( $match[1] );
        $value = $match[2];
        if ( $param === 'compare' ) {
            $compare = $map_compare[$value] ?? '=';
        }
        elseif ( $param === 'type' ) {
            $type = $value;
        }
    }

    // Insérer le type de publications (post type) concerné
    if ( preg_match('/isg-loop-pt--([a-zA-Z0-9_\-]+)/', $class_string, $pt_match) ) {
        $query_args['post_type'] = $pt_match[1];
    } else {
        $query_args['post_type'] = 'product'; // ou 'post' ou ce que tu veux comme valeur par défaut
    }

    $query_args['meta_query'] = [
        [
            'key'     => $acf_key,
            'value'   => $acf_value,
            'compare' => $compare,
            'type'    => $type,
        ],
        [
            'key'     => $acf_key,
            'compare' => 'EXISTS',
        ],
        [
            'key'     => $acf_key,
            'value'   => '',
            'compare' => '!=',
        ]
    ];

    return $query_args;
}, 10, 2 );
Langage du code : PHP (php)

Classes CSS des blocs Query

Vous n’aurez qu’à ajouter les classes CSS suivantes à vos blocs Query; en remplaçant les parties entre crochets par les valeurs souhaitées.

Le code se chargera de récupérer automatiquement ces valeurs qui figureront directement après le double tiret (–) :

Champ ACF et valeur

• isg-loop-acf--[nom_champ_acf] : définit le champ ACF ciblé.
• isg-acf-valeur--[valeur] : définit la valeur recherchée pour le champ ACF.

Données de la requête

Et d’autres classes optionnelles (pour lesquelles une valeur par défaut est définie si elles ne sont pas renseignées) :

• isg-loop-arg--compare--[valeur] : comparaison (par défaut : = )
• isg-loop-arg--type--[valeur] : type de données (par défaut : CHAR)

Valeurs possibles des paramètres :

* Voir l’encadré rouge suivant concernant ces premiers termes.

Voir aussi : https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters

Par exemple :

• isg-loop-arg--compare--LIKE : pour une valeur différente de…
• isg-loop-arg--type--NUMERIC : pour rechercher une valeur numérique.

isg-loop-arg--compare--supeq

'compare' => '>='

isg-loop-arg--compare-->=

Type de publication (post type)

• isg-loop-pt--[type-de-post] : indique le type de publication concerné (post, product, etc.) avec une valeur par défaut si non renseigne (ici ‘product’ dans notre exemple à la ligne 53).

Le code lit ces classes, les interprète, puis modifie les meta_query du bloc Query en conséquence. Il ajoute aussi des protections supplémentaires pour éviter les cas où le champ n’existe pas, est vide ou non défini.

Cette méthode a deux avantages majeurs :

1. Elle permet de réutiliser ce seul filtre pour de nombreux blocs.
2. Elle rend le paramétrage possible dans l’interface de l’éditeur WordPress, sans toucher au code une fois la fonction en place.

C’est un excellent compromis entre souplesse, maintenabilité et performance. Elle ouvre la voie à des boucles vraiment dynamiques, tout en gardant le contrôle dans l’éditeur.

Donc si comme moi vous en avez marre de créer des filtres à gogo, cela devrait nettement vous simplifier la vie.

Évidemment vous pouvez remodifier le code selon les cas. Aussi ce code ne répondra jamais à tous les cas de figure, à moins d’avoir un code beaucoup trop complexe, ce qui n’est jamais le but recherché.

Vous avez une idée de boucle spécifique ? N’hésitez pas à adapter ce code ou à me contacter si vous avez besoin d’un accompagnement sur GeneratePress et WordPress.