Cómo usar template-parts dentro de un bloque Query Loop de WordPress

¿Por qué centralizar las tarjetas de contenido (Cards) en un template part?

A medida que un sitio en WordPress crece, es común reutilizar el mismo tipo de tarjeta de contenido (Card) en múltiples lugares: listados de entradas, bloques de artículos relacionados, resultados de búsqueda, bloques personalizados de secciones específicas, etc.

Si cada una de estas tarjetas se implementa de forma independiente —ya sea desde el editor de bloques o con código repetido— el mantenimiento se vuelve más complejo. Cualquier cambio visual o estructural implica actualizar manualmente cada instancia, lo que aumenta el riesgo de errores e inconsistencias.

Al centralizar la Card en un archivo único, es decir, un template part, conseguimos:

• Un único lugar desde el que controlar el diseño y la estructura de nuestras tarjetas.
• Reutilización limpia del mismo componente en cualquier parte del sitio, sin duplicar código.
• Mantenimiento más rápido y seguro, ya que cualquier mejora se propaga automáticamente a todos los lugares donde se use ese template part.
• Mayor coherencia visual y funcional en todo el sitio, especialmente útil cuando trabajas en equipo o en sitios a gran escala.

Este enfoque es especialmente útil cuando desarrollamos temas a medida o usamos el editor de sitios de WordPress, pero aún queremos tener el control fino que nos da el código.

Ventajas y limitaciones de esta solución

Reutilizar un template part dentro de un Query Loop es una técnica práctica y flexible, especialmente cuando quieres mantener todo el diseño de tus Cards (tarjetas de contenido) en un solo archivo. Sin embargo, como cualquier solución, tiene sus pros y contras.

✅ Ventajas

• Centralización total del diseño: cualquier cambio en el template part se refleja automáticamente en todas las secciones donde se usa.
• Reducción del código duplicado: no es necesario copiar y pegar estructuras similares en múltiples bloques o plantillas, lo que simplifica el desarrollo.
• Mejor rendimiento y limpieza de código: al evitar duplicidades innecesarias, el código es más fácil de mantener y depurar.
• Control total con PHP: ideal para proyectos donde se requiere lógica condicional avanzada o integración con funciones personalizadas. Especialmente útil si usas las mismas Cards en muchas secciones distintas del sitio.

⚠️ Limitaciones

• Pierdes la edición visual desde el editor de bloques: al usar un template part directamente con código, no puedes modificar su contenido desde la interfaz visual del editor de bloques.
• Menor flexibilidad para editores de contenido: los usuarios no podrán modificar estas tarjetas desde el editor.
• Requiere conocimientos técnicos: esta solución es más técnica y menos accesible para usuarios que trabajan únicamente con el editor visual de WordPress.
• Menor portabilidad entre temas si el template part está muy personalizado para un diseño específico.

En resumen, es una solución muy útil para equipos técnicos o proyectos donde se prioriza el rendimiento, la consistencia y el control del código. Pero hay que considerar el perfil del equipo y los requisitos del proyecto antes de adoptarla como estándar.

Cómo insertar un template part clásico dentro de un bloque Query Loop en un tema de bloques

En un tema basado en bloques (Full Site Editing), los archivos .php dejan de ser el lugar principal donde definimos la estructura visual. En su lugar, usamos archivos .html con bloques declarativos y configuramos su comportamiento a través de filtros y funciones en functions.php.

Si ya tienes definida una Card como un template part, y estás usando un bloque Query Loop, es posible que te preguntes: ¿cómo puedo reutilizar esa misma Card en todas las instancias del loop, sin duplicar su estructura en cada plantilla HTML?.

La respuesta está en aprovechar el sistema de template parts de WordPress y aplicar un enfoque un poco más técnico: reemplazar dinámicamente el contenido del bloque core/post-template dentro del Query Loop, e insertar ahí tú template part. Así evitas repetir la estructura HTML de la Card dentro de cada plantilla o patrón donde uses un loop.

Esto se hace a través del filtro render_block, que te permite interceptar cualquier bloque al momento de renderizarlo y modificar su salida. Con este método, puedes inyectar get_template_part() en el momento justo, manteniendo la vista HTML limpia y reutilizando tu componente de forma controlada.

Esto es especialmente útil si usas un tema basado en bloques, pero quieres mantener algunas partes en código para tener más control o evitar duplicación de estilos y estructura.

En el siguiente punto te muestro exactamente cómo hacerlo.

Código de ejemplo: interceptando el bloque core/post-template con render_block

Para reutilizar tu Card definida en un template part dentro de un bloque Query Loop, puedes usar el filtro render_block. Este filtro te permite interceptar la salida de cualquier bloque antes de que se renderice en el frontend, y reemplazarla por el contenido que tú quieras —en este caso, tu propio template.

A continuación, te dejo un ejemplo funcional donde se identifica un Query Loop mediante una clase CSS personalizada (prefix-blog-query) y se reemplaza su contenido por el template part card-blog.php.

add_filter('render_block', 'prefix_modificar_contenido_bloque', 10, 2);
function prefix_modificar_contenido_bloque($block_content, $block) {
    // Clase CSS objetivo (la que usas para identificar tu loop)
    $clase_objetivo = 'prefix-blog-query';
    
    // Verificar si el bloque tiene esa clase
    if (!empty($block['attrs']['className']) && strpos($block['attrs']['className'], $clase_objetivo) !== false) {
        global $post;
        static $procesados = array(); // Evitar duplicados en el loop
        
        if (isset($post) && is_object($post) && !in_array($post->ID, $procesados)) {
            $post_id = $post->ID;
            $procesados[] = $post_id;
            
            // Argumentos personalizados para el template
            $args = array(
                'tag_title' => 'h2',
                'item' => get_post($post_id)
            );
            
            // Capturar el contenido del template part
            ob_start();
            get_template_part('/template-parts/card', 'blog', $args);
            $template_content = ob_get_clean();
            
            return $template_content;
        }
    }
    return $block_content;
}

