Documentación · Documentación técnica

Sobrescritura de plantillas

Este documento explica cómo sobrescribir las plantillas del frontend integradas en el plugin ADP Car Market Hub desde un tema (hijo) para que las actualizaciones no sobrescriban sus personalizaciones.

Cuándo utilizar este documento

Lea este documento si necesita:

Ajustar el marcado, el diseño o el orden de los campos en la página de vehículo individual o en el archivo de vehículos sin modificar los archivos de origen del plugin.
Aplicar contenedores, barras laterales o hooks específicos del tema a las páginas del plugin.
Migrar personalizaciones existentes a un tema hijo para que sean seguras frente a futuras actualizaciones.

Para conocer el flujo subyacente de carga de plantillas, consulte el Sistema de plantillas del frontend. Para conocer los shortcodes basados en plantillas, consulte Shortcodes.

Descripción general

El plugin renderiza las páginas de vehículos individuales y el archivo de vehículos a través de dos filtros de WordPress:

single_template — reemplazado por single-as24ci_car.php (sobrescritura del tema) o el archivo integrado del plugin.
archive_template — reemplazado por archive-as24ci_car.php (sobrescritura del tema) o el archivo integrado del plugin.

Para cada filtro, el plugin llama primero a locate_template(). Si el tema activo (o su tema hijo) proporciona un archivo con el nombre esperado, ese archivo tiene prioridad. De lo contrario, el plugin recurre al archivo incluido en su propio directorio templates/.

Esto hace que las sobrescrituras sean sencillas: coloque un archivo con el nombre correcto en su tema y WordPress lo cargará en lugar de la versión integrada.

Requisitos o prerrequisitos

Se recomienda encarecidamente el uso de un tema hijo para que las actualizaciones del tema no sobrescriban sus modificaciones.
Familiaridad con los archivos de plantilla integrados. Están bajo el espacio de nombres AS24CI y dependen de clases del plugin como Archive_Filters, Field_Mapping, Schema, Options y Locations.
Acceso de lectura al directorio templates/ del plugin para copiar el marcado integrado actual como punto de partida.

Instrucciones paso a paso

Identifique la plantilla que desea sobrescribir: - Página de vehículo individual → single-as24ci_car.php. - Página de archivo de vehículos → archive-as24ci_car.php.
Copie el archivo integrado desde el directorio templates/ del plugin en la raíz de su tema (hijo) utilizando el mismo nombre de archivo.
Edite la copia en su tema. Mantenga las referencias de clase y las consultas de datos existentes a menos que esté seguro de su reemplazo.
Limpie cualquier caché de página completa o de plantillas.
Recargue la página correspondiente en el frontend y confirme que se está cargando la sobrescritura (por ejemplo, visualizando el código fuente de la página para buscar un comentario de marca que haya añadido).

Ubicaciones de sobrescritura

El plugin utiliza locate_template() con el nombre de archivo básico. Eso significa que WordPress busca en:

El directorio raíz del tema hijo activo.
El directorio raíz del tema padre activo.

Las estructuras de subdirectorios dentro de un tema (por ejemplo, <theme>/templates/single-as24ci_car.php) no son examinadas por el filtro del plugin. Coloque los archivos de sobrescritura en la raíz del tema utilizando el nombre de archivo exacto.

Qué se puede sobrescribir

single-as24ci_car.php — toda la página de vehículo individual. El contenedor integrado es intencionadamente ligero; el diseño real reside en single-as24ci_car-classic.php. Sobrescribir el contenedor significa que usted asume la total responsabilidad de elegir e incluir un diseño.
archive-as24ci_car.php — toda la página de archivo de vehículos. Este es también el archivo que incluye el shortcode [as24ci_archive] (consulte las Limitaciones a continuación).

Qué no se puede sobrescribir directamente

Partes de plantilla (por ejemplo, templates/parts/search-filter.php) se cargan con include desde rutas absolutas del plugin y no pasan por locate_template(). Para personalizarlas, sobrescriba la plantilla padre que las incluye y replique la salida requerida, o utilice los hooks y filtros disponibles en el plugin.
Plantillas de shortcodes — [as24ci_archive], [as24ci_compare] y [as24ci_search_filter] siempre incluyen los archivos integrados del plugin (archive-as24ci_car.php, page-as24ci_compare.php, parts/search-filter.php). Por lo tanto, una sobrescritura de archive-as24ci_car.php en el tema también afecta al shortcode [as24ci_archive], pero las plantillas de comparación y de filtro de búsqueda no se pueden sobrescribir a través de locate_template().
CSS/JS del plugin de los que dependen las plantillas. Sobrescriba los estilos a través de la hoja de estilos de su tema en lugar de eliminar los recursos encolados por el plugin.

Notas operativas

Al actualizar el plugin, revise el registro de cambios (changelog) para ver si hay modificaciones en las plantillas integradas. Si el plugin añade o elimina datos que la plantilla renderiza, es posible que deba actualizar su sobrescritura para adaptarla.
Evite mezclar sobrescrituras parciales con código que asuma la estructura del archivo integrado. Mantenga la sobrescritura lo más fiel posible al original o documente la divergencia dentro del archivo.
Las sobrescrituras del tema no se ven afectadas por las actualizaciones automáticas del plugin porque WordPress solo actualiza los archivos dentro del directorio del plugin.
Las sobrescrituras se aplican tanto a los administradores conectados como a los visitantes. No existe un mecanismo de sobrescritura por rol en el plugin.
Las sobrescrituras no pueden eludir las comprobaciones de tipo de contenido personalizado (post-type) o de capacidades que aplican los filtros: la sobrescritura solo se carga para solicitudes legítimas de archivo o de elemento individual de as24ci_car.

Resolución de problemas

El archivo de sobrescritura se ignora — confirme que el archivo está en la raíz del tema activo y utiliza el nombre de archivo exacto (single-as24ci_car.php o archive-as24ci_car.php). Compruebe si hay algún error tipográfico o si existe un tema padre que ya proporciona dicho archivo.
Error fatal tras la sobrescritura — las plantillas integradas utilizan el espacio de nombres AS24CI y hacen referencia a clases del plugin. Si solo copió parte del archivo, restaure la declaración del espacio de nombres y la protección defined( 'ABSPATH' ), y mantenga intactas las consultas Field_Mapping / Archive_Filters.
La sobrescritura aparece en el archivo del CPT pero no en el shortcode — ambas rutas cargan archive-as24ci_car.php desde el directorio templates/ del plugin; el shortcode no utiliza locate_template(). Verifique la ruta de su sobrescritura y que ningún plugin de caché esté sirviendo una versión antigua de la página.
El diseño se muestra sin estilos tras la sobrescritura — el CSS integrado espera nombres de clase específicos. Mantenga esos nombres de clase en su sobrescritura o amplíe la hoja de estilos del tema para cubrir el nuevo marcado.