Documentación · Guía de integración

Integración con constructores de páginas

Este documento explica cómo usar el plugin ADP Car Market Hub dentro de los flujos de trabajo de los constructores de páginas, cómo colocar shortcodes en páginas creadas con cualquier editor de páginas y qué validar en el front-end después de su colocación.

Cuándo usar este documento

Use este documento si está:

Incrustando listados de vehículos, filtros de búsqueda o la herramienta de comparación en páginas creadas con un constructor de páginas como Elementor, WPBakery, Divi, Beaver Builder o el editor de bloques de WordPress (Gutenberg).
Creando una página de inicio personalizada o una página de destino que deba mostrar un subconjunto filtrado del inventario de vehículos.
Colocando un filtro de búsqueda independiente en una página para que los visitantes puedan comenzar a filtrar antes de navegar a la página de resultados.
Diagnosticando problemas en los que los assets del plugin no se cargan correctamente en una página del constructor de páginas.

El público objetivo es un administrador de WordPress o un creador de sitios. No se requieren conocimientos de PHP o CSS para la colocación básica de shortcodes.

Descripción general

El plugin proporciona tres shortcodes para el front-end que puede colocar en cualquier página de WordPress, incluidas las páginas creadas con constructores de páginas de terceros:

Shortcode	Qué renderiza
`[as24ci_archive]`	Listado completo de vehículos con filtros de búsqueda, controles de ordenación, pestañas de estado y paginación. Equivalente a la página de archivo de vehículos.
`[as24ci_search_filter]`	Formulario de filtro de búsqueda independiente sin resultados. Se envía al archivo de vehículos o a cualquier página de resultados que especifique.
`[as24ci_compare]`	Tabla de comparación de vehículos. Depende de que el visitante haya añadido vehículos a la lista de comparación.

Existen shortcodes adicionales disponibles para características secundarias:

Shortcode	Qué renderiza
`[as24ci_favorites]`	Lista de vehículos que el visitante ha marcado como favoritos.
`[as24ci_location_box post_id=""]`	Tarjeta de ubicación del concesionario para la entrada de ubicación (Location) especificada.
`[as24ci_hours_box post_id=""]`	Tarjeta de horarios de apertura para la entrada de ubicación (Location) especificada.

Estos shortcodes funcionan en cualquier constructor de páginas que admita los shortcodes estándar de WordPress. El resultado es el mismo que el de las páginas correspondientes gestionadas por el plugin.

Requisitos previos

Antes de colocar los shortcodes:

El plugin está instalado y activado.
Se ha importado al menos un vehículo (para [as24ci_archive] y [as24ci_search_filter]).
Los enlaces permanentes amigables están activados (Ajustes → Enlaces permanentes). Sin enlaces permanentes amigables, la URL del archivo de vehículos podría no resolverse correctamente cuando [as24ci_search_filter] redirige a un visitante a la página de resultados.
Si está utilizando el Editor de bloques (Gutenberg), no se necesita ninguna configuración adicional. Si está utilizando un constructor de páginas de terceros, verifique que conserve los shortcodes de WordPress sin codificar ni escapar los corchetes.

Instrucciones paso a paso

Incrustar el archivo de vehículos en una página

Cree una nueva página o abra una página existente en su constructor de páginas.
Añada un bloque de shortcode (o su equivalente en su constructor de páginas; por ejemplo, Elementor tiene un widget de Shortcode, WPBakery tiene un elemento Imagen única → Shortcode, Divi tiene un módulo de Código, etc.).
Pegue el shortcode:

   [as24ci_archive]

Para prefiltrar el listado (por ejemplo, para mostrar solo vehículos eléctricos), use los atributos opcionales del shortcode:

   [as24ci_archive fuel="electric" per_page="24"]

Atributos admitidos:

Atributo	Valores	Descripción
`make`	Cualquier slug de marca (p. ej., `bmw`)	Preselecciona una marca.
`model`	Cualquier slug de modelo (p. ej., `3-series`)	Preselecciona un modelo (usar con `make`).
`price_min`	Entero	Filtro de precio mínimo.
`price_max`	Entero	Filtro de precio máximo.
`fuel`	Cualquier slug de tipo de combustible	Preselecciona un tipo de combustible.
`body`	Cualquier slug de tipo de carrocería	Preselecciona un tipo de carrocería.
`order_by`	`price`, `mileage`, `date`	Campo de ordenación por defecto.
`order`	`asc`, `desc`	Dirección de ordenación. Por defecto `asc`.
`per_page`	`12`, `24`, `48`, `72`, `all`	Resultados por página. Por defecto `24`.

Los atributos del shortcode establecen los valores por defecto. Los visitantes aún pueden sobrescribirlos interactuando con los filtros de la página. Los parámetros de consulta de la URL siempre tienen prioridad sobre los atributos del shortcode.

Publique o previsualice la página y confirme que aparece el listado de vehículos.

Incrustar un filtro de búsqueda independiente

Coloque [as24ci_search_filter] en cualquier lugar de una página (por ejemplo, en la página de inicio) para permitir que los visitantes establezcan sus criterios antes de ser dirigidos a la página de resultados.

[as24ci_search_filter results_url="/cars/"]

El atributo results_url especifica a dónde se envía el formulario. Por defecto, es la URL del archivo de vehículos. Establézcalo en la URL de cualquier página que contenga [as24ci_archive].
Si el plugin no puede determinar la URL del archivo automáticamente y results_url no está configurado, el formulario se dirigirá por defecto a /cars/.

Usar la página de comparación como plantilla

