Contents
Introducción: ¿Qué es la Template Hierarchy de WordPress?
La Template Hierarchy es el sistema que utiliza WordPress para decidir qué archivo de plantilla cargar según la URL solicitada. Entenderla es clave para crear temas flexibles, mantenibles y compatibles con child themes. Aquí tienes un tutorial detallado, con ejemplos prácticos y técnicas para controlar exactamente qué plantilla se usa en cada situación.
Conceptos básicos
Al recibir una petición, WordPress recorre una lista ordenada de nombres de archivo y carga el primero que exista en el tema (o en el child theme). Si no encuentra ninguno, hace fallback a index.php. La jerarquía está pensada para ser predecible: archivos más específicos (por ejemplo single-product.php) tienen prioridad sobre archivos genéricos (por ejemplo single.php o index.php).
Reglas importantes
- Los templates del child theme tienen prioridad sobre los del theme padre.
- Al crear plantillas personalizadas para páginas o taxonomías, sigue estrictamente la nomenclatura para que WordPress las detecte automáticamente.
- Puedes forzar la carga de un template usando filtros como template_include o funciones como get_template_part() y locate_template().
Jerarquía común — Resumen práctico
Aquí tienes la lista de orden de comprobación para los casos más comunes. Coloca los archivos en el directorio del tema (o child theme) para que WordPress los detecte:
Páginas estáticas (Pages)
- page-{slug}.php (por ejemplo page-contacto.php)
- page-{id}.php (por ejemplo page-42.php)
- page.php
- singular.php
- index.php
Entradas singulares (Posts y Custom Post Types)
- single-{post_type}.php (por ejemplo single-product.php para CPT product)
- single.php
- singular.php
- index.php
Archivo de entradas (Blog)
- home.php (muestra los posts cuando la página de entradas está en la página principal o en la página de posts)
- index.php
Front page
- front-page.php (si existe, tiene prioridad sobre home.php y page.php para la portada)
- home.php
- page.php
- index.php
Archivos por taxonomía y taxonomías personalizadas
- taxonomy-{taxonomy}-{term}.php
- taxonomy-{taxonomy}.php
- taxonomy.php
- archive.php
- index.php
Categorías y etiquetas
- category-{slug}.php
- category-{id}.php
- category.php
- archive.php
- index.php
Búsqueda, autor, fecha, 404
- search.php
- author.php
- date.php
- 404.php
Plantillas personalizadas para páginas (Page Templates)
Si quieres que una página utilice una plantilla elegible desde el editor de páginas, añade un archivo PHP con un encabezado de plantilla. Ejemplo:
lt?php / Template Name: Plantilla Contacto Template Post Type: page / get_header() ?gt ltmaingt lth2gtContactolt/h2gt lt!-- Contenido de la plantilla --gt lt/maingt lt?php get_footer() ?gt
El comentario inicial hace que WordPress liste la plantilla en el selector de plantillas del editor. Puedes usar Template Post Type para registrar la plantilla también para otros tipos de post (por ejemplo CPT).
Ejemplos de archivos esenciales
front-page.php (portada)
lt?php get_header() ?gt ltsection class=herogt lth2gtBienvenido a mi sitiolt/h2gt lt/sectiongt lt?php get_footer() ?gt
home.php (listado de posts)
lt?php
get_header()
if ( have_posts() ) :
while ( have_posts() ) : the_post()
get_template_part( template-parts/content, get_post_type() )
endwhile
the_posts_pagination()
else :
get_template_part( template-parts/content, none )
endif
get_footer()
?gt
single.php (entrada individual)
lt?php get_header() if ( have_posts() ) : while ( have_posts() ) : the_post() the_title(lth1gt,lt/h1gt) the_content() endwhile endif get_footer() ?gt
Personalizar plantillas para Custom Post Types
Si registras un CPT llamado producto, crea single-producto.php (o single-product.php si registraste el slug como product) para personalizar su vista singular. Para el listado archive, crea archive-producto.php.
lt?php
// functions.php - registrar CPT (ejemplo)
function crear_cpt_producto() {
args = array(
label => Productos,
public => true,
has_archive => true,
supports => array(title,editor,thumbnail),
)
register_post_type(producto, args)
}
add_action(init, crear_cpt_producto)
?gt
Uso de get_template_part() para fragmentar plantillas
Para mantener plantillas limpias, divide piezas reutilizables en template-parts. Por ejemplo:
// Llamada desde single.php o loop
get_template_part(template-parts/content, get_post_type())
// Busca template-parts/content-{post_type}.php primero, luego content.php
Detectar qué plantilla está cargando WordPress (debug)
Para depurar qué archivo se está usando, añade temporalmente este filtro (no dejar en producción):
add_filter(template_include, function(template){
error_log(Plantilla cargada: . template)
return template
})
También puedes mostrarlo en pantalla (solo para desarrollo):
add_action(wp_footer, function(){
global template
echo lt!-- Plantilla actual: . basename(template) . --gt
})
Sobrescribir plantillas desde un child theme
Si el sitio usa un child theme, coloca el archivo con el mismo nombre en el child theme y WordPress lo usará en lugar del del padre. Para cargar archivos del padre desde el child theme cuando lo necesites, usa get_template_part() apuntando al path relativo: WordPress ya respeta el child theme automáticamente.
Funciones útiles relacionadas con la jerarquía
- get_page_template(), get_single_template(), get_archive_template(): devuelven la ruta de la plantilla que se usaría.
- locate_template(): busca plantillas en child y parent themes y devuelve la ruta con segundo parámetro true puedes cargarla directamente.
- template_include: filtro para interceptar y cambiar la plantilla final que WordPress va a incluir.
- is_page_template(mi-plantilla.php): comprueba si la página usa una plantilla concreta (útil para condicionales en functions.php).
Ejemplo: forzar una plantilla desde functions.php para una condición concreta
Si quieres redirigir determinadas consultas a una plantilla específica (por ejemplo, todas las búsquedas con un parámetro), usa el filtro template_include:
add_filter(template_include, function(template){
if ( is_search() isset(_GET[mi_param]) ) {
new_template = locate_template(search-special.php)
if ( new_template ) return new_template
}
return template
})
Buenas prácticas
- Mantén la lógica PHP en functions.php o en clases deja las plantillas para estructura y marcado.
- Usa get_template_part() para fragmentar y evitar duplicación.
- Documenta los templates personalizados con comentarios de cabecera cuando sean Page Templates.
- Prueba con child themes para actualizar el theme padre sin perder personalizaciones.
- Activa WP_DEBUG y revisa los logs cuando algo no carga como esperas.
Recursos y referencias
La documentación oficial y las guías de referencia pueden ser muy útiles: consulta la guía de la jerarquía de plantillas en el Codex o en el Developer Handbook de WordPress para detalles completos y ejemplos adicionales: https://developer.wordpress.org/themes/basics/template-hierarchy/
Resumen final
La Template Hierarchy es la columna vertebral del sistema de plantillas de WordPress. Aprender la prioridad de los archivos, cómo crear plantillas personalizadas y cómo fragmentar el tema con get_template_part() y child themes te permite construir temas robustos y fáciles de mantener. Sigue las nomenclaturas y usa las herramientas de depuración para asegurarte de que siempre se carga la plantilla que esperas.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |