Sistema de plantillas y personalizaciones

Este documento describe cómo el plugin ADP Car Market Hub carga sus plantillas del frontend y cómo un tema puede sobrescribirlas. Enumera los archivos incluidos en la carpeta templates/ del plugin y explica cuáles se pueden sobrescribir a través de la jerarquía de plantillas estándar de WordPress y cuáles se cargan directamente mediante shortcodes.

Cuándo utilizar este documento

Lea este documento cuando necesite:

• Personalizar el marcado de la página individual del vehículo, el archivo de vehículos o la página de comparación desde un tema o tema hijo.
• Reemplazar una pequeña parte (por ejemplo, el formulario de filtro de búsqueda) sin tener que duplicar toda la plantilla.
• Entender qué archivos de plantilla es seguro sobrescribir y cuáles cambian entre versiones.

Para conocer los tipos de contenido personalizados (post types) y las taxonomías que representan estas plantillas, consulte Custom Post Types And Taxonomies. Para los shortcodes que cargan partes de plantilla directamente, consulte Shortcodes For Developers.

Descripción general

El plugin incluye sus plantillas en la carpeta templates/ del plugin. Dos mecanismos las exponen:

1. Filtros de la jerarquía de plantillas de WordPress. El plugin se engancha a single_template y archive_template. Para ambos filtros, primero llama a locate_template() para que un tema activo o tema hijo pueda proporcionar su propia copia del archivo. Si no se encuentra ninguna personalización en el tema, se utiliza la plantilla integrada del plugin.
2. Renderizado directo de shortcodes. Los shortcodes para la página de comparación ([as24ci_compare]) y el filtro de búsqueda independiente ([as24ci_search_filter]) cargan sus plantillas directamente desde la carpeta templates/ del plugin. No consultan al tema para una posible sobrescritura.

El resultado es que la página de vehículo individual y el archivo de vehículos se pueden sobrescribir limpiamente colocando un archivo en el tema activo, mientras que la página de comparación y la parte del filtro de búsqueda solo cambian cuando se modifica o filtra su salida a través de un mecanismo diferente.

Archivos incluidos en templates/

Plantillas de nivel superior:

• archive-as24ci_car.php — listado de archivo de vehículos.
• single-as24ci_car.php — página individual de vehículo (diseño por defecto).
• single-as24ci_car-classic.php — diseño individual alternativo "clásico".
• page-as24ci_compare.php — página de comparación renderizada por [as24ci_compare].

Partes de plantilla (partials) y recursos:

• parts/search-filter.php — el formulario de filtro de búsqueda renderizado por [as24ci_search_filter].
• icons/ — definiciones de iconos SVG utilizados por las plantillas.
• css/ y js/ — hojas de estilo y scripts del frontend que se envían junto con las plantillas y que el cargador de recursos encola (consulte Frontend Assets).

Plantillas que se pueden sobrescribir desde el tema

Estos archivos se cargan a través de los filtros single_template / archive_template y, por lo tanto, respetan el tema:

El plugin llama a locate_template( '<file-name>.php' ) sin prefijo de subdirectorio, por lo que el archivo de sobrescritura va directamente en la raíz del tema activo (o en la raíz del tema hijo). Si locate_template() devuelve una ruta, el plugin la utiliza; de lo contrario, recurre a la plantilla integrada.

Plantillas que no se cargan a través de la jerarquía del tema

Estos archivos son cargados directamente por el plugin y locate_template() no los detecta:

Para personalizar estos elementos, tiene tres opciones fiables:

1. Cree una página o plantilla contenedora en su tema que llame al shortcode correspondiente y envuelva su salida con su propio marcado.
2. Utilice los hooks de acción y filtro que expone el plugin (consulte Hooks And Filters, Actions Reference, Filters Reference) para alterar el comportamiento en lugar del marcado.
3. Como último recurso, duplique el archivo en su tema y cárguelo desde su propia plantilla; en ese caso, asumirá la responsabilidad de mantenerlo alineado con las futuras versiones del plugin.

