Documentación · Documentación técnica

Sistema de plantillas del frontend

Este documento explica cómo el plugin ADP Car Market Hub renderiza las páginas de vehículos en el frontend, cómo se relacionan sus plantillas integradas con el tema WordPress activo y qué puntos de extensión se exponen a los temas y shortcodes.

Cuándo utilizar este documento

Lea este documento si necesita:

Entender qué archivo renderiza la página de vehículo individual o el archivo de vehículos.
Decidir si utilizar un listado basado en shortcodes dentro de una página normal o confiar en el archivo del CPT.
Extender o sobrescribir el diseño desde un tema hijo. Para conocer la mecánica de sobrescritura, consulte Template Overrides.

Descripción general

El plugin registra su tipo de contenido personalizado as24ci_car con soporte para archivos y distribuye un pequeño conjunto de plantillas integradas bajo el directorio templates/ del plugin. Dos filtros de WordPress enrutan las solicitudes a esas plantillas cuando el tema activo no proporciona su propia versión:

single_template — utilizado para is_singular( 'as24ci_car' ).
archive_template — utilizado para is_post_type_archive( 'as24ci_car' ).

Cada filtro primero solicita a WordPress que localice una sobrescritura a nivel de tema (locate_template()), y solo recurre al archivo integrado del plugin cuando no existe ninguna sobrescritura.

Plantillas integradas

Los siguientes archivos se encuentran bajo la carpeta templates/ del plugin y son cargados por los filtros anteriores (o por shortcodes):

single-as24ci_car.php — un contenedor ligero que selecciona el diseño de vehículo individual adecuado según la opción as24ci_design_single_layout e incluye el archivo de diseño elegido.
single-as24ci_car-classic.php — el diseño actual de vehículo individual. Actualmente, el contenedor siempre carga este archivo; las versiones futuras pueden añadir diseños adicionales. Verifique el comportamiento con la versión actual del plugin antes de publicar textos orientados al cliente.
archive-as24ci_car.php — el diseño del archivo de vehículos utilizado para el archivo del CPT y para el shortcode [as24ci_archive].
parts/search-filter.php — plantilla parcial renderizada por [as24ci_search_filter] para mostrar el formulario de búsqueda independiente.
page-as24ci_compare.php — página de comparación renderizada por [as24ci_compare].
icons/ — ayudantes de iconos SVG en línea compartidos que se utilizan en todas las plantillas.
css/ y js/ — recursos de los que dependen las plantillas.

Cómo llega una solicitud a una plantilla

WordPress analiza la solicitud y la resuelve para un único vehículo o para el archivo de vehículos.
Justo antes de la salida, WordPress aplica single_template o archive_template.
La función de devolución de llamada (callback) del filtro del plugin: - devuelve el $template original cuando la solicitud no es para as24ci_car; - llama a locate_template( '<template>.php' ) para dar al tema activo (o tema hijo) la primera oportunidad de sobrescribir; - si no existe ningún archivo del tema, devuelve el archivo integrado desde el directorio templates/ del plugin; - si no existe ninguno de los dos, devuelve el $template original para que WordPress pueda recurrir a su jerarquía estándar.

Los shortcodes siguen el mismo espíritu de precedencia, pero no llaman a locate_template(); siempre incluyen los archivos integrados de archivo / comparación / filtro de búsqueda del plugin. Consulte Shortcodes y Template Overrides para conocer las implicaciones.

Integración de shortcodes y modos de renderizado

El plugin expone una bandera global, $as24ci_render_mode, que los controladores de shortcodes establecen en 'shortcode' mientras se ejecuta su plantilla integrada. El código condicional en las plantillas y en las clases de soporte (por ejemplo, la carga de recursos) utiliza esta bandera para aplicar la misma lógica en las páginas basadas en shortcodes que la que aplican en el archivo nativo del CPT.

El shortcode [as24ci_archive] reemplaza el $wp_query global con una consulta personalizada mientras se renderiza la plantilla de archivo, y restaura la consulta anterior y wp_reset_postdata() después, de modo que se pueda incrustar de forma segura dentro de una página normal.

Referencia de configuración

Clave de opción	Efecto en el renderizado
`as24ci_design_single_layout`	Selecciona el diseño de vehículo individual. El contenedor actual siempre carga el archivo de diseño clásico; esta opción también alimenta las clases de body y el CSS adaptados al diseño. Por defecto `'minimal'`.

Los selectores de diseño, diseño visual y características que afectan a lo que se renderiza dentro de las plantillas (zonas de filtro, conjunto de campos de favoritos, selector de agente de búsqueda, etc.) se documentan en Options And Settings Storage.

Notas de funcionamiento

Las funciones de devolución de llamada del filtro del plugin devuelven la ruta del archivo integrado como una cadena. WordPress incluye el archivo con su cargador de plantillas estándar, por lo que las variables globales como $post, $wp_query y las clases de body se comportan como en cualquier plantilla de tema.
Las plantillas integradas declaran namespace AS24CI; y exit cuando ABSPATH no está definido, reflejando la protección estándar de WordPress.
Los archivos de plantilla hacen referencia a clases del plugin como Archive_Filters, Field_Mapping, Schema, Options y Locations para recopilar sus datos. Los temas que sobrescriban el archivo deben mantener intactas estas referencias (o replicar la obtención de datos equivalente) para evitar advertencias de variables no definidas.
El archivo basado en shortcode fuerza un WP_Query nuevo a partir de los parámetros de $_GET a través de Archive_Filters::build_query_args_from_request(), por lo que los filtros de URL funcionan de manera idéntica en el archivo del CPT y en las páginas de shortcode.

Resolución de problemas

El diseño del plugin nunca aparece — confirme que el tema activo no define su propio single-as24ci_car.php o archive-as24ci_car.php; los archivos del tema siempre tienen prioridad. Consulte Template Overrides.
Una página que utiliza [as24ci_archive] muestra la entrada incorrecta — el shortcode reemplaza la consulta global mientras se ejecuta y la restaura después. Si un componente de tema personalizado lee la consulta global antes de que se procese el shortcode, el orden en el que la página renderiza las partes del diseño es importante; incruste el shortcode en el área de contenido principal en lugar de en la cabecera o en la barra lateral.
La paginación se restablece a la página 1 dentro de [as24ci_archive] — el shortcode lee ?paged= y ?page= de la URL. Asegúrese de que su estructura de enlaces permanentes permita cadenas de consulta o utilice un enlace permanente que sea compatible con el shortcode.
El recurso (CSS/JS) no se carga en una página de shortcode — el plugin detecta los shortcodes y la bandera $as24ci_render_mode para cargar los recursos. Si un maquetador (builder) almacena en caché la salida de la página, fuerce la limpieza de esa caché después de editar la página para que el shortcode sea detectado durante la cola de reproducción (enqueue).