if ( null !== $pre_render ) { return $pre_render; } — cette ligne, extraite du cœur de WordPress, résume à elle seule tout l’intérêt du filtre pre_render_block : dès qu’une valeur non nulle est retournée, le rendu normal du bloc est purement et simplement ignoré.
Ce billet s’adresse aux développeurs avancés qui veulent remplacer le rendu d’un bloc précis, utilisé dans un gabarit ou un fragment de gabarit, sans pour autant désenregistrer ce bloc ni modifier son code source. Il ne traite pas des transients, qui répondent à un besoin différent — celui de mise en cache plutôt que de substitution de rendu.
Ce que fait réellement ce filtre
Le filtre pre_render_block s’exécute avant que WordPress ne génère le HTML final d’un bloc. Il reçoit en paramètre le contenu potentiellement pré-calculé (généralement null au premier passage) ainsi que le tableau représentant le bloc parsé, avec son nom et ses attributs.
add_filter( 'pre_render_block', function( $pre_render, $bloc ) {
if ( 'core/latest-posts' !== $bloc['blockName'] ) {
return $pre_render;
}
return '<div class="remplacement-personnalise">Contenu de remplacement</div>';
}, 10, 2 );Dans cet exemple, tout bloc core/latest-posts présent dans un gabarit ou un fragment de gabarit voit son rendu habituel entièrement ignoré, remplacé par le contenu retourné par le filtre.
Pourquoi ne pas simplement désenregistrer le bloc
Désenregistrer un bloc avec unregister_block_type() le rend indisponible partout, y compris dans l’éditeur, où il disparaîtrait purement et simplement de l’inserteur de blocs. Le filtre pre_render_block propose une alternative plus ciblée : le bloc reste disponible et modifiable normalement dans l’éditeur, seul son affichage final change, et uniquement dans les conditions définies par le développeur.
- Le bloc reste visible et éditable dans l’éditeur, contrairement à un bloc désenregistré.
- Le remplacement peut être conditionnel — selon le gabarit, la page, ou tout autre contexte.
- Le filtre s’applique aussi bien aux gabarits qu’aux fragments de gabarit, sans distinction.
Un cas d’usage concret dans un fragment de gabarit
Imaginons un fragment de gabarit utilisé comme en-tête, contenant un bloc de recherche que l’on souhaite remplacer par un champ personnalisé plus riche, sans réécrire tout le fragment ni créer un bloc entièrement nouveau :
add_filter( 'pre_render_block', function( $pre_render, $bloc, $instance ) {
if ( 'core/search' !== $bloc['blockName'] ) {
return $pre_render;
}
ob_start();
get_template_part( 'template-parts/recherche-personnalisee' );
return ob_get_clean();
}, 10, 3 );Le troisième paramètre, l’instance du bloc au format WP_Block, donne accès au contexte complet dans lequel le bloc s’exécute, ce qui permet des remplacements encore plus fins si nécessaire.
Les limites à connaître
Ce filtre s’applique globalement, à tous les blocs du même type sur l’ensemble du site, sauf condition explicite dans le code. Un remplacement mal ciblé peut donc avoir des effets de bord inattendus sur des pages où le remplacement n’était pas souhaité. Une vérification systématique du contexte, avant de retourner un contenu de remplacement, reste indispensable.
Un filtre puissant appliqué sans condition finit toujours par surprendre quelqu’un, souvent plusieurs mois après sa mise en place, quand le contexte d’origine a été oublié.
Une alternative à connaître
Pour des remplacements plus limités, portant uniquement sur le contenu final déjà généré plutôt que sur le rendu entier, le filtre render_block — qui s’exécute après le rendu normal — peut suffire et s’avère parfois plus simple à raisonner que pre_render_block, qui court-circuite tout.
En résumé
Le filtre pre_render_block offre un point d’intervention précis pour remplacer entièrement le rendu d’un bloc, dans un gabarit comme dans un fragment de gabarit, sans toucher à son enregistrement. Sa puissance impose en retour une discipline de conditionnement stricte, sous peine de propager un remplacement à des contextes qui n’en avaient pas besoin.
