Documentation · User Handbook
Frontend Usage Workflow
This document describes how visitors interact with the vehicle inventory on the public-facing (frontend) side of a WordPress site powered by the ADP Car Market Hub plugin. It covers the vehicle archive page, detail pages, filter controls, Favorites, Compare, contact and test drive forms, financing calculator, social sharing, PDF datasheet, and Search Alerts.
When to use this document
Read this document if you:
- Want to understand what visitors see and what actions they can take on the frontend.
- Are configuring or testing frontend features (filters, favorites, compare, forms, and so on).
- Need to verify that the frontend is displaying inventory correctly after an import.
- Are integrating shortcodes into WordPress pages.
For administrator configuration of these features, see the Administrator Handbook.
Overview
The plugin renders vehicle inventory on the WordPress frontend using a dedicated custom post type (as24ci_car) and a set of built-in templates. The main frontend areas are:
- Vehicle archive page — a paginated grid of all published vehicle cards.
- Vehicle detail page — a single vehicle's full information.
- Compare page — side-by-side comparison of selected vehicles.
- Favorites page — a list of vehicles the visitor has saved.
These pages can be served through the WordPress CPT archive URL, native taxonomy archive URLs, or WordPress pages containing plugin shortcodes.
Requirements or prerequisites
- At least one vehicle must be imported and published (post status:
publish) before anything appears on the frontend. - The vehicle archive and compare/favorites pages must be published WordPress pages containing the appropriate shortcodes, or the WordPress CPT archive must be accessible via your permalink structure.
- Features such as Favorites, Compare, Financing Calculator, Test Drive, Social Sharing, and Search Alerts must be enabled before they appear on the frontend. The Favorites and Compare toggles live on the Settings tab (and in the Setup Wizard); Social Sharing is configured under Design & Styles; Search Alerts are managed on the dedicated Search Alerts tab; Test Drive booking and the Financing Calculator are configured on the Leads tab and the financing settings section respectively. Verify the current placement in the installed plugin version, as the admin layout can evolve between releases.
- For the Test Drive feature, available weekdays, time window, slot duration, and (optionally) blackout dates must be configured in the Leads tab.
Vehicle archive page
Display
The archive page displays published vehicles as a card-based grid. Each card shows:
- Vehicle image (thumbnail).
- Condition badge (New, Used, Sale, or Top Offer — configurable in Design & Styles).
- Vehicle title (make, model, variant).
- Key specifications (year, mileage, fuel type, power).
- Price.
- Favorites heart button (if the Favorites feature is enabled).
- Compare button (if the Compare feature is enabled).
- Link to the vehicle detail page.
The number of vehicles per page is configurable (12, 24, 48, 72, or all) and can be changed via the per-page selector in the filter sidebar or toolbar.
Shortcode
The archive can be embedded on any WordPress page using:
[as24ci_archive]The shortcode supports optional filter override attributes, for example:
[as24ci_archive make="BMW" per_page="12"]Sorting
When the sort filter is enabled, visitors can sort vehicles by:
- Newest first (default: by import/publish date, descending)
- Price: low to high
- Price: high to low
- Mileage: low to high
- Year: newest first
- Year: oldest first
Verify the exact sort options available in your plugin version.
Archive filters
The filter sidebar on the archive page allows visitors to narrow the vehicle list. Each filter can be individually enabled or disabled in ADP Car Market Hub → Layout Manager.
Standard filters
| Filter | Description |
|---|---|
| Make | Brand/manufacturer (uses as24ci_brand taxonomy) |
| Model | Model name (uses as24ci_model taxonomy) |
| Body type | Body type (uses as24ci_body_type taxonomy) |
| Fuel type | Fuel type (uses as24ci_fuel_type taxonomy) |
| Transmission | Gearbox type (uses as24ci_transmission taxonomy) |
| Drive type | Drivetrain (uses as24ci_drive taxonomy) |
| Condition | New / Used / Other (uses as24ci_condition taxonomy) |
| Exterior colour | Exterior paint colour (uses as24ci_ext_color taxonomy) |
| Price range | Minimum and maximum price (numeric range) |
| Mileage | Minimum and maximum mileage (numeric range) |
| Year | Minimum and maximum first registration year |
| Keyword search | Text search across vehicle title and description |
Advanced filters
| Filter | Description |
|---|---|
| Interior colour | Interior colour (uses as24ci_int_color taxonomy) |
| Energy label | Energy efficiency label A–G (uses as24ci_energy_label taxonomy) |
| Engine displacement | Cubic capacity range in cc |
| Doors | Minimum and maximum number of doors |
| Seats | Minimum and maximum number of seats |
| Location | Dealer location filter |
Applying filters
Filters are applied via URL query parameters. Selecting a filter option reloads or updates the archive with the filtered results. Multiple filters can be combined. Clearing a filter removes it from the query.
Vehicle detail page
A vehicle detail page is the single-vehicle view displaying full listing information.
Content sections
| Section | Description |
|---|---|
| Image gallery | Grid or slider layout (configurable). Supports lightbox when enabled. |
| Breadcrumbs | Navigation trail showing the archive path |
| Vehicle title and price | Prominently displayed; currency formatted per locale settings |
| Condition badge | Displays New / Used / Sale / Top Offer |
| Specifications table | All mapped vehicle attributes: mileage, registration, engine, power, transmission, fuel, body type, colour, doors, seats, emissions, and more |
| Equipment list | Equipment and features extracted from the AutoScout24 listing |
| Description | Vehicle description text (imported from the API or generated by the AI Assistant) |
| Contact / salesperson card | The dealership sales contact resolved for this vehicle (name, photo, email and phone), shown when a CMH Team contact is configured. See CMH Team below. |
| Contact form | Built-in inquiry form (see Contact form below) |
| Financing calculator | Monthly payment estimator (if enabled) |
| Test Drive form | Test drive booking form (if enabled) |
| Social sharing buttons | Share links for WhatsApp, Facebook, Instagram, X/Twitter, email, and copy-link (if enabled) |
| PDF datasheet button | Link to open a print-optimised vehicle datasheet |
| Favorites button | Add/remove the vehicle from the visitor's favorites list |
| Compare button | Add/remove the vehicle from the comparison selection |
The specific fields displayed in the specifications table are controlled by the Mapping tab settings where each field can be shown or hidden and its label customised.
Contact form
The built-in contact form is shown on each vehicle detail page and allows visitors to send an inquiry about the vehicle.
Fields
- Name — required.
- Email — required. Must be a valid email address.
- Phone — optional (enable/disable in Leads settings).
- Message — optional (enable/disable in Leads settings).
- Consent checkbox — optional (enable and configure in Leads settings). When enabled, the visitor must check the box before submitting.
Spam and rate limiting
- Honeypot: a hidden field is included in the form. Automated bots typically fill it; when filled, the submission is silently rejected without creating a lead or sending an email.
- Rate limiting: up to 5 submissions per IP address per 5 minutes are accepted. Submissions above this threshold receive an error response.
After submission
- The visitor is redirected back to the
#as24ci-contactanchor on the vehicle page with a success or error indicator. - A success message confirms the inquiry was received.
- An error message is shown if the submission failed (for example, a required field is missing or the rate limit was exceeded).
The success and error messages are configurable in Leads settings.
CMH Team contact card
When a dealership sales contact is configured in CMH Team, the vehicle detail page shows that person as the contact for the listing.
- The card displays the contact's name and (where provided) photo, email address and phone number, with click-to-email and click-to-call links.
- The contact shown is the one resolved for the specific vehicle: a contact assigned directly to the car takes precedence, then the contact set for the car's location, then the global default contact.
- If no CMH Team contact applies, the page falls back to the seller profile details of the vehicle's author.
- The same resolved contact is also used as the preferred recipient for inquiries submitted through the contact form (see Lead Management Workflow).
Administrators manage these contacts under the CMH Team menu; see the Administrator Handbook.
Test Drive booking
When the Test Drive feature is enabled, a test drive booking form is available on each vehicle detail page (often rendered as a tab alongside the contact form).
How it works
- The visitor selects a date from a date picker. Dates in the past and dates that fall on a day not configured as available are not selectable.
- Based on the selected date, the available time slots are loaded dynamically. Slots are generated from the configured start time, end time, and slot duration (for example, 09:00–17:00 in 30-minute intervals).
- The visitor selects a time slot and fills in their name, email, and optional phone number.
- On submission, a test drive request is created as a lead with
is_test_drive = 1and theappointment_datefield set. - The standard email notifications are sent (with "Test Drive Request" indicated in the subject and body).
Configuration (for administrators)
- Available weekdays — which days of the week allow test drives (Monday through Sunday).
- Start time / End time — the daily time window for slots (for example, 08:00–18:00).
- Slot duration — length of each time slot in minutes (minimum 5 minutes).
- Blackout dates — specific dates (entered as
YYYY-MM-DD, one per line) on which no test drives are available, regardless of the weekday setting.
Financing calculator
When the Financing Calculator feature is enabled, an interactive monthly payment estimator is shown on vehicle detail pages.
The calculator uses:
- Vehicle price from the imported listing.
- Interest rate — configurable default (Loans tab in Features settings).
- Loan term — configurable default in months (12, 24, 36, 48, 60, 72, or 84 months).
- Down payment — configurable default as a percentage of the vehicle price.
Visitors can adjust the rate, term, and down payment to see different payment estimates. The result is a calculated monthly instalment figure displayed on the page. This calculator is for illustrative purposes only; actual financing terms depend on the customer's financial provider.
Favorites (Wishlist)
When the Favorites feature is enabled, visitors can save vehicles to a personal wishlist.
How it works
- A heart icon button appears on each vehicle card in the archive and on the vehicle detail page.
- Clicking the heart adds the vehicle to the visitor's favorites. Clicking again removes it.
- Favorites are stored in the visitor's browser (
localStorage). No login or account is required. - Favorites are device and browser specific — they do not synchronise across devices or browsers, and are cleared if the visitor clears their browser storage.
- A maximum of 50 vehicles can be stored in favorites at one time.
Favorites page
Embed the favorites page on any WordPress page using the shortcode:
[as24ci_favorites]The page fetches the vehicle data for the stored IDs via a REST API endpoint and renders a list with the configured fields. The visible fields are configurable in Layout Manager (Favorites zone).
Vehicle Compare
When the Compare feature is enabled, visitors can select multiple vehicles for side-by-side comparison.
How it works
- A Compare button appears on archive cards and on the single vehicle page's floating action bar.
- Clicking the button toggles the vehicle in/out of the comparison selection.
- The selected vehicles are stored in
localStorage. No login is required. - The maximum number of vehicles that can be compared at once is configurable (default: 4). When the maximum is reached, a message informs the visitor.
- A floating bar or indicator typically shows how many vehicles are selected and provides a link to the compare page.
Compare page
The compare page is rendered by the shortcode:
[as24ci_compare]This page displays the selected vehicles in a side-by-side table for easy comparison of specifications. If no vehicles are selected, an instructional message is shown.
Social sharing
When Social Sharing is enabled, a row of sharing buttons appears on vehicle detail pages. No external JavaScript SDKs are loaded — all buttons are standard URL-based links.
Supported networks
- WhatsApp — opens the WhatsApp share dialog.
- Facebook — opens the Facebook share dialog.
- Instagram — Instagram does not support direct URL-based web sharing; the button behaviour for Instagram may vary. Verify in the current plugin version.
- X (formerly Twitter) — opens the X/Twitter compose window with the vehicle URL pre-filled.
- Email — opens the visitor's default email client with a pre-composed subject and body.
- Copy link — copies the vehicle URL to the visitor's clipboard.
Individual networks can be enabled or disabled in Features settings. The placement (above or below the description, for example) is also configurable.
PDF datasheet
When the PDF Datasheet feature is enabled, visitors can open a print-optimised HTML page for any vehicle, then use their browser's Print → Save as PDF function to create a PDF document.
The datasheet page is accessed by adding the query parameter ?as24ci_pdf={post_id} to the vehicle URL. A button or link to trigger this is typically included on the vehicle detail page when the feature is enabled.
Configurable fields
The following fields can be included or excluded in the datasheet (configurable by administrators):
Vehicle title, price, mileage, first registration, fuel type, transmission, power, body type, exterior colour, doors, seats, emission class, CO2 values, energy consumption, equipment list, description, location, and contact information.
Search Alerts (Smart Stock Alerts)
When the Search Alerts feature is enabled, visitors can subscribe to a saved search and receive an email notification when a matching vehicle is imported.
How it works for visitors
- On the archive page, after applying one or more filters, a Save search / Subscribe to alerts form is shown.
- The visitor enters their email address and submits the form.
- A GDPR-compliant Double-Opt-In confirmation email is sent. The subscription is in Pending status until the visitor clicks the confirmation link in the email.
- After confirming, the subscription becomes Active. From this point, the visitor receives an email notification whenever a vehicle matching their saved filter criteria is imported.
- Each notification email includes an unsubscribe link. Clicking it sets the subscription to Inactive (unsubscribed).
Notification trigger
Notifications are sent automatically on the as24ci_vehicle_imported action hook, which fires each time a vehicle is created or updated during an import run. The plugin checks all active subscriptions and sends emails to matching subscribers.
Administrator view
Active, pending, paused, and unsubscribed subscriptions are listed in the Search Alerts admin tab. Administrators can filter, view, and delete subscriptions.
Operational notes
- Filters are implemented as URL query parameters. Visitors can bookmark filtered views or share URLs with applied filters.
- Favorites and Compare use browser localStorage. Clearing browser storage or using a different device/browser loses the saved selection.
- The contact form posts back to the current page with a success or error query parameter. JavaScript is not required for form submission; the form works with standard HTML POST.
- The financing calculator is illustrative only. Results are computed in the browser from the configured defaults. They do not represent a binding credit offer.
- Test drive availability is evaluated server-side. The available dates and slots are derived from the configured settings at the time the page loads.
- Social sharing links are pure HTML anchors. No tracking cookies or third-party scripts are loaded. Click-through tracking is not built in.
- The PDF datasheet is a browser-rendered print page, not a server-generated PDF file. The print quality and layout depend on the visitor's browser and operating system.
- Search Alert emails are sent via WordPress
wp_mail(), which uses the server's email configuration. If email delivery is unreliable, consider configuring SMTP.
Troubleshooting
| Symptom | Likely cause | Check |
|---|---|---|
| No vehicles appear on the archive page | No published vehicles, or archive page is not configured | Run an import; check Default post status in Settings; verify the archive page exists and uses the shortcode or CPT archive URL |
| Filters show no results after selection | The selected value does not match any imported vehicle taxonomy term | Check that vehicles with the selected attribute have been imported; verify taxonomy term slugs |
| Favorites page is empty | No favorites are saved in the visitor's browser, or the page uses the wrong shortcode | Check that [as24ci_favorites] is in the page content; verify the Favorites feature is enabled |
| Compare page shows "no vehicles selected" | No vehicles are in the compare selection | Go to the archive and click Compare on vehicles first |
| Contact form shows an error after submission | A required field is missing, rate limit exceeded, or honeypot triggered | Check that name and email are filled; wait 5 minutes and try again |
| Test drive slots are empty for selected date | The date falls on an unavailable weekday or is a blackout date | Check the Test Drive configuration in the Leads tab |
| Financing calculator shows 0 or no price | Vehicle has no price in the imported data | Verify the vehicle has a price in the AutoScout24 listing; check the import |
| Social share buttons are not visible | Social Sharing feature is disabled | Enable Social Sharing in Features; configure desired networks |
| Search alert confirmation email not received | Email delivery issue, or the email went to spam | Check WordPress email delivery; check the spam folder; consider SMTP plugin |