Documentation · Frontend Guide

Compare

This document covers the vehicle comparison feature of the ADP Car Market Hub WordPress Plugin: how visitors select vehicles to compare, how the comparison page works, and what limitations apply.

When to use this document

Read this document if you are setting up the compare feature for the first time, helping a visitor understand how to use it, or troubleshooting unexpected behavior in the comparison view.

Overview

The compare feature allows visitors to select up to a configurable number of vehicles from the archive or from individual vehicle detail pages, and then view them side by side on a dedicated comparison page. The selection is stored in the browser's localStorage and requires no account or login.

The comparison page is a full-page table with one column per vehicle. Each row shows the vehicle's thumbnail, title, and configured specification fields. Vehicles are rendered in the order they were selected.

Requirements or prerequisites

The compare feature must be enabled in the plugin settings (it is enabled by default).
A compare page must be configured and accessible. The plugin can create a default compare page during activation; you can also create one manually and assign it in the plugin settings.
The compare page must contain the [as24ci_compare] shortcode, or the plugin must be configured to use the page via the as24cipagecompare_id option so it can resolve the compare URL.

Step-by-step instructions

Set up the compare page

In the WordPress admin, go to Pages → Add New.
Give the page a title such as "Compare Vehicles".
In the page content, add the shortcode [as24ci_compare].
Publish the page.
In the plugin settings, note the page ID. The plugin uses the stored compare page ID (as24ci_page_compare_id) to build compare links throughout the site. If this option is not set, the plugin falls back to home_url('/compare-cars/').

Use the compare feature as a visitor

On the vehicle archive, locate a vehicle card. When the compare feature is enabled and the compare button is active in the Layout Manager, a compare icon button appears on the card overlay.
Click the compare button to add the vehicle to the comparison selection. The button changes state to indicate the vehicle is selected.
Repeat for other vehicles you want to compare. The plugin enforces a configurable maximum number of vehicles (default: 4).
When you have selected the desired vehicles, click the compare link or button that appears (the label reads "Compare"). This navigates to the compare page.
The compare page loads with the selected vehicles displayed side by side in a table.

The same compare button appears in the sticky floating bar on single vehicle detail pages, allowing visitors to add a vehicle to the comparison selection while viewing its full detail.

Open the compare page directly

The compare page reads vehicle IDs from the ids GET parameter, which is a comma-separated list of vehicle post IDs:

https://yoursite.com/compare-cars/?ids=123,456,789

The JavaScript compare toggle builds this URL automatically when the visitor clicks the "Compare" link.

Configuration reference

Compare settings

Setting	Location	Description
Enable compare	Plugin settings → Settings (or Setup Wizard)	Enables or disables the entire compare feature
Maximum vehicles	Plugin settings → Compare	Maximum number of vehicles a visitor can add to a comparison (default 4, minimum 2)
Compare page	Plugin settings → Pages	Page ID of the compare page. Used to build compare URLs throughout the site.

Compare table fields

The fields displayed in the comparison table are configured in the Layout Manager → Compare zone. Each enabled field appears as a row in the table for every selected vehicle. The available fields and their default labels include:

Field ID	Description
`conditionType`	Condition (new or used)
`bodyType`	Body type
`fuelType`	Fuel type
`transmissionType`	Transmission
`driveType`	Drive type
`bodyColorText`	Exterior color
`interiorColorText`	Interior color
`doors`	Number of doors
`seats`	Number of seats
`mileage`	Mileage (formatted with km)
`cubicCapacity`	Engine displacement (cm³)
`range`	Electric range (km)
`firstRegistrationYear`	First registration year
`firstRegistrationDate`	First registration date
`kiloWatts`	Power in kW
`horsePower`	Power in HP
`co2Emission`	CO₂ emissions (g/km)
`price`	Selling price
`listPrice`	List price
`emissionStandard`	Emission standard
`energyLabel`	Energy label
`batteryCapacity`	Battery capacity (kWh)
`hadAccident`	Accident history (Yes/No)

Additional fields may be available depending on the vehicle data imported. Verify the current list in your plugin's Layout Manager.

Units are applied automatically to numeric values:

Price: formatted with currency
Mileage, range, warranty mileage, towing capacity, curb weight, total weight: km or kg as appropriate
CO₂: g/km
Displacement: cm³
Horsepower: HP
Consumption: l/100 km
Battery capacity: kWh
Power consumption: kWh/100 km
Fast charging power: kW
Warranty duration: months
Boolean fields (hadAccident, inspected): displayed as Yes or No

Fields with no value for a vehicle display an em dash (—).

Archive card compare button

The compare button appears on vehicle archive cards when:

The compare feature is enabled in the plugin settings (FEATURE_COMPARE).
The compare_btn element is enabled in the Layout Manager → Archive Cards zone.

The button shows a compare icon and toggles the selected state when clicked.

Operational notes

Vehicle selections are stored in localStorage under a key managed by the compare JavaScript. Selections persist across page navigation within the same browser session and survive page reloads.
Clearing browser data (cookies, local storage) will reset the compare selection.
The compare page reads the ids GET parameter and loads up to 4 vehicles (hard-coded maximum in the template). Only published vehicles of the correct post type are loaded; unpublished or deleted vehicles are silently excluded.
The configurable maximum (COMPARE_MAX_VEHICLES) controls the JavaScript enforcement of the limit during selection. The server-side template applies its own hard limit of 4. If the configurable maximum exceeds 4, the server will still only render at most 4 columns.
Vehicle data in the comparison table is read from the plugin's custom {prefix}as24_vehicles table when available, with fallback to the raw API payload (raw_data JSON column) and then to WordPress post meta for legacy vehicles.
The compare page can be used both as a standalone WordPress page (via the [as24ci_compare] shortcode) and as a template-driven page. Both render the same output.
The compare JavaScript asset is enqueued only on vehicle archive pages, single vehicle pages, and pages containing the [as24ci_archive] or [as24ci_compare] shortcode.

Troubleshooting

The compare button does not appear on vehicle cards.

Verify the compare feature is enabled in the plugin settings.
Check the Layout Manager → Archive Cards zone and confirm compare_btn is enabled.

Clicking the compare button shows "You can compare up to X vehicles."

The visitor has reached the configured maximum. They must remove a vehicle from the selection before adding another.

The compare page shows "No vehicles selected for comparison."

The visitor navigated to the compare page without any vehicles in their localStorage selection.
This can also happen if the browser does not support localStorage or if it has been cleared.

The compare page shows fewer vehicles than expected.

Only published vehicles are loaded. If a vehicle was deleted or unpublished after being added to the compare selection, it is excluded from the output.
The template enforces a maximum of 4 vehicles regardless of the configurable setting.

Compare links point to the wrong page.

Verify that the compare page ID is set correctly in the plugin settings (as24ci_page_compare_id). If this option is missing or points to a deleted page, the compare URL falls back to home_url('/compare-cars/').