=== Coverground ===
Contributors: covergroundeu
Tags: block, block-editor, embed, accessibility, travel
Requires at least: 6.8
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.2.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Show your Coverground routes as editable cards of native blocks. Pick a route in the editor and get notices when routes change.

== Description ==

[Coverground](https://coverground.eu) lets organisations publish guided walking and cycling routes. This plugin connects your site to your Coverground account and adds a **Coverground route** block: pick one of your published routes (or paste its web address into an empty paragraph) and the block builds a card — cover photo, title, a facts line, and a "Follow this route" button.

The card is made of ordinary core blocks (image, heading, paragraph, buttons), so you can restyle it, rewrite it, extend it with your own blocks, or delete parts of it. It follows your theme's colors and typography. Because the card saves as plain core blocks, your posts keep rendering even if you disconnect or deactivate this plugin.

Because your cards are yours, the plugin never rewrites them. Instead, a daily check compares your cards against Coverground and tells you in the WordPress admin when a route changed after you placed its card, when a card points to a route that is no longer published, and when your Coverground subscription has lapsed. Each block also shows this inline in the editor, with a one-click reload.

Two things worth knowing before you install: Coverground's map covers the Netherlands at the moment, so that is where routes can be built. A free Coverground account publishes two routes; paid plans add more.

== External services ==

This plugin requires Coverground (https://coverground.eu), a service where organisations build and publish walking and cycling routes. The plugin uses it to list your published routes and to fill the route cards. All requests are made by your WordPress server from the admin; your public pages load nothing from Coverground.

* Connecting (Settings → Coverground): you sign in on app.coverground.eu. Your site then sends the one-time approval code to app.coverground.eu and receives a read-only access token. Your site's domain is added to your allowed embed domains on Coverground.
* In the block editor and once a day (WP-Cron): your site sends the access token to api.coverground.eu to read your route list, route card data and subscription status.
* Loading a card: the route's cover photo is downloaded from Coverground and stored in your media library.
* Disconnecting: your site sends the access token to api.coverground.eu to revoke it.

The plugin adds no scripts, cookies or tracking to your pages and sends no data about your visitors. The "Follow this route" button is an ordinary link. A visitor who follows it is on Coverground, which counts route opens anonymously, without cookies, as described in its privacy statement.

This service is provided by Coverground, a trade name of Jeroen Smeets (Houten, the Netherlands).

* Terms of service: https://coverground.eu/terms/
* Privacy policy: https://coverground.eu/privacy/

== Installation ==

1. Upload the plugin to `/wp-content/plugins/` or install it through the Plugins screen, and activate it.
2. Go to Settings → Coverground and select **Connect to Coverground**. You are taken to app.coverground.eu to sign in and approve read access; approval also adds this site's domain to your allowed embed domains on Coverground.
3. Add the **Coverground route** block to a post or page and pick a route.

== Frequently Asked Questions ==

= What data is exchanged with Coverground? =

Connecting stores a read-only access token on your site, used to read your routes and subscription status. The plugin sends nothing about your site's visitors to Coverground — the published card is static content served by your site. See External services for what is sent and when.

= Can I use the block without connecting? =

No — the block needs the connection to list and load your routes. For embedding a route on a site you don't manage a Coverground account on, use the embed snippet from the route's Embed button in the Coverground dashboard instead.

= Do I need a paid Coverground plan? =

No. This plugin works on every Coverground plan, including the free one — a free account can publish two routes and show them here.

= Where does the card's photo live? =

When you load a route, its cover photo is copied into your media library and the card uses that copy — so your pages serve their own image and keep working fully even when Coverground is unreachable. Reloading a card after the photo changed on Coverground adds the new version as a new media item; older cards keep their own copy. The copies stay in your library until you delete them yourself. If the photo cannot be copied — for instance when you may not upload files — the card is built without an image and the editor shows a warning, with a button to try again.

= What if Coverground is down? =

Published pages are unaffected: cards are static blocks with their own image copy served by your site. In the editor, the route picker and card loading show a temporary error with a retry; the daily check simply keeps its last report. Only the "Follow this route" button depends on Coverground being reachable at the moment a visitor uses it.

= The photo has no alternative text — is that a mistake? =

Not necessarily. When the route owner marked the photo as decorative, the card deliberately uses empty alternative text: the title and facts line next to it already carry the meaning, so screen readers skip the photo instead of reading a redundant description. Add your own text if the image is meaningful in your page's context.

Since 0.2.1 the card marks its own language: the wrapper carries a `lang` attribute set from **Card text language**, so a Dutch card inside an English page is read by a Dutch voice rather than an English one. Set that language correctly and screen readers do the rest.

= My card is out of date =

Cards are snapshots you own, so they are never changed automatically. When a route changes on Coverground, the daily check flags it in the admin and the block shows a notice in the editor; use **Reload card from Coverground** to update it. Reloading replaces the card's blocks, including edits you made to them.

= Does the button open in a new tab? =

No — it is an ordinary link, which is the most accessible default. You can switch it to open in a new tab with the button's own link settings.

= How do I disconnect? =

Settings → Coverground → Disconnect, or revoke the site from the Embedding page in your Coverground dashboard. Existing cards keep working either way; the domain you approved stays on your allowed embed domains until you remove it there.

= Which admin notices does the plugin show? =

Only these three, and only when the daily check finds something: a card that is out of date, a card whose route is no longer published, and a lapsed Coverground subscription (administrators only). They appear on the Dashboard, the post and page lists and Settings → Coverground, and each can be dismissed. A dismissed notice returns only when what it reports changes. The plugin shows no upgrade prompts.

= Where is the source code? =

The plugin ships with its source. The block script and styles in `build/` are compiled from the files in `src/` with @wordpress/scripts (webpack, Babel, Sass). The PHP files and `assets/notices.js` are not compiled.

To rebuild `build/`, you need Node.js 18.12 or later. In the plugin folder, run `npm install`, then `npm run build`. `npm run start` rebuilds on every change; `npm run lint:js` and `npm run test:unit` run the linter and the unit tests.

== Screenshots ==

1. Settings → Coverground before the site is connected: what connecting gives the site, and the button that starts it.
2. Typing /coverground in the editor to insert the Coverground route block.
3. The block's route picker, searching the published routes on the connected account.
4. The finished card in the editor: cover photo, title, a Follow this route button, and a facts line with the number of stops and the distance.

== Changelog ==

= 0.2.3 =
* After activating, the admin now says the site is not connected yet and links to the settings page. The notice stays until the connection is made or attempted, and has no dismiss button — it clears itself once the setup is dealt with.
* The Coverground row on the Plugins screen has a Settings link.
* First release in the WordPress plugin directory: screenshots, an icon and a banner, and revised tags.

= 0.2.2 =
* The card only uses the cover photo copied into your media library. If the photo cannot be copied, the card is built without an image and the editor shows a warning, with a button to try again.
* A dismissed lapsed-subscription notice returns only when the subscription lapses again, not every month.
* The plugin includes its source code, and the readme documents the build steps and the external service it uses.

= 0.2.1 =
* The card now carries its own language, so a card written in one language inside a page written in another is read by the right voice. Cards saved by earlier versions keep working and are migrated the next time you save the post.

= 0.2.0 =
* Connection-first: connect the site to a Coverground account from Settings → Coverground (consent screen on app.coverground.eu; read-only token).
* Route picker in the block replaces the typed route reference; pasting a route URL into an empty paragraph creates the block.
* All route data flows through a same-origin REST proxy — no cross-origin requests from the editor.
* Daily check with admin notices: changed routes, unpublished routes, lapsed subscription. Inline editor notices with one-click reload.
* The route's cover photo is copied into the media library when a card loads, so published cards no longer depend on Coverground for their image.

= 0.1.0 =
* First release: single-route card block seeded from the Coverground embed data endpoint.
