Theme Integration

This document explains how the ADP Car Market Hub plugin integrates with the active WordPress theme, what to validate after installation or a theme switch, and how to resolve the most common layout conflicts.

When to use this document

Use this document if you are:

• Installing the plugin on a site and validating that the vehicle pages render correctly with the active theme.
• Switching themes on an existing site and checking that plugin output is unaffected.
• Diagnosing layout problems on the vehicle archive, single vehicle, or compare pages.
• A developer integrating a custom theme with the plugin.

The audience is a WordPress administrator, developer, or theme integrator. Familiarity with WordPress theme files and browser developer tools is helpful for the troubleshooting sections.

Overview

The plugin registers the as24ci_car custom post type with has_archive = true and a URL slug of cars. It provides its own PHP templates for the vehicle archive, single vehicle detail, and compare pages. Those templates call the standard WordPress get_header() and get_footer() functions, so the active theme's navigation, header, and footer are always used. The plugin only controls the content area between header and footer.

All plugin-generated content is wrapped in a <div class="as24ci-page"> element. On archive pages the element also carries the class as24ci-archive-page. On single vehicle pages it carries as24ci-page-classic. Both carry the alignfull class, which signals to block-based and full-site editing themes that the element should span the full viewport width.

The plugin enqueues its own CSS files (scoped to as24ci-page selectors) and outputs a <style id="as24ci-dynamic-styles"> block via wp_head at priority 99 with design values from Car Market Hub → Design. Typography rules inside that block are always scoped to .as24ci-page-classic so they never affect theme elements outside the plugin wrapper.

Prerequisites

Before validating theme integration:

• The plugin is installed and activated and at least one vehicle has been imported. See Installation Guide.
• Pretty permalinks are enabled (Settings → Permalinks → Post name or any non-plain option). Plain (query-string) permalinks require extra configuration to make the vehicle archive URL work correctly.
• You have access to the WordPress front end in a browser.

Step by step validation checklist

Run these checks after initial installation or after changing the active theme.

1. Vehicle archive page. Visit the vehicle archive URL (typically /cars/). Confirm that: - The theme header and footer are visible. - Vehicle listing cards are displayed inside the theme's content area. - The search filters above the listing are visible. - No PHP errors or unstyled HTML is visible.
2. Single vehicle page. Click through to any vehicle detail page. Confirm that: - The theme header and footer are present. - The vehicle image gallery, title, price, and specification table render correctly. - The contact form is visible and functional.
3. Full-width layout. The plugin wrapper carries the alignfull class. On block themes and full-site editing themes, this class typically causes the element to extend to the viewport edge. Check that the plugin content does not overflow or introduce a horizontal scroll bar.
4. Typography inheritance. The plugin's CSS uses font-family: inherit and font-size: inherit as defaults for body text inside .as24ci-page. If the theme sets a custom font on body or on a parent element, the plugin will inherit it. Check that the inherited typeface looks acceptable on vehicle pages.
5. Responsive check. Resize the browser window to phone and tablet breakpoints. Confirm that the filter sidebar, the vehicle grid, and the single vehicle layout are legible at small screen widths.
6. Compare page. If the Compare feature is enabled (Car Market Hub → Settings, or in the Setup Wizard), verify that the comparison page renders correctly.

Configuration reference

The settings that affect how the plugin output looks alongside the active theme are in Car Market Hub → Design.

Operational notes

• Theme templates take priority. If the active theme (or child theme) contains a file named single-as24ci_car.php or archive-as24ci_car.php in its root directory, WordPress loads that file instead of the plugin's bundled template. This is by design and enables full theme-level customisation. See Template Override Guide.
• alignfull on block themes. Block themes (Twenty Twenty-Three, Twenty Twenty-Four, and similar) typically render full-width aligned elements edge-to-edge. Because the plugin wrapper carries alignfull, it follows this behaviour. If your block theme does not use the standard alignfull class for full-width content, the layout may look narrower than expected.
• Classic themes with fixed content widths. Some classic themes wrap all content in a <div class="container"> or similar element that restricts width. The plugin's inner wrapper is 1440px wide by default, centred with margin: 0 auto. On themes with a narrower fixed container, the plugin content will be constrained to the theme's container width. This is generally acceptable but may cause the design to look different from the preview in Car Market Hub → Design.
• Conflicting heading styles. Themes that target h1, h2, or h3 globally can affect headings inside the plugin wrapper. If heading sizes or colours look wrong on vehicle pages, use the per-heading override controls in Car Market Hub → Design or add a scoped rule in the Custom CSS field. See Custom CSS Guide.
• JavaScript conflicts. Themes or other plugins that load jQuery at a non-standard priority, or that replace or disable jQuery, may affect the plugin's make-to-model filter dependency on the archive page. Test dynamic filtering (selecting a make and watching the model dropdown update) after changing themes.
• Caching. After changing themes or adjusting Design settings, clear any active page cache and object cache so that updated CSS is delivered.

Troubleshooting

Related documents

• Template Override Guide
• Custom CSS Guide
• Page Builder Integration
• Design and Styles Reference
• PHP and Database Requirements
• Hosting Requirements