Frontend Template System

This document explains how the ADP Car Market Hub plugin renders vehicle pages on the front-end, how its bundled templates relate to the active WordPress theme, and which extension points are exposed to themes and shortcodes.

When to use this document

Read this document if you need to:

• Understand which file renders the single vehicle page or the vehicle archive.
• Decide whether to use a shortcode-based listing inside a regular page or rely on the CPT archive.
• Extend or override the layout from a child theme. For the override mechanics, see Template Overrides.

Overview

The plugin registers its as24ci_car post type with archive support and ships a small set of bundled templates under the plugin's templates/ directory. Two WordPress filters route requests to those templates when the active theme does not provide its own version:

• single_template — used for is_singular( 'as24ci_car' ).
• archive_template — used for is_post_type_archive( 'as24ci_car' ).

Each filter first asks WordPress to locate a theme-level override (locate_template()), and only falls back to the plugin's bundled file when no override exists.

Bundled templates

The following files live under the plugin's templates/ folder and are loaded by the filters above (or by shortcodes):

• single-as24ci_car.php — thin wrapper that selects the appropriate single-vehicle layout based on the as24ci_design_single_layout option and includes the chosen layout file.
• single-as24ci_car-classic.php — the current single-vehicle layout. The wrapper currently always loads this file; future versions may add additional layouts. Verify behaviour against the current plugin version before publishing customer-facing copy.
• archive-as24ci_car.php — the vehicle archive layout used for the CPT archive and for the [as24ci_archive] shortcode.
• parts/search-filter.php — partial rendered by [as24ci_search_filter] to display the standalone search form.
• page-as24ci_compare.php — comparison page rendered by [as24ci_compare].
• icons/ — shared inline-SVG icon helpers used across the templates.
• css/ and js/ — assets the templates depend on.

How a request reaches a template

1. WordPress parses the request and resolves it to a single vehicle or to the vehicle archive.
2. Right before output, WordPress applies single_template or archive_template.
3. The plugin's filter callback: - returns the original $template when the request is not for as24ci_car; - calls locate_template( '<template>.php' ) to give the active (child) theme the first chance to override; - if no theme file exists, returns the bundled file from the plugin's templates/ directory; - if neither exists, returns the original $template so WordPress can fall back to its standard hierarchy.

The shortcodes follow the same precedence in spirit, but they do not call locate_template() — they always include the plugin's bundled archive / compare / search-filter files. See Shortcodes and Template Overrides for the implications.

Shortcode and render-mode integration

The plugin exposes a global flag, $as24ci_render_mode, that the shortcode handlers set to 'shortcode' while their bundled template runs. Conditional code in the templates and in supporting classes (for example asset loading) uses this flag to apply the same logic on shortcode-based pages that they apply on the native CPT archive.

The [as24ci_archive] shortcode replaces the global $wp_query with a custom query while the archive template renders, and restores the previous query and wp_reset_postdata() afterwards, so it can be embedded safely inside a normal page.

Configuration reference

Layout, design and feature toggles that affect what is rendered inside the templates (filter zones, favorites field set, search agent toggle, etc.) are documented in Options And Settings Storage.

Operational notes

• The plugin's filter callbacks return the bundled file path as a string. WordPress includes the file with its standard template loader, so global variables such as $post, $wp_query and body classes behave as in any theme template.
• Bundled templates declare namespace AS24CI; and exit when ABSPATH is undefined, mirroring WordPress's standard guard.
• Template files reference plugin classes such as Archive_Filters, Field_Mapping, Schema, Options and Locations to assemble their data. Themes overriding the file must keep these references intact (or replicate the equivalent data fetching) to avoid undefined-variable warnings.
• The shortcode-based archive forces a fresh WP_Query from $_GET parameters via Archive_Filters::build_query_args_from_request(), so URL filters work identically on the CPT archive and on shortcode pages.

Troubleshooting

• The plugin's layout never appears — confirm the active theme does not define its own single-as24ci_car.php or archive-as24ci_car.php; theme files always win. See Template Overrides.
• A page using [as24ci_archive] shows the wrong post — the shortcode replaces the global query while it runs and restores it afterwards. If a custom theme component reads the global query before the shortcode is processed, the order in which the page renders parts of the layout matters; embed the shortcode in the main content area rather than in the header or sidebar.
• Pagination resets to page 1 inside [as24ci_archive] — the shortcode reads ?paged= and ?page= from the URL. Ensure your permalink structure allows query strings or use a permalink that is compatible with the shortcode.
• Asset (CSS/JS) not loaded on a shortcode page — the plugin detects shortcodes and the $as24ci_render_mode flag to load assets. If a builder caches the page output, force-clear that cache after editing the page so the shortcode is detected during enqueue.

Related documents

• Template Overrides
• Shortcodes
• Custom Post Types And Taxonomies
• Options And Settings Storage
• Architecture Overview