Instrucciones paso a paso

Sobrescribir la página individual de vehículo

1. Copie single-as24ci_car.php desde la carpeta templates/ del plugin.
2. Péguelo en la raíz de su tema activo (o tema hijo).
3. Edite la copia para realizar sus cambios.
4. Recargue una página de vehículo individual. WordPress cargará su archivo a través de locate_template() en lugar del archivo integrado del plugin.

Sobrescribir el archivo de vehículos

1. Copie archive-as24ci_car.php desde la carpeta templates/ del plugin.
2. Péguelo en la raíz de su tema activo (o tema hijo).
3. Edite la copia. Recargue la página de archivo (/cars/ por defecto) para ver su versión.

Personalizar la página de comparación o el formulario de filtro de búsqueda

1. Envuelva el shortcode correspondiente en una plantilla de página personalizada o diseño de bloques en su tema, o bien duplique la plantilla subyacente en su tema y cárguela desde su propia plantilla.
2. Verifique que los recursos del plugin de los que depende (CSS/JS, consulte Frontend Assets) sigan encolados en su página personalizada.

Notas de funcionamiento

• Utilice un tema hijo. Coloque las sobrescrituras en un tema hijo para evitar perderlas cuando se actualice el tema padre.
• Interacción con el gestor de diseño. El plugin incluye un gestor de diseño que organiza los bloques dentro de las páginas de archivo y de vehículo individual, configurado desde la interfaz de administración del plugin. Si reemplaza por completo la plantilla individual o de archivo, también omitirá el gestor de diseño. Utilice modificaciones selectivas basadas en hooks cuando necesite mantener ese comportamiento.
• Activación de la página de comparación. La página de comparación se crea al activar el plugin. La página en sí simplemente contiene el shortcode [as24ci_compare], por lo que su contenido es renderizado por la plantilla del plugin, no por single_template / archive_template.
• Shortcode en cualquier página. Debido a que [as24ci_archive] reutiliza el renderizador de archivos, puede incrustar el listado en cualquier página de WordPress o diseño de bloques sin necesidad de sobrescribir la plantilla de archivo en absoluto.
• Encolado de recursos. Los archivos CSS y JavaScript del frontend que se envían con el plugin se encolan de forma condicional según la página actual (página individual, archivo, uso de shortcodes). Si crea una plantilla contenedora personalizada que no coincide con las condiciones estándar, es posible que los recursos del plugin correspondientes no se encolen automáticamente.
• Verifique el comportamiento en la versión actual del plugin antes de publicar un tema personalizado. La estructura de las plantillas y el marcado de los bloques pueden cambiar entre versiones.

Resolución de problemas

• Se ignora la sobrescritura de mi tema. Confirme que el nombre del archivo coincide exactamente (single-as24ci_car.php, archive-as24ci_car.php) y que se encuentra en la raíz del tema activo. Limpie cualquier caché de objetos o de página.
• La página individual muestra el diseño clásico (o viceversa). El diseño individual se selecciona desde los ajustes de diseño del plugin en la interfaz de administración. Cámbielo allí en lugar de hacerlo desde el tema.
• La página de comparación no muestra nada o da un error 404. Confirme que la página de comparación todavía existe, contiene el shortcode [as24ci_compare] y está publicada. Confirme que la función de comparación está activada en la interfaz de administración del plugin.
• Falta un script o estilo del frontend en una página contenedora personalizada. El cargador de recursos del plugin se basa en la detección del tipo de contenido, el archivo y los shortcodes. Utilice los shortcodes oficiales dentro de su contenedor para que los recursos correspondientes se encolen automáticamente.
• Verifique el comportamiento en la versión actual del plugin antes de publicar una integración personalizada. Las rutas de las plantillas y el marcado pueden evolucionar entre versiones.

Documentos relacionados

• Custom Post Types And Taxonomies
• Shortcodes For Developers
• Frontend Assets
• Hooks And Filters
• Filters Reference