La página de comparación es una plantilla de página especial de WordPress (page-as24ci_compare.php). El plugin puede crear una página de Comparación automáticamente durante la instalación. También puede colocar [as24ci_compare] en un bloque de shortcode en cualquier página normal para incrustar la tabla de comparación en línea.

Referencia de configuración

Todos los shortcodes utilizan los ajustes ya definidos en la administración del plugin. No hay campos de configuración separados para el modo de constructor de páginas.

Atributo de shortcode	De dónde provienen las opciones subyacentes
Qué filtros aparecen en `[as24ci_archive]` y `[as24ci_search_filter]`	El diseño de filtros activo configurado en la pestaña Filtros de la administración del plugin.
Diseño visual de todos los shortcodes	Car Market Hub → Diseño — colores, tipografía, radio del borde, etc.
Flags de características (favoritos, comparación, alerta de búsqueda)	Car Market Hub → Ajustes (y el Asistente de configuración). Si una característica está desactivada, el shortcode correspondiente no renderiza nada o muestra un mensaje.

Carga de assets

El plugin detecta si un shortcode está presente en la página actual utilizando la función has_shortcode() de WordPress, y encola los archivos CSS y JavaScript correspondientes de forma automática. No es necesario configurar manualmente la carga de assets.

En las páginas que utilizan [as24ci_archive] o [as24ci_compare], se encolan las siguientes hojas de estilo:

as24ci-archive.css — para [as24ci_archive]
as24ci-compare.css — para [as24ci_compare] y para el botón de comparación en las páginas de archivo y de detalle único
as24ci-search-agent.css — cuando la característica de Alerta de búsqueda está activada

El bloque de CSS de diseño dinámico (<style id="as24ci-dynamic-styles">) se genera en <head> en cada página del front-end, no solo en las páginas específicas del plugin.

Notas de funcionamiento

Paginación en páginas con shortcodes. El shortcode [as24ci_archive] lee los parámetros de consulta ?paged= y ?page= para la paginación. Cuando un constructor de páginas o un tema utiliza esos parámetros para sus propios fines, puede haber un conflicto. Pruebe la paginación en la página en su contexto final.
Enlaces permanentes simples. Con los enlaces permanentes simples (cadena de consulta) activados, is_post_type_archive() devuelve false para el archivo del plugin. El plugin recurre a la detección de has_shortcode(), por lo que el CSS y el JavaScript se siguen cargando. Sin embargo, el results_url para [as24ci_search_filter] podría no resolverse correctamente; prefiera enlaces permanentes amigables en producción.
Renderizado de contenido del constructor de páginas. Algunos constructores de páginas renderizan los shortcodes en el servidor (estándar de do_shortcode) y otros los renderizan a través de Ajax o en el cliente. Los shortcodes del plugin dependen del renderizado estándar del lado del servidor. Si un constructor de páginas pospone el renderizado al lado del cliente, el resultado puede aparecer vacío en la vista previa del constructor, pero debería mostrarse correctamente en el front-end publicado.
Shortcodes anidados. No anide los shortcodes del plugin unos dentro de otros. Cada shortcode gestiona su propia WP_Query y su estado global.
Diseño de ancho completo. Al igual que las plantillas de archivo y de detalle único del propio plugin, el resultado del shortcode envuelve todo dentro de .as24ci-page.alignfull. En los temas de bloques, esto hace que el listado se extienda a todo el ancho. Si el constructor de páginas restringe la página a un contenedor más estrecho, el contenido del shortcode se verá limitado por ese contenedor. Consulte la Guía de integración de temas para obtener más detalles.
Posición del filtro de búsqueda. El shortcode [as24ci_search_filter] renderiza el formulario de filtro pero no una lista de resultados. Cuando se coloca en la página de inicio, la acción del formulario debe apuntar a una página separada que contenga [as24ci_archive].

Resolución de problemas

Síntoma	Causa probable	Qué comprobar
El shortcode se renderiza como texto literal (`[as24ci_archive]`).	El constructor de páginas está escapando o codificando el shortcode en lugar de ejecutarlo.	Use el widget de Shortcode dedicado del constructor de páginas o el bloque de Código en lugar de un bloque de texto plano.
El shortcode de archivo no muestra vehículos.	Aún no se han importado vehículos, o los atributos de prefiltrado en el shortcode no coinciden con ningún vehículo.	Importe vehículos primero. Compruebe los valores de los atributos con los datos reales en Car Market Hub → Cars.
El CSS no se aplica en la página del shortcode.	El constructor de páginas elimina o pospone las hojas de estilo del plugin.	Compruebe las herramientas de desarrollo del navegador → pestaña Red para ver si falta la hoja de estilo `as24ci-archive` o `as24ci-single`. Si falta, compruebe si el constructor de páginas tiene una opción para conservar los assets de terceros.
Falta el CSS dinámico (`as24ci-dynamic-styles`).	Un plugin de caché u optimización está eliminando los bloques inline de `<style>` de `<head>`.	Excluya `as24ci-dynamic-styles` de la regla de optimización o añada los identificadores de `as24ci-*` a la lista de permitidos.
La paginación no funciona en la página del shortcode de archivo.	El parámetro `?paged=` está siendo consumido o reescrito por el tema o el constructor de páginas.	Pruebe con la navegación por URL simple. Compruebe si el tema o el constructor de páginas intercepta los parámetros de consulta.
`[as24ci_search_filter]` se envía a la URL incorrecta.	El atributo `results_url` falta o apunta a una página sin `[as24ci_archive]`.	Añada `results_url="/cars/"` (o la ruta correcta) al shortcode.