Frontend Display Issues

This document covers problems with how vehicle listings are displayed on the public-facing pages of a WordPress site using the ADP Car Market Hub plugin. It addresses archive pages, single vehicle detail pages, theme conflicts, permalink issues and asset loading problems.

When to use this document

Read this document when:

• The vehicle archive page (/cars/ or the configured slug) shows no listings, a 404 error, or is not found.
• Single vehicle detail pages are not displaying or are missing layout and styling.
• Filters on the archive page do not work or do not return expected results.
• Plugin CSS or JavaScript is not loading on frontend pages.
• The active theme overrides or conflicts with plugin templates.
• Pagination on the archive or a shortcode-embedded listing page does not work.

Overview

The plugin registers a custom post type (as24ci_car) with the archive slug cars and provides two template files:

• templates/archive-as24ci_car.php — used for the vehicle archive page.
• templates/single-as24ci_car.php — used for individual vehicle detail pages.

WordPress resolves templates using the standard template hierarchy. The plugin hooks into single_template and archive_template filters. It first checks whether the active theme provides a custom override (single-as24ci_car.php or archive-as24ci_car.php in the theme directory), and uses the plugin's own template as a fallback. This means a theme can fully control the layout if it provides a matching template file.

CSS and JavaScript are enqueued automatically by detecting the current page type. On pages where a shortcode is used to embed the archive, assets are detected via has_shortcode() against the page's post content.

Prerequisites

• At least one vehicle post exists and is published.
• Permalinks are set to something other than "Plain" (for archive routing to work correctly). Go to Settings → Permalinks and choose any option other than the default "Plain" setting, then click Save Changes.
• The plugin is active and no PHP fatal errors are present (check Tools → Site Health or the PHP error log).

Diagnostic steps

Step 1: Flush permalinks

Most archive 404 errors are caused by stale permalink rules. This is the first thing to try whenever the vehicle archive or single pages return a 404 error.

1. Go to Settings → Permalinks in the WordPress admin.
2. Click Save Changes without changing any settings. This rebuilds the rewrite rules.
3. Visit the vehicle archive URL (typically /cars/) and confirm it loads.

Step 2: Confirm the vehicle archive URL

The plugin registers the CPT with the archive slug cars. The archive URL is typically:

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

If WordPress is installed in a subdirectory, or the permalink structure uses a prefix, the archive URL will reflect that. Use get_post_type_archive_link('as24ci_car') (via WP-CLI or a test snippet) to confirm the exact URL.

Step 3: Check whether the CPT archive is enabled

The custom post type is registered with has_archive = true. If WordPress does not route to the archive, confirm:

1. Permalinks are not set to "Plain". Plain permalinks disable CPT archive routing.
2. No caching plugin is serving a stale 404 response for the archive URL. Purge the cache after flushing permalinks.
3. No .htaccess rule or server configuration is blocking the archive URL.

Step 4: Check for theme conflicts

If the archive or single template renders incorrectly, a theme conflict may be responsible:

1. Temporarily switch to a default WordPress theme (such as Twenty Twenty-Four) and visit the vehicle archive and a single vehicle page.
2. If the pages display correctly with the default theme, your active theme is causing a conflict.
3. Common causes: the active theme provides its own archive-as24ci_car.php or single-as24ci_car.php template that is outdated or incompatible; the theme outputs incorrect HTML structure around content; the theme's own CSS conflicts with the plugin's styles.

Step 5: Check that CSS and JavaScript are loading

If the vehicle archive or single page shows unstyled content or non-functional interactive elements (filter dropdowns, gallery, lightbox):

1. Open the page in a browser and view the page source or use the browser's developer tools (Network tab).
2. Confirm the plugin stylesheets are present: - On archive pages: as24ci-archive.css - On single vehicle pages: as24ci-single.css
3. If these are missing: - Confirm the page is correctly recognized as the CPT archive or a singular CPT post. - If using a shortcode to embed the archive on a regular page, confirm the shortcode [as24ci_archive] is in the page's post content (not in a widget, template part or custom field processed outside of the_content). Assets are detected by reading the post content with has_shortcode(). - If a performance or minification plugin concatenates or defers scripts, it may interfere with the plugin's JavaScript. Test with that plugin deactivated.
4. Confirm that no other plugin or theme is calling wp_dequeue_style or wp_dequeue_script for plugin assets.

Step 6: Verify the archive filter behavior

The vehicle archive supports filter parameters passed via the URL query string (e.g. ?make=volkswagen&fuel_type=diesel). If filters do not work:

1. Confirm the filter widgets are displayed (they are rendered by the archive template).
2. Confirm that the specific filter is enabled in the plugin's Filter or Layout Manager settings. Disabled filters will not appear and their GET parameters will be ignored.
3. Confirm there is no caching layer serving a cached version of the archive page regardless of query parameters. Most caching plugins must be configured to exclude pages with query strings from being cached.

Step 7: Investigate pagination issues

If pagination on the archive page does not work (clicking page 2 returns the same results):

1. Confirm the permalink structure is not "Plain".
2. On shortcode-embedded archive pages, pagination uses ?paged=2 (or ?page=2) query parameters. Confirm there is no redirect stripping these parameters.
3. On the real CPT archive URL, WordPress handles pagination natively. Flush permalinks if it is broken.

Step 8: Check for PHP errors

A PHP fatal error or warning can break the page output silently or cause a partial render:

1. Enable WordPress debug mode temporarily by adding to wp-config.php: ``php define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false ); ``
2. Visit the problem page and check wp-content/debug.log for errors.
3. Disable debug mode again after investigating.

Configuration reference

Operational notes

• The plugin template files are located in the templates/ directory of the plugin. Do not edit these files directly, as updates will overwrite your changes. To customize templates, copy them into your active theme directory and edit the copy there.
• The archive template resolves filter values using WordPress taxonomies (as24ci_brand, as24ci_model, as24ci_fuel_type, etc.) and a custom database table (wp_as24_vehicles) for numeric fields such as price and mileage.
• If the archive page is embedded using the [as24ci_archive] shortcode on a standard WordPress page, the page must not have its own query loop or content that interferes with the $wp_query global. The shortcode temporarily replaces $wp_query during rendering and restores it afterward.
• Dynamic CSS (design settings such as colors) is output inline in the <head> tag via a wp_head action with priority 99.

Troubleshooting

Related documents

• Troubleshooting Overview
• Shortcode Issues
• Image Import Errors
• Permission Errors