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). Detection also works through the stable output-page IDs stored by the setup wizard (as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id), so a configured archive/compare/favorites page still loads its CSS even when the shortcode itself is not parseable from the queried content. - 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 5a: Vehicle cards are intermittently left-aligned instead of centered (page cache)

The archive, compare and favorites pages center their card grid through their own stylesheets (as24ci-archive.css, as24ci-compare.css, as24ci-favorites.css). If the cards stand centered after some reloads and left-aligned after others — i.e. a plain reload flips the alignment — the page's <head> is intermittently missing the plugin stylesheet <link>. This is an asset-loading / caching symptom, not a theme layout problem.

Confirm which case you have. In the left-aligned state, view the page source or the Network tab and search for an as24ci-…​.css stylesheet link:

• The <link …​ as24ci-archive.css> (or compare/favorites) is absent → the cached HTML snapshot was generated without the stylesheet being enqueued. This is the enqueue/cache case below.
• The link is present but the cards are still left-aligned → look for a theme/plugin rule overriding .as24ci-archive-inner / .as24ci-favorites-inner / .as24ci-compare-inner (these set margin: 0 auto) or forcing the card grid to a single column.

Why it happens. A full-page or minify/combine cache freezes whatever HTML was generated for that request. If a snapshot is generated at a moment when asset detection fails (for example, another plugin or widget repointed the global $post before wp_head), the snapshot is stored without the stylesheet link, and every visitor served that snapshot sees left-aligned cards until the cache is rebuilt.

What the plugin already does. Detection now uses the stable output-page IDs plus the queried object (not only has_shortcode() against the global $post), so the stylesheet is enqueued deterministically on every render. In addition, a tiny inline critical-CSS block (<style id="as24ci-critical-centering">) is printed in the <head> of these pages; because it is inline it travels inside the cached HTML and keeps the cards centered even if a minifier later drops the external stylesheet file.

What to do after activating or updating the plugin. Purge / rebuild the page cache once so no pre-fix “CSS-less” snapshot remains in circulation:

1. In your caching plugin (WP Rocket, W3 Total Cache, WP Super Cache, LiteSpeed Cache, or a hosting/Plesk page cache), run Clear / Purge all cache.
2. If an object cache is in use (Redis/Memcached), flush it as well.
3. Reload each demo page (inventory, compare, favorites) several times and confirm the cards stay centered and that the as24ci-…​.css link is present every time.

If a non-standard cache still serves a stale snapshot, exclude the three demo pages from the full-page cache (most cache plugins have a “Never cache the following pages” list — add the inventory, compare and favorites URLs). This is normally unnecessary once the cache has been rebuilt, because the inline critical CSS keeps the layout correct even in a cached snapshot.

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