=== WPCars24 ===
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 8.1
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Publishes a car dealership's vehicle stock in WordPress. The vehicles come from the WPCars24 platform, which imports them from AutoScout24.

== Description ==

A car dealership keeps its listings where the buyers already are: on a
marketplace such as AutoScout24. WPCars24 puts the same stock on the
dealership's own website, without a second round of data entry and without
anyone having to remember to keep the two in step.

The WPCars24 platform fetches the listings from the marketplace, normalises
them into one consistent vehicle model and holds them per dealership. This
plugin is the WordPress end of that chain: it mirrors the stock into your site
and renders it.

= Mirrored, not proxied =

Every vehicle becomes a regular post of its own post type, with taxonomies for
make, model, fuel, body, transmission and more. Permalinks, the built-in
search, page caching and your theme therefore behave exactly as they do for
any other content, and each page is built from the local copy rather than from
a request to the platform. When the platform is unreachable, your site keeps
serving its vehicles.

Images are the deliberate exception: they are linked from the marketplace
instead of being copied into your media library. A dealership with 300
vehicles at 20 pictures each would otherwise carry 6000 attachments. What that
means for your visitors is in "External services" below.

= Try it for free, keep it with a subscription =

The plugin offers two ways to start, side by side:

* **Try for free.** Start the demo without an account, an email address or a
  licence key. Up to five vehicles from your stock appear on your website and
  are updated once a day. The demo has no time limit.
* **I have a licence key.** With a subscription your entire stock appears and
  keeps itself up to date every hour.

The limits are set by the platform, not by this plugin. If you buy a
subscription while the demo is running, enter the licence key on the same
page: the demo carries over, including the access to your marketplace
account, and the entire stock follows.

When a subscription ends, the plugin falls back to the demo instead of
stopping. Five vehicles keep being updated once a day; the others stay on your
website unchanged until you renew.

Either way you need API credentials for a supported source platform,
currently AutoScout24, whose support provides them. That is where your
vehicles come from.

= Updates =

WPCars24 is not distributed through the WordPress.org plugin directory. New
versions come from the WPCars24 platform and are offered in your plugin list
like any other update, and you can switch on automatic updates there as usual.
"View details" lists what has changed.

Before a package is installed, the plugin checks that it is newer than the
installed version, that its checksum matches and that it carries a valid
WPCars24 signature. A package that fails any of these checks is not
installed, and the current version stays in place.

Updates are offered once this installation is connected to the platform,
through the demo or with a licence key.

= Shortcodes =

Two shortcodes build the overview:

* `[wpcars24_vehicles]` renders a list of vehicles. It takes `limit`,
  `orderby`, `pagination`, `filter`, `fields` and `id`, and `make`, `model`,
  `fuel`, `body`, `transmission` or `usage` restrict it to certain values.
* `[wpcars24_filter]` renders the search form on its own, for a sidebar or a
  landing page. It takes `for`, `fields` and `url`.

`[wpcars24_vehicle]` renders a complete vehicle page anywhere; `sections`
chooses its parts and their order. `[wpcars24_vehicle_header]` renders its
upper half, price and gallery, and `[wpcars24_vehicle_details]` everything
below.

Ten more compose a vehicle page out of parts, so the layout stays yours:
`[wpcars24_title]`, `[wpcars24_gallery]`, `[wpcars24_image]`,
`[wpcars24_specs]`, `[wpcars24_envkv]`, `[wpcars24_equipment]`,
`[wpcars24_description]`, `[wpcars24_seller]`, `[wpcars24_location]` and
`[wpcars24_link]`. If a template of your theme or page builder places them,
tick "Design the vehicle pages yourself" under WPCars24 › Settings, so the
plugin does not add its own sections as well.

Below those, 40 shortcodes each print exactly one value — `[wpcars24_price]`,
`[wpcars24_mileage]`, `[wpcars24_power]`, `[wpcars24_fuel]`,
`[wpcars24_registration]` and so on — for page builders and custom templates.
`[wpcars24_field name="…"]` prints any of them by its name. Each of them stays
silent when a vehicle has no such value, so a missing figure never leaves a
stray label behind, unless you give it a replacement text with `empty`.

A complete reference, with every parameter and all 40 value names, is
available from WPCars24.

= Templates =

