Problemas de visualización en el frontend

Este documento cubre los problemas con la forma en que se muestran los listados de vehículos en las páginas públicas de un sitio de WordPress utilizando el plugin ADP Car Market Hub. Aborda las páginas de archivo, las páginas de detalles de vehículos individuales, los conflictos de temas, los problemas de enlaces permanentes y los problemas de carga de recursos.

Cuándo usar este documento

Lea este documento cuando:

• La página de archivo de vehículos (/cars/ o el slug configurado) no muestra listados, devuelve un error 404 o no se encuentra.
• Las páginas de detalles de vehículos individuales no se muestran o carecen de diseño y estilos.
• Los filtros en la página de archivo no funcionan o no devuelven los resultados esperados.
• El CSS o JavaScript del plugin no se carga en las páginas del frontend.
• El tema activo anula o entra en conflicto con las plantillas del plugin.
• La paginación en el archivo o en una página con un listado incrustado mediante shortcode no funciona.

Descripción general

El plugin registra un tipo de contenido personalizado o CPT (as24ci_car) con el slug de archivo cars y proporciona dos archivos de plantilla:

• templates/archive-as24ci_car.php — utilizado para la página de archivo de vehículos.
• templates/single-as24ci_car.php — utilizado para las páginas de detalles de vehículos individuales.

WordPress resuelve las plantillas utilizando la jerarquía de plantillas estándar. El plugin se engancha en los filtros single_template y archive_template. Primero comprueba si el tema activo proporciona una invalidación personalizada (single-as24ci_car.php o archive-as24ci_car.php en el directorio del tema), y utiliza la propia plantilla del plugin como alternativa de reserva. Esto significa que un tema puede controlar completamente el diseño si proporciona un archivo de plantilla coincidente.

El CSS y el JavaScript se encolan automáticamente al detectar el tipo de página actual. En las páginas donde se utiliza un shortcode para incrustar el archivo, los recursos se detectan a través de has_shortcode() contra el contenido de la entrada de la página.

Requisitos previos

• Existe al menos una entrada de vehículo y está publicada.
• Los enlaces permanentes están configurados con una opción diferente de "Simple" (para que el enrutamiento del archivo funcione correctamente). Vaya a Ajustes → Enlaces permanentes y elija cualquier opción que no sea la configuración predeterminada "Simple", luego haga clic en Guardar cambios.
• El plugin está activo y no hay errores fatales de PHP (compruebe Herramientas → Salud del sitio o el registro de errores de PHP).

Pasos de diagnóstico

Paso 1: Regenerar los enlaces permanentes

La mayoría de los errores 404 de archivo se deben a reglas de enlaces permanentes desactualizadas. Esto es lo primero que debe intentar siempre que el archivo de vehículos o las páginas individuales devuelvan un error 404.

1. Vaya a Ajustes → Enlaces permanentes en el panel de administración de WordPress.
2. Haga clic en Guardar cambios sin modificar ningún ajuste. Esto reconstruye las reglas de reescritura.
3. Visite la URL del archivo de vehículos (normalmente /cars/) y confirme que se carga.

Paso 2: Confirmar la URL del archivo de vehículos

El plugin registra el CPT con el slug de archivo cars. La URL del archivo suele ser:

https://your-site.example.com/cars/

Si WordPress está instalado en un subdirectorio, o la estructura de enlaces permanentes utiliza un prefijo, la URL del archivo lo reflejará. Utilice get_post_type_archive_link('as24ci_car') (a través de WP-CLI o un fragmento de código de prueba) para confirmar la URL exacta.

Paso 3: Comprobar si el archivo del CPT está habilitado

El tipo de contenido personalizado se registra con has_archive = true. Si WordPress no enruta al archivo, confirme:

1. Los enlaces permanentes no están configurados como "Simple". Los enlaces permanentes simples desactivan el enrutamiento de archivos de CPT.
2. Ningún plugin de caché está sirviendo una respuesta 404 desactualizada para la URL del archivo. Vacíe la caché después de regenerar los enlaces permanentes.
3. Ninguna regla de .htaccess o configuración del servidor está bloqueando la URL del archivo.

Paso 4: Comprobar si hay conflictos con el tema

Si la plantilla de archivo o la plantilla individual se representan incorrectamente, la causa puede ser un conflicto con el tema:

