Documentación · Guía de integración

Guía de invalidación de plantillas

Este documento explica cómo personalizar de forma segura las plantillas PHP utilizadas por el plugin ADP Car Market Hub mediante la creación de archivos de invalidación (overrides) en su tema, y cómo mantener esas invalidaciones de forma sostenible tras las actualizaciones del plugin.

Cuándo utilizar este documento

Utilice este documento si es:

Un desarrollador que necesita cambiar la estructura HTML del archivo de vehículos, del detalle de un vehículo individual o de la página de comparación más allá de lo que permiten los ajustes de Diseño y el CSS personalizado.
El encargado de mantener un tema personalizado y desea integrar las páginas de vehículos de forma fluida en la propia estructura HTML del tema.
El encargado de revisar un sitio web tras la actualización del plugin para comprobar si las invalidaciones existentes siguen siendo compatibles.

Esta guía está dirigida a desarrolladores PHP que estén familiarizados con el desarrollo de temas de WordPress. Si solo necesita cambiar colores, fuentes o espaciados, utilice en su lugar Car Market Hub → Diseño o el campo de CSS personalizado; no es necesario realizar ninguna invalidación de plantilla. Consulte la Guía de CSS personalizado.

Descripción general

El plugin proporciona plantillas PHP de respaldo para las páginas de vehículos en su directorio templates/. WordPress localiza las plantillas en un orden específico: los archivos del tema activo se comprueban antes que los archivos del plugin. El plugin utiliza este mecanismo de forma intencionada a través de locate_template():

WordPress comprueba el directorio del tema activo en busca de un archivo con el mismo nombre.
Si lo encuentra, se utiliza ese archivo del tema.
Si no lo encuentra, se utiliza la propia plantilla del plugin como respaldo.

Esto significa que puede invalidar cualquiera de las plantillas del frontend del plugin colocando un archivo con el mismo nombre en el directorio raíz de su tema. El archivo del plugin nunca se modifica y queda a salvo de sus personalizaciones durante las actualizaciones. Su archivo de invalidación permanece en el tema, el cual está bajo su propio control de versiones.

Plantillas disponibles para invalidación

Los siguientes archivos de plantilla se resuelven a través de locate_template() y se pueden invalidar:

Nombre de archivo de la plantilla	Propósito	Ubicación en el plugin
`single-as24ci_car.php`	Página de detalle de vehículo individual. Carga el diseño activo (actualmente siempre `single-as24ci_car-classic.php`).	`templates/single-as24ci_car.php`
`archive-as24ci_car.php`	Página de archivo y listados de vehículos. También se utiliza cuando el shortcode `[as24ci_archive]` se renderiza en modo plantilla.	`templates/archive-as24ci_car.php`

La página de comparación (page-as24ci_compare.php) y la sección parcial del filtro de búsqueda (parts/search-filter.php) se cargan directamente por el plugin y no se resuelven a través de locate_template(). No se pueden invalidar utilizando este método. Verifique este comportamiento en la versión actual del plugin antes de confiar en él.

Requisitos previos

Acceso a los archivos del tema activo (a través de FTP, SSH o el editor de archivos de WordPress).
Se recomienda encarecidamente el uso de un tema hijo (child theme) si está utilizando un tema comercial o un tema padre. Colocar archivos de invalidación en un tema padre significa que se perderán cuando este se actualice.
Familiaridad con PHP y las etiquetas de plantilla de WordPress (get_header(), get_footer(), the_title() y similares).

Instrucciones paso a paso

Creación de una invalidación de plantilla

Localice el archivo de origen. Busque la plantilla que desea personalizar en el directorio del plugin, en wp-content/plugins/adp-car-market-hub/templates/. Por ejemplo, archive-as24ci_car.php.
Copie el archivo (no lo mueva). Copie el archivo en el directorio raíz de su tema (hijo). El nombre del archivo debe ser idéntico: - Para el archivo: wp-content/themes/your-theme/archive-as24ci_car.php - Para el individual: wp-content/themes/your-theme/single-as24ci_car.php
Realice sus cambios en la copia del tema. Edite la copia en su tema. El archivo original del plugin permanece intacto.
Pruebe en el frontend. Visite un archivo de vehículos o una página de detalle de vehículo individual y confirme que se aplican sus cambios.

Verificación de qué plantilla está activa

La página de Salud del sitio de WordPress y los plugins de monitorización de consultas (por ejemplo, Query Monitor) pueden mostrar qué archivo de plantilla se está utilizando para cualquier solicitud dada. Alternativamente, añada un comentario temporal en la parte superior de su archivo de invalidación y compruebe el código fuente de la página para confirmar que el archivo se está cargando.

Mantener la compatibilidad tras las actualizaciones del plugin

Cuando se actualiza el plugin, las plantillas incluidas en templates/ pueden cambiar. Su archivo de invalidación permanece en el tema y se sigue utilizando, pero si la lógica de la plantilla del plugin ha cambiado, su invalidación podría quedar desactualizada.

Después de cada actualización del plugin:

