Template System And Overrides

This document describes how the ADP Car Market Hub plugin loads its front-end templates and how a theme can override them. It lists the files shipped in the plugin's templates/ folder and explains which ones are theme-overridable through the standard WordPress template hierarchy and which are loaded directly by shortcodes.

When to use this document

Read this document when you need to:

• Customise the markup of the vehicle single page, the vehicle archive, or the comparison page from a theme or child theme.
• Replace a small partial (for example the search filter form) without forking the entire template.
• Understand which template files are safe to override and which ones change between releases.

For the post types and taxonomies these templates render, see Custom Post Types And Taxonomies. For the shortcodes that load template parts directly, see Shortcodes For Developers.

Overview

The plugin ships its templates in the templates/ folder of the plugin. Two mechanisms expose them:

1. WordPress template hierarchy filters. The plugin hooks single_template and archive_template. For both filters it first calls locate_template() so that an active theme or child theme can supply its own copy of the file. If no theme override is found, the plugin's bundled template is used.
2. Direct shortcode rendering. The shortcodes for the comparison page ([as24ci_compare]) and the standalone search filter ([as24ci_search_filter]) load their templates directly from the plugin's templates/ folder. They do not consult the theme for an override.

The result is that the single-vehicle page and the vehicle archive can be overridden cleanly by dropping a file into the active theme, while the comparison page and the search filter partial change only when you modify or filter their output through a different mechanism.

Files shipped under templates/

Top-level templates:

• archive-as24ci_car.php — vehicle archive listing.
• single-as24ci_car.php — vehicle single page (default layout).
• single-as24ci_car-classic.php — alternative "classic" single layout.
• page-as24ci_compare.php — comparison page rendered by [as24ci_compare].

Partials and assets:

• parts/search-filter.php — the search-filter form rendered by [as24ci_search_filter].
• icons/ — SVG icon definitions used by the templates.
• css/ and js/ — front-end stylesheets and scripts shipped alongside the templates and enqueued by the asset loader (see Frontend Assets).

Theme-overridable templates

These files are loaded through single_template / archive_template filters and therefore respect the theme:

The plugin calls locate_template( '<file-name>.php' ) with no subdirectory prefix, so the override file goes directly in the active theme's root (or child theme's root). If locate_template() returns a path, the plugin uses it; otherwise it falls back to the bundled template.

Templates not loaded through the theme hierarchy

These files are loaded directly by the plugin and are not picked up by locate_template():

To customise these, you have three reliable options:

1. Build a wrapper page or template in your theme that calls the relevant shortcode and surrounds its output with your own markup.
2. Use the action and filter hooks the plugin exposes (see Hooks And Filters, Actions Reference, Filters Reference) to alter behaviour rather than markup.
3. As a last resort, fork the file into your theme and load it from your own template; you then take responsibility for keeping it aligned with future plugin releases.

Step by step instructions

Override the vehicle single page

1. Copy single-as24ci_car.php from the plugin's templates/ folder.
2. Paste it into the root of your active theme (or child theme).
3. Edit the copy to make your changes.
4. Reload a single vehicle page. WordPress will load your file via locate_template() instead of the plugin's bundled file.

Override the vehicle archive

1. Copy archive-as24ci_car.php from the plugin's templates/ folder.
2. Paste it into the root of your active theme (or child theme).
3. Edit the copy. Reload the archive page (/cars/ by default) to see your version.

Customise the comparison page or the search-filter form

1. Either wrap the relevant shortcode in a custom page template or block layout in your theme, or fork the underlying template into your theme and load it from your own template.
2. Verify that any plugin assets you depend on (CSS/JS, see Frontend Assets) are still enqueued on your custom page.

Operational notes

• Use a child theme. Place overrides in a child theme to avoid losing them when the parent theme updates.
• Layout manager interaction. The plugin includes a layout manager that arranges blocks within the single-vehicle and archive pages, configured from the plugin's admin UI. If you fully replace the single or archive template, you also bypass the layout manager. Use selective hook-based modifications when you need to keep that behaviour.
• Compare page activation. The compare page is created on activation. The page itself simply contains the [as24ci_compare] shortcode, so its content is rendered by the plugin template, not by single_template / archive_template.
• Shortcode in any page. Because [as24ci_archive] re-uses the archive renderer, you can embed the listing into any WordPress page or block layout without overriding the archive template at all.
• Asset enqueueing. Front-end CSS and JavaScript shipped with the plugin are enqueued conditionally based on the current page (single, archive, shortcode usage). If you build a custom wrapper template that does not match the standard conditions, the relevant plugin assets may not be enqueued automatically.
• Verify behaviour in the current plugin version before publishing a custom theme. Template structure and block markup can change between releases.

Troubleshooting

• My theme override is ignored. Confirm the file name matches exactly (single-as24ci_car.php, archive-as24ci_car.php) and that it sits at the root of the active theme. Clear any object/page cache.
• Single page renders the classic layout (or vice versa). The single layout is selected from the plugin's design settings in the admin UI. Change it there rather than from the theme.
• Compare page shows nothing or a 404. Confirm that the compare page still exists, contains the [as24ci_compare] shortcode, and is published. Confirm that the compare feature is enabled in the plugin's admin UI.
• Front-end script or style missing on a custom wrapper page. The plugin's asset loader keys off post type, archive, and shortcode detection. Use the official shortcodes inside your wrapper so the matching assets are enqueued automatically.
• Verify behaviour in the current plugin version before publishing a custom integration. Template paths and markup can evolve between releases.

Related documents

• Custom Post Types And Taxonomies
• Shortcodes For Developers
• Frontend Assets
• Hooks And Filters
• Filters Reference