Documentation · Technical Documentation

Template Overrides

This document explains how to override the ADP Car Market Hub plugin's bundled front-end templates from a (child) theme so that upgrades do not overwrite your customisations.

When to use this document

Read this document if you need to:

  • Adjust the markup, layout or order of fields on the single vehicle page or the vehicle archive without modifying the plugin's source files.
  • Apply theme-specific wrappers, sidebars or hooks to the plugin's pages.
  • Migrate existing customisations into a child theme to make them upgrade-safe.

For the underlying template-loading flow, see Frontend Template System. For template-driven shortcodes, see Shortcodes.

Overview

The plugin renders single vehicle pages and the vehicle archive through two WordPress filters:

  • single_template — replaced by single-as24ci_car.php (theme override) or the plugin's bundled file.
  • archive_template — replaced by archive-as24ci_car.php (theme override) or the plugin's bundled file.

For each filter, the plugin first calls locate_template(). If the active theme (or its child theme) provides a file with the expected name, that file wins. Otherwise the plugin falls back to the file shipped under its own templates/ directory.

This makes overrides simple: drop a correctly named file in your theme and WordPress will load it instead of the bundled version.

Requirements or prerequisites

  • A child theme is strongly recommended so theme updates do not overwrite your overrides.
  • Familiarity with the bundled template files. They are namespaced AS24CI and rely on plugin classes such as Archive_Filters, Field_Mapping, Schema, Options and Locations.
  • Read access to the plugin's templates/ directory to copy the current bundled markup as a starting point.

Step by step instructions

  1. Identify the template you want to override: - Single vehicle page → single-as24ci_car.php. - Vehicle archive page → archive-as24ci_car.php.
  2. Copy the bundled file from the plugin's templates/ directory into the root of your (child) theme using the same filename.
  3. Edit the copy in your theme. Keep the existing class references and data lookups unless you are sure of the replacement.
  4. Clear any full-page or template caches.
  5. Reload the relevant page on the front-end and confirm the override is loaded (for example by viewing page source for a marker comment you added).

Override locations

The plugin uses locate_template() with the bare filename. That means WordPress searches:

  • The active child theme's root directory.
  • The active parent theme's root directory.

Subdirectory layouts inside a theme (for example <theme>/templates/single-as24ci_car.php) are not searched by the plugin's filter. Place override files in the theme root using the exact filename.

What you can override

  • single-as24ci_car.php — the entire single-vehicle page. The bundled wrapper is intentionally thin; the actual layout lives in single-as24ci_car-classic.php. Overriding the wrapper means you take full responsibility for choosing and including a layout.
  • archive-as24ci_car.php — the entire vehicle archive page. This is also the file that the [as24ci_archive] shortcode includes (see Limitations below).

What is not directly overridable

  • Template parts (e.g. templates/parts/search-filter.php) are loaded with include from absolute plugin paths and do not pass through locate_template(). To customise them, override the parent template that includes them and replicate the required output, or use the plugin's available hooks and filters.
  • Shortcode templates — [as24ci_archive], [as24ci_compare] and [as24ci_search_filter] always include the plugin's bundled files (archive-as24ci_car.php, page-as24ci_compare.php, parts/search-filter.php). A theme override of archive-as24ci_car.php therefore also affects the [as24ci_archive] shortcode, but the compare and search-filter templates cannot be overridden via locate_template().
  • Plugin CSS/JS that the templates depend on. Override styling via your theme's stylesheet rather than by removing the plugin's enqueued assets.

Operational notes

  • When upgrading the plugin, review the changelog for changes to the bundled templates. If the plugin adds or removes data the template renders, your override may need to be updated to match.
  • Avoid mixing partial overrides with code that assumes the bundled file's structure. Either keep the override close to the original or document the divergence inside the file.
  • Theme overrides are not affected by plugin auto-updates because WordPress only updates files inside the plugin directory.
  • Overrides apply to both logged-in admins and visitors. There is no per-role override mechanism in the plugin.
  • Overrides cannot bypass the post-type or capability checks the filters apply: the override is only loaded for genuine as24ci_car single or archive requests.

Troubleshooting

  • Override file is ignored — confirm the file is in the active theme's root and uses the exact filename (single-as24ci_car.php or archive-as24ci_car.php). Check for a typo or for a parent theme that already provides the file.
  • Fatal error after override — the bundled templates use the AS24CI namespace and reference plugin classes. If you copied only part of the file, restore the namespace declaration and the defined( 'ABSPATH' ) guard, and keep the Field_Mapping / Archive_Filters lookups intact.
  • **Override appears on the CPT archive but not in the shortcode** — both routes load archive-as24ci_car.php from the plugin's templates/ directory; the shortcode does not use locate_template(). Verify your override path and that no caching plugin is serving an older version of the page.
  • Layout looks unstyled after override — the bundled CSS expects specific class names. Either keep those class names in your override or extend the theme stylesheet to cover the new markup.