Compare su archivo de invalidación con el archivo correspondiente en el directorio del plugin actualizado. Una herramienta de diff o un editor de código con comparación de archivos pueden resultar de ayuda.
Fusione cualquier cambio relevante de la nueva versión del plugin en su archivo de invalidación.
Pruebe las páginas de vehículos en el frontend después de realizar la fusión.

Mantener las invalidaciones al mínimo (que contengan solo las secciones que realmente necesita cambiar) reduce el trabajo necesario al fusionar las actualizaciones.

Referencia de configuración

No existe ningún campo de ajuste en el plugin que controle directamente las invalidaciones de plantillas. La lógica de resolución forma parte del sistema de ganchos (hooks) de WordPress y no se puede cambiar desde la administración del plugin.

Los ajustes de Diseño en Car Market Hub → Diseño se siguen aplicando incluso cuando se utiliza una invalidación de plantilla, ya que el CSS dinámico se genera a través de wp_head independientemente de qué archivo de plantilla se sirva.

Notas operativas

Requisito de tema hijo. Si está utilizando un tema comercial o un tema padre, cree siempre un tema hijo antes de añadir archivos de invalidación. Los archivos añadidos directamente a un tema padre se eliminan cuando el tema se actualiza.
La invalidación debe llamar a get_header() y get_footer(). Las propias plantillas del plugin llaman a ambos. Si su invalidación los omite, la página se servirá sin la navegación ni el pie de página del tema. Esto casi nunca es lo que se desea.
Mantener el espacio de nombres del plugin. Los archivos de plantilla del plugin declaran namespace AS24CI; y hacen referencia a constantes internas como CPT::POST_TYPE y Options::DESIGN_SINGLE_LAYOUT. Si su invalidación utiliza alguna de estas, mantenga la declaración del espacio de nombres o califique completamente los nombres de las clases.
Modo de renderizado de shortcode. La plantilla de archivo admite dos modos de renderizado controlados por la variable global $as24ci_render_mode: 'template' (cuando se sirve como una página de archivo de CPT) y 'shortcode' (cuando se incluye mediante el shortcode [as24ci_archive]). La plantilla omite get_header() y get_footer() en el modo shortcode. Su invalidación debería replicar este comportamiento si desea que el shortcode funcione correctamente junto con la plantilla de archivo.
Estabilidad de las clases CSS. El CSS del plugin depende de los nombres de clase en el HTML de la plantilla (por ejemplo, .as24ci-page, .as24ci-page-classic, .as24ci-archive-list, .as24ci-archive-row). Si elimina o cambia el nombre de estas clases en su invalidación, la hoja de estilos del plugin y los ajustes de Diseño dejarán de funcionar para esos elementos. Cambie los nombres de las clases únicamente si también actualiza el CSS correspondiente en el campo de CSS personalizado o en la hoja de estilos de su tema.
Clase alignfull. El plugin añade la clase alignfull al contenedor .as24ci-page para que los temas de bloques lo extiendan al ancho completo. Si elimina esta clase en su invalidación, no se aplicará el comportamiento de ancho completo del tema de bloques.
Requisitos de versión de PHP y versión de WordPress. Las plantillas del plugin utilizan características de PHP coherentes con los requisitos establecidos del plugin. Consulte los Requisitos de PHP y base de datos.

Resolución de problemas

Síntoma	Causa probable	Qué comprobar
No se está utilizando el archivo de invalidación.	El archivo está en el directorio incorrecto, tiene una errata en el nombre del archivo o está en la raíz del tema padre en lugar de la raíz del tema hijo.	Confirme el nombre exacto del archivo y su ubicación. Utilice Query Monitor o compruebe el código fuente de la página en busca de un comentario temporal en el archivo de invalidación.
Las páginas de vehículos devuelven una página en blanco o un error de PHP tras crear la invalidación.	El archivo de invalidación tiene un error de sintaxis PHP o le falta un include obligatorio.	Compruebe el registro de errores de PHP del servidor. Confirme que el archivo de invalidación abre y cierra las etiquetas PHP correctamente.
El CSS del plugin no se aplica en la plantilla invalidada.	Falta la clase de contenedor `.as24ci-page` o `.as24ci-page-classic` en la salida de la invalidación.	Asegúrese de que el contenedor externo `<div class="as24ci-page as24ci-page-classic …">` esté presente en la invalidación.
Los ajustes de Diseño (colores, tipografía) no tienen efecto.	La salida de CSS dinámico depende de las clases de contenedor del plugin. Si no están presentes, las reglas con alcance específico no coincidirán.	Restaure las clases de contenedor tal como se describe anteriormente.
El shortcode `[as24ci_archive]` no muestra la cabecera ni el pie de página del tema cuando la invalidación de archivo también está activa.	La invalidación siempre llama a `get_header()` y `get_footer()` independientemente de `$as24ci_render_mode`.	Añada una comprobación para `$as24ci_render_mode === 'template'` antes de llamar a `get_header()` y `get_footer()`, imitando la propia lógica de plantilla del plugin.