¿Cómo funciona?

• Identificación del loop: en el editor de bloques, asegúrate de asignar una clase personalizada al bloque Plantilla de entrada que tenemos dentro del bloque Query Loop, como prefix-blog-query.
• Interceptación: el filtro render_block detecta cuándo se está renderizando un bloque con esa clase.
• Reemplazo del contenido: por cada post del loop, se carga el template part card-blog.php, pasando el post actual como argumento y sustituyendo los bloques que normalmente tendríamos dentro de la Plantilla de entrada.

Esto te permite reutilizar tú Card sin duplicar su estructura HTML dentro del loop, manteniendo todo centralizado y bajo control.

Al template card-blog.php, le enviamos el contenido del post con $args['item'] y con $args['tag_title'] le pasamos el tag HTML que se usará como título (por ejemplo, h2, h3 o P ), permitiendo ajustar la semántica según el contexto en el que se muestre la tarjeta. De esta forma, mantenemos el template lo más flexible y reutilizable posible, siguiendo buenas prácticas de SEO.

Casos de uso reales: dónde aplicar este enfoque

Centralizar el diseño de las Cards usando un template part y renderizarlo dinámicamente dentro del Query Loop abre muchas posibilidades prácticas en sitios WordPress que reutilizan contenido en distintas secciones. Aquí algunos ejemplos donde este patrón resulta especialmente útil:

Blog principal
En la página del blog, puedes usar un Query Loop para mostrar la lista de entradas recientes y, en lugar de construir la estructura desde el editor de bloques, simplemente reutilizar tu Card personalizada. Esto asegura que el diseño se mantenga igual que en otras partes del sitio.

Artículos relacionados
En la parte inferior de una entrada, puedes insertar un bloque Query Loop filtrado por categoría o etiquetas para mostrar contenido relacionado. Gracias a esta técnica, puedes mostrar exactamente la misma tarjeta que usas en el listado del blog, pero sin duplicar el código.

Secciones especiales o temáticas (como “JOR”)
Si tienes secciones de contenido temático —por ejemplo, una sección de recursos, noticias específicas o contenido curado— puedes aplicar el mismo principio: usas un Query Loop filtrado y dejas que el template part se encargue del diseño de cada tarjeta.

Bloques personalizados sin lógica de presentación
En algunos casos, puedes tener un bloque personalizado que solo define la lógica (por ejemplo, qué mostrar), y dejar que el diseño lo maneje siempre el mismo template part. Esta separación entre lógica y presentación mejora la escalabilidad y el mantenimiento.

Consideraciones finales y posibles mejoras

Reutilizar un template part dentro de un bloque Query Loop es una solución elegante para mantener las Cards centralizadas y coherentes a lo largo de todo un sitio WordPress. Aunque puede parecer una técnica poco convencional al principio, ofrece ventajas claras en términos de mantenimiento, consistencia visual y control total sobre el HTML renderizado.

Pero, como cualquier enfoque técnico, también puede evolucionar y adaptarse a necesidades más complejas. Aquí algunas ideas para mejorar o complementar esta técnica:

Reutilización avanzada con múltiples variantes
Puedes extender tu template part para aceptar más argumentos (por ejemplo, mostrar_fecha, mostrar_categoria, etc.) y así reutilizar una misma tarjeta en distintos contextos visuales sin tener que duplicar el archivo.

Integración con patrones o estilos globales
Aunque esta técnica trabaja por fuera del editor de bloques, puedes acompañarla con clases utilitarias de Tailwind, Bootstrap, o los estilos globales definidos en theme.json, manteniendo la coherencia de diseño.

Testeo visual en plantillas
Como la lógica de presentación está en el template part, puedes probar cambios de diseño en un solo archivo y ver rápidamente el efecto en múltiples partes del sitio. Esto te ahorra tiempo y reduce errores.

Alternativas si necesitas control visual
Si trabajas con editores de contenido que no manejan código, podrías considerar crear un bloque personalizado que internamente cargue el template part. Así mantienes la flexibilidad de diseño, pero sin perder la facilidad del editor visual.

En definitiva, este patrón es ideal para sitios que escalan, que requieren consistencia y que deben mantenerse fácilmente a lo largo del tiempo. Si bien no es la opción por defecto del editor visual, es una gran aliada cuando buscas eficiencia y control real del código.

Reutiliza tus Cards de forma eficiente y mantén tu diseño centralizado

Como hemos visto, integrar template parts dentro del bloque Query Loop te permite tener un control total sobre la presentación de tus tarjetas de contenido (Cards), sin sacrificar la flexibilidad que ofrece el editor de bloques. Este enfoque reduce la duplicación de código, mejora el mantenimiento a largo plazo y asegura una experiencia visual coherente en todo el sitio.

Además, al centralizar el diseño en un único archivo, puedes escalar más fácilmente tu tema o sistema de diseño sin preocuparte por inconsistencias visuales entre secciones.

Si estás desarrollando un tema con WordPress moderno y necesitas que tus componentes sean reutilizables, esta técnica puede ser justo lo que necesitas para combinar estructura limpia, control en el código y eficiencia en el desarrollo.