1. Cambie temporalmente a un tema predeterminado de WordPress (como Twenty Twenty-Four) y visite el archivo de vehículos y una página de vehículo individual.
2. Si las páginas se muestran correctamente con el tema predeterminado, su tema activo está causando un conflicto.
3. Causas comunes: el tema activo proporciona su propia plantilla archive-as24ci_car.php o single-as24ci_car.php que está desactualizada o es incompatible; el tema genera una estructura HTML incorrecta alrededor del contenido; el propio CSS del tema entra en conflicto con los estilos del plugin.

Paso 5: Comprobar que el CSS y el JavaScript se están cargando

Si el archivo de vehículos o la página individual muestran contenido sin estilos o elementos interactivos que no funcionan (desplegables de filtros, galería, lightbox):

1. Abra la página en un navegador y vea el código fuente de la página o utilice las herramientas de desarrollo del navegador (pestaña Red).
2. Confirme que las hojas de estilo del plugin están presentes: - En páginas de archivo: as24ci-archive.css - En páginas de vehículos individuales: as24ci-single.css
3. Si faltan: - Confirme que la página se reconoce correctamente como el archivo del CPT o como una entrada individual del CPT. - Si utiliza un shortcode para incrustar el archivo en una página normal, confirme que el shortcode [as24ci_archive] está en el contenido de la entrada de la página (no en un widget, parte de plantilla o campo personalizado procesado fuera de the_content). Los recursos se detectan leyendo el contenido de la entrada con has_shortcode(). - Si un plugin de rendimiento o de minificación concatena o pospone scripts, puede interferir con el JavaScript del plugin. Realice una prueba desactivando dicho plugin.
4. Confirme que ningún otro plugin o tema esté llamando a wp_dequeue_style o wp_dequeue_script para los recursos del plugin.

Paso 6: Verificar el comportamiento de los filtros del archivo

El archivo de vehículos admite parámetros de filtro pasados a través de la cadena de consulta de la URL (por ejemplo, ?make=volkswagen&fuel_type=diesel). Si los filtros no funcionan:

1. Confirme que se muestran los widgets de filtro (se representan mediante la plantilla de archivo).
2. Confirme que el filtro específico está habilitado en los ajustes de Filtro o del Gestor de diseño del plugin. Los filtros desactivados no aparecerán y se ignorarán sus parámetros GET.
3. Confirme que no haya ninguna capa de caché sirviendo una versión almacenada en caché de la página de archivo independientemente de los parámetros de consulta. La mayoría de los plugins de caché deben configurarse para excluir del almacenamiento en caché las páginas con cadenas de consulta.

Paso 7: Investigar problemas de paginación

Si la paginación en la página de archivo no funciona (al hacer clic en la página 2 se devuelven los mismos resultados):

1. Confirme que la estructura de enlaces permanentes no sea "Simple".
2. En las páginas de archivo incrustadas mediante shortcode, la paginación utiliza los parámetros de consulta ?paged=2 (o ?page=2). Confirme que no haya ninguna redirección que elimine estos parámetros.
3. En la URL real del archivo del CPT, WordPress gestiona la paginación de forma nativa. Regenere los enlaces permanentes si no funciona.

Paso 8: Comprobar si hay errores de PHP

Un error fatal o una advertencia de PHP pueden interrumpir silenciosamente la salida de la página o causar una representación parcial:

1. Habilite temporalmente el modo de depuración de WordPress añadiendo lo siguiente a wp-config.php: ``php define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false ); ``
2. Visite la página con problemas y compruebe wp-content/debug.log en busca de errores.
3. Desactive de nuevo el modo de depuración después de realizar la investigación.

Referencia de configuración

Notas operativas

• Los archivos de plantilla del plugin se encuentran en el directorio templates/ del plugin. No edite estos archivos directamente, ya que las actualizaciones sobrescribirán sus cambios. Para personalizar las plantillas, cópielas en el directorio de su tema activo y edite la copia allí.
• La plantilla de archivo resuelve los valores de los filtros utilizando taxonomías de WordPress (as24ci_brand, as24ci_model, as24ci_fuel_type, etc.) y una tabla de base de datos personalizada (wp_as24_vehicles) para campos numéricos como el precio y el kilometraje.
• Si la página de archivo se incrusta utilizando el shortcode [as24ci_archive] en una página estándar de WordPress, la página no debe tener su propio bucle de consulta o contenido que interfiera con la variable global $wp_query. El shortcode reemplaza temporalmente a $wp_query durante la representación y lo restaura después.
• El CSS dinámico (ajustes de diseño como los colores) se genera en línea en la etiqueta <head> a través de una acción wp_head con prioridad 99.

Resolución de problemas

Documentos relacionados

• Descripción general de la resolución de problemas
• Problemas con shortcodes
• Errores de importación de imágenes
• Errores de permisos