`vehicle-card.php` and `vehicle-empty.php` can be replaced by a theme. Copy
them from the plugin's `templates` directory into a `wpcars24` directory
inside your theme; the plugin then uses your copy. Each bundled template
carries a version in its header, so you can tell whether the original has
changed since you copied it.

= Stylesheets =

The plugin ships two stylesheets. `wpcars24-base` keeps the grid, the spacing
between blocks, the gallery and the image formats in shape and is always
loaded. `wpcars24-theme` adds borders, surfaces, rounded corners and font
sizes; the filter `wpcars24_load_stylesheet` switches it off for themes that
style the vehicles themselves. A rule with the same single class overrides
almost every rule of both. The exceptions keep themes from adding margins and
indents to lists, paragraphs and form fields; the theme guide available from
WPCars24 lists them.

= What stays stable =

You can build a child theme, a page builder template or custom CSS on these,
and they change only with a new major version: the CSS classes and custom
properties, the shortcodes with their parameters, the hooks with their
callbacks, priorities and arguments, the filters, the query parameters in
addresses, the template names with `$wpcars24_args`, and the handles
`wpcars24-base`, `wpcars24-theme` and `wpcars24-gallery`. When one of them
changes, the old name keeps working for one more major version: shortcodes as
an alias, filters through `apply_filters_deprecated()`, classes as a second
class. Everything else, such as PHP classes outside the hooks and the names of
options and meta fields, may change in any version.

= Consumption and CO2 figures =

German law (Pkw-EnVKV) requires the mandatory figures to be stated together
and in a prescribed form. `[wpcars24_envkv]` renders them as one block for
that reason, and it is the one section shortcode that takes no field
selection: it is not meant to make it easy to build a page that breaks the
rules. The individual figures remain available as single shortcodes for cases
where you know what you are doing.

= Car-Pass =

In Belgium, dealers have to link the Car-Pass, the vehicle's odometer history,
in every online used car advert. When AutoScout24 supplies one, the vehicle
page shows the official Car-Pass logo in the vehicle data, directly below the
mileage; it opens that history in a new tab. The logo ships with the plugin, so car-pass.be learns
nothing about your visitors until one of them clicks it. Vehicles without a
Car-Pass are unaffected, and the vehicle list never shows it.

= External services =

This plugin depends on external services. Nothing leaves your site before you
start the demo or enter a licence key.

**The WPCars24 platform** (`https://api.wpcars24.de`) holds your access and
your vehicle data. The plugin contacts it:

* when you start the demo or connect this installation: it sends the address
  of this WordPress site, the plugin version and the WordPress version, and
  when you connect, also the licence key. It receives a token for this
  installation in return. No account and no email address are asked for;
* on every later request: that token travels in the `Authorization` header;
* to show what your access includes, such as the demo or a subscription, the
  vehicle limit and the available intervals. The answer is kept for an hour;
* when you set up a source platform: your API username and password for the
  marketplace are passed to the platform, which stores them encrypted and
  uses them to fetch your listings. They are not stored in WordPress;
* on a schedule and when you click "Synchronise now": to fetch vehicles and
  the vocabulary used for the labels;
* when WordPress checks for updates: it sends the installed version and
  receives the newest version on offer. An update package is downloaded from
  the platform as well;
* when you delete the plugin: one request deregisters this installation, so
  the slot it occupied in your licence becomes free again.

The plugin sends no visitor data to the platform. So that a change does not
have to wait for the next scheduled run, the plugin also registers one route
the platform can call: `POST /wp-json/wpcars24/v1/sync`, which carries a
signature and a timestamp and triggers nothing but a sync.

The buttons "Buy a licence", "Unlock now" and "Renew now" open the WPCars24
pricing page, https://www.wpcars24.de/pricing/, in a new tab. Nothing is sent
before you click.

Terms: https://www.wpcars24.de/agb/
Data processing agreement: https://www.wpcars24.de/avv/
Privacy policy: https://www.wpcars24.de/datenschutzerklaerung/

**AutoScout24** is where the listings come from, and it also serves their
images. Because images are linked rather than copied, a visitor's browser
loads them straight from `prod.pictures.autoscout24.net`, and AutoScout24
therefore receives that visitor's IP address and user agent, as with any
externally hosted image. The link to the original listing on
`www.autoscout24.de` is only followed when a visitor clicks it.

Privacy policy: https://www.autoscout24.de/unternehmen/datenschutz/
Terms: https://www.autoscout24.de/unternehmen/verbraucher-agb/

If your jurisdiction requires it, name both services in your own privacy
policy.

== Installation ==

1. Download the plugin as a ZIP file from wpcars24.de. In WordPress, go to
   Plugins › Add Plugin › Upload Plugin, upload the file and activate it.
2. Go to WPCars24 › Connection. Click "Start demo", or enter your licence key.
   The installation registers itself with the platform and receives a token.
3. Go to WPCars24 › Source platform and enter your AutoScout24 API
   credentials. They are forwarded to the platform and stored there,
   encrypted.
4. The first fetch starts on its own. You can watch its progress on the same
   page; a large stock arrives in several passes.
5. Put `[wpcars24_vehicles]` on a page for the overview. The individual
   vehicle pages work without any further setup.

The plugin needs WordPress to be able to run scheduled tasks. If WP-Cron is
switched off on your installation, set up a real cron job for `wp-cron.php`.
Otherwise the stock is only refreshed when the platform announces a change, or,
with a subscription, when you click "Synchronise now".

== Frequently Asked Questions ==

= Do I need an account? =

Not for the demo: it starts without an account, an email address or a
licence key. For your entire stock you need a WPCars24 subscription. In both
cases you need an account with a supported marketplace, currently AutoScout24,
because that is where your vehicles come from.

= What does the demo include? =

Up to five vehicles from your stock, updated once a day, for as long as you
like. If your stock is larger, the Source platform page tells you how many
vehicles were not taken over.

= What happens when my subscription ends? =

The plugin falls back to the demo. The five vehicles that were added most
recently keep being updated once a day. The others stay on your website
exactly as they are, including any that have been sold in the meantime, until
you renew. After a renewal, the entire stock is brought up to date with the
next fetch.

= Which marketplaces are supported? =

AutoScout24 at the moment. The connection to a marketplace lives in the
platform rather than in this plugin, so further ones can be added without you
having to update the plugin.

= Are the images copied into my media library? =

No, they are linked. That keeps your database and your backups small, and a
picture the dealership replaces on the marketplace is current on the website
too, without a new import. The trade-off is that your visitors load the
pictures from AutoScout24, which is described under "External services".

= How often is the stock refreshed? =

With a subscription, the platform fetches your listings from the marketplace
hourly, every 12 hours or every 24 hours, whichever you choose; hourly is the
default. The demo fetches once a day. When a fetch brings changes, the
platform notifies your site, so they appear right away instead of at the
plugin's next scheduled run. With a subscription, "Synchronise now" starts an
additional fetch, at most once an hour. In the demo and after a subscription
has ended, the button is locked.

= What happens to a vehicle that is no longer listed? =

You decide, under WPCars24 › Source platform › Vehicles no longer listed:
delete it permanently, which is the default, move it to the trash, set it back
to draft, or keep it on the website. A vehicle that stays is marked "No longer
listed" in the admin list. The setting also applies to vehicles that are
already no longer listed. If a vehicle is listed again, it comes back from the
trash or the drafts under its previous address.

The fallback after a subscription has ended is the one exception: there, the
vehicles beyond the five stay on your website unchanged until you renew,
including any that have been sold.

= Can I use my own markup? =

Yes, at three levels. Replace the bundled templates from your theme, compose a
vehicle page out of the ten section shortcodes, or build it value by value out
of the 40 single shortcodes.

= How do I get updates? =

Through WordPress, like any other plugin, but from the WPCars24 platform
instead of WordPress.org. See "Updates" above.

= What does deleting the plugin remove? =

It deregisters this installation from the platform so the licence slot becomes
free again, and it removes the plugin's own options, its cached data, its
scheduled tasks and the stored token. The vehicles themselves stay: a plugin
you briefly remove and reinstall must not cost you your entire stock and every
address a search engine has already indexed. Delete them in the admin if you
want them gone — that is a decision of its own.

= Which languages does the plugin speak? =

English, German, Spanish, French, Italian and Dutch. One setting covers the
vehicle data the marketplace supplies, such as fuel types, transmissions and
equipment, the labels on the vehicle pages, the number and price format and
the plugin's own admin pages. By default it follows the location of the
dealership, because AutoScout24 names no language for a dealer; in a country
with several languages, the more widespread one is chosen. A fixed language can
be chosen under WPCars24 › Settings. Your own texts, such as the description,
appear as you wrote them.

== Changelog ==

WordPress shows the changes of every version under Plugins › View details,
together with each update.
