Template Override Guide

This document explains how to safely customise the PHP templates used by the ADP Car Market Hub plugin by creating override files in your theme, and how to keep those overrides maintainable across plugin updates.

When to use this document

Use this document if you are:

• A developer who needs to change the HTML structure of the vehicle archive, single vehicle detail, or compare page beyond what the Design settings and Custom CSS allow.
• Maintaining a custom theme and want to integrate vehicle pages seamlessly into the theme's own HTML structure.
• Reviewing a site after a plugin update to check whether existing overrides are still compatible.

This guide is for PHP developers who are comfortable with WordPress theme development. If you only need to change colours, fonts, or spacing, use Car Market Hub → Design or the Custom CSS field instead — no template override is needed. See Custom CSS Guide.

Overview

The plugin provides fallback PHP templates for vehicle pages in its templates/ directory. WordPress locates templates in a specific order: active theme files are checked before plugin files. The plugin uses this mechanism intentionally via locate_template():

1. WordPress checks the active theme directory for a file with the same name.
2. If found, that theme file is used.
3. If not found, the plugin's own template is used as a fallback.

This means you can override any of the plugin's front-end templates by placing a file with the same name in your theme's root directory. The plugin file is never modified and is safe from your customisations during updates. Your override file stays in the theme, which is under your own version control.

Templates available for override

The following template files are resolved through locate_template() and can be overridden:

The compare page (page-as24ci_compare.php) and search filter partial (parts/search-filter.php) are loaded directly by the plugin and are not resolved through locate_template(). They cannot be overridden using this method. Verify this behaviour in the current plugin version before relying on it.

Prerequisites

• Access to the active theme's files (via FTP, SSH, or the WordPress file editor).
• A child theme is strongly recommended if you are using a commercial or parent theme. Placing override files in a parent theme means they will be lost when the parent theme is updated.
• Familiarity with PHP and WordPress template tags (get_header(), get_footer(), the_title(), and similar).

Step by step instructions

Creating a template override

1. Locate the source file. Find the template you want to customise in the plugin directory, at wp-content/plugins/adp-car-market-hub/templates/. For example, archive-as24ci_car.php.
2. Copy — do not move — the file. Copy the file into your (child) theme's root directory. The filename must be identical: - For the archive: wp-content/themes/your-theme/archive-as24ci_car.php - For the single: wp-content/themes/your-theme/single-as24ci_car.php
3. Make your changes in the theme copy. Edit the copy in your theme. The plugin's original file is untouched.
4. Test on the front end. Visit a vehicle archive or single vehicle page and confirm that your changes are applied.

Verifying which template is active

The WordPress Site Health page and query monitor plugins (for example Query Monitor) can show which template file is being used for any given request. Alternatively, add a temporary comment to the top of your override file and check the page source to confirm the file is loaded.

Staying compatible after plugin updates

When the plugin is updated, the bundled templates in templates/ may change. Your override file stays in the theme and continues to be used — but if the plugin's template logic has changed, your override may be out of date.

After each plugin update:

1. Compare your override file with the corresponding file in the updated plugin directory. A diff tool or code editor with file comparison can help.
2. Merge any relevant changes from the plugin's new version into your override.
3. Test vehicle pages on the front end after merging.

Keeping overrides minimal — containing only the sections you actually need to change — reduces the work required when merging updates.

Configuration reference

There is no plugin settings field that directly controls template overrides. The resolution logic is part of the WordPress hook system and cannot be changed from the plugin admin.

The Design settings in Car Market Hub → Design still apply even when a template override is in use, because the dynamic CSS is output via wp_head regardless of which template file is served.

Operational notes

• Child theme requirement. If you are using a commercial or parent theme, always create a child theme before adding override files. Files added directly to a parent theme are deleted when the theme updates.
• The override must call get_header() and get_footer(). The plugin's own templates call both. If your override omits them, the page will be served without the theme's navigation and footer. This is almost never desired.
• Keep the plugin namespace. The plugin's template files declare namespace AS24CI; and reference internal constants such as CPT::POST_TYPE and Options::DESIGN_SINGLE_LAYOUT. If your override uses any of these, keep the namespace declaration or fully qualify the class names.
• Shortcode render mode. The archive template supports two render modes controlled by the global $as24ci_render_mode variable: 'template' (when served as a CPT archive page) and 'shortcode' (when included by the [as24ci_archive] shortcode). The template omits get_header() and get_footer() in shortcode mode. Your override should replicate this behaviour if you want the shortcode to work correctly alongside the archive template.
• CSS class stability. The plugin's CSS depends on class names in the template HTML (for example .as24ci-page, .as24ci-page-classic, .as24ci-archive-list, .as24ci-archive-row). If you remove or rename these classes in your override, the plugin's stylesheet and Design settings will stop working for those elements. Only change class names if you also update the corresponding CSS in the Custom CSS field or in your theme stylesheet.
• alignfull class. The plugin adds the alignfull class to the .as24ci-page wrapper so that block themes extend it to full width. If you remove this class in your override, the block-theme full-width behaviour will not apply.
• PHP version and WordPress version requirements. The plugin's templates use PHP features consistent with the plugin's stated requirements. See PHP and Database Requirements.

Troubleshooting

Related documents

• Theme Integration
• Custom CSS Guide
• Page Builder Integration
• Design and Styles Reference
• PHP and Database Requirements