Car Search Form

Overview

The CarSearchForm component is a comprehensive vehicle search form that allows users to filter cars by various criteria and display matching results. It includes pagination, filtering options, and the ability to redirect to a search results page.

Installation

The component is part of the Carpose application and requires no separate installation.

Usage

To use the CarSearchForm component in a standard HTML page, you only need two required attributes:

<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
></div>

This minimal setup will display a search form with inline results. See the Examples section below for more advanced configurations including wishlist, comparison, and redirect functionality.

Configuration Attributes

The component reads configuration from data attributes on the provided element:

Required Attributes

Attribute	Type	Description
data-carpose-component	string	Identifies the component type, must be set to "car-search-form"
data-api-key	string	API key for authentication with the Carpose backend services

Optional Attributes

Attribute	Type	Default	Description
data-search-url-forward	string	null	URL to redirect to when search button is clicked. When set, no results are shown inline - instead saves form state to localStorage and redirects to the specified URL. The target page must have another car-search-form component to read the localStorage state and display the results. When null, results are displayed inline below the form.
data-force-scroll-to-top	boolean	false	When true, forces window to scroll to the top when changing pages or filters.
data-enable-page-load-focus	boolean	false	When true, enables focus behavior when a page loads.
data-default-form-state-hash	string	null	Default form state (base64-encoded) to use when resetting the form. If not provided, a new empty form state will be created.
data-wishlist	boolean	false	When true, enables wishlist functionality allowing users to save cars to a favorites list.
data-compare	boolean	false	When true, enables comparison functionality allowing users to compare up to 3 cars side by side.

Features

• Filtering by manufacturer, model, condition, mileage, construction year, engine type, vehicle type, fuel type, store, and price

• Additional detailed filters accessible via "weitere Filter anzeigen" button

• Real-time vehicle count display

• Reset button to clear all filters

• Pagination for search results

• Responsive layout that adapts to different screen sizes

• Wishlist functionality for saving favorite vehicles (when enabled)

• Comparison functionality for comparing up to 3 cars side by side (when enabled)

• Icon-overlay buttons on car thumbnails for quick wishlist and comparison actions

Wishlist Functionality

When wishlist functionality is enabled via the data-wishlist="true" attribute, users can:

1. Save vehicles to a wishlist that persists between sessions (stored in browser localStorage)

2. Access saved vehicles through a floating wishlist button that appears in the UI

3. View all saved vehicles in a slide-out drawer

4. Select vehicles from their wishlist to send an inquiry

5. Remove vehicles from their wishlist

6. Navigate directly to vehicle detail pages from the wishlist

The wishlist integration consists of:

• WishlistButton component added to each car card

• WishlistFloatingButton component displayed in the UI when wishlist is enabled

• WishlistContext provider that manages the wishlist state across the application

Example with Wishlist Enabled

<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
  data-search-url-forward="/search-results"
  data-wishlist="true"
></div>

Comparison Functionality

When comparison functionality is enabled via the data-compare="true" attribute, users can:

1. Add up to 3 vehicles to a comparison list that persists between sessions (stored in browser localStorage)

2. Access the comparison view through a floating comparison button that appears in the UI

3. View all selected vehicles side by side in a modal for easy comparison

4. Compare key vehicle specifications including:

   • Price and VAT information

   • Registration date and mileage

   • Power and engine specifications

   • Transmission and fuel type

   • Additional specifications (cubic capacity, seats, doors, colors)

5. Remove vehicles from the comparison

6. Navigate directly to vehicle detail pages from the comparison view

7. Responsive layout: 1 car (full width), 2 cars (50/50 split), 3 cars (equal thirds)

8. Mobile-optimized horizontal scroll view for comparing vehicles on smaller screens

The comparison integration consists of:

• ComparisonButton component added to car cards and detail pages

• ComparisonIconButton component displayed as overlay on car thumbnails

• ComparisonFloatingButton component displayed in the UI when comparison is enabled

• ComparisonContext provider that manages the comparison state across the application

Example with Comparison Enabled

<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
  data-search-url-forward="/search-results"
  data-compare="true"
></div>

Example with Both Wishlist and Comparison Enabled

<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
  data-search-url-forward="/search-results"
  data-wishlist="true"
  data-compare="true"
></div>

Examples

Basic Example

<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
  data-search-url-forward="/search-results"
></div>

Full Example with All Options

<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
  data-search-url-forward="/search-results"
  data-force-scroll-to-top="true"
  data-enable-page-load-focus="true"
  data-default-form-state-hash="eyJtYW51ZmFjdHVyZXIiOiIifQ=="
  data-wishlist="true"
  data-compare="true"
></div>

Two-Page Setup Example

When using data-search-url-forward, you need two pages:

Page 1: Search Form (e.g., /index.html)

<!-- Form only - redirects to results page on submit -->
<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
  data-search-url-forward="/search-results"
  data-wishlist="true"
  data-compare="true"
></div>

Page 2: Results Page (e.g., /search-results.html)

<!-- Form + Results - displays results inline based on localStorage -->
<div
  data-carpose-component="car-search-form"
  data-api-key="your-api-key"
  data-wishlist="true"
  data-compare="true"
></div>

In this setup:

• The form on Page 1 saves the form state to localStorage and redirects to /search-results

• The form on Page 2 reads the form state from localStorage and displays the results inline

Behavior

1. Search Mode:

   • With data-search-url-forward set: Clicking the search button redirects to the specified URL. The form state is saved to localStorage for that specific page path. No results are shown inline. The target page must include another car-search-form component to read the localStorage state and display the results.

   • Without data-search-url-forward (or set to null): Search results are displayed inline directly below the form on the same page.

2. Form State Persistence:

   • Form state is stored in browser localStorage with page-specific keys.

   • State persists across page reloads and browser sessions.

3. Form Reset:

   • The reset button restores form to default state.

   • The default state is determined by data-default-form-state-hash if provided, otherwise a new empty state is created.

4. Scrolling Behavior:

   • Control scroll behavior with data-force-scroll-to-top and data-enable-page-load-focus.

5. Wishlist Behavior:

   • Enable wishlist functionality with data-wishlist="true".

   • Wishlist state persists between sessions through localStorage.

   • Users can send inquiries for multiple vehicles at once from their wishlist.

   • Success messages are shown when adding or removing vehicles from the wishlist.

6. Comparison Behavior:

   • Enable comparison functionality with data-compare="true".

   • Comparison state persists between sessions through localStorage.

   • Users can compare up to 3 vehicles side by side.

   • Warning message is shown when trying to add more than 3 vehicles.

   • Success messages are shown when adding or removing vehicles from the comparison.

   • Responsive column layout: 1 car (full width), 2 cars (50/50), 3 cars (equal thirds).

7. Pagination:

   • When inline search results are displayed, results are paginated with 30 items per page.

   • Pagination controls are shown at the bottom of the results when there are multiple pages.