=== KlubOS ===
Contributors: klubos
Tags: sports club, class schedule, news, calendar, sign-up form
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 3.4.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Show your sports club's schedule, news, pricing, calendar, gallery and sign-ups on WordPress, straight from KlubOS. Set up in 10 minutes.

== Description ==

**You enter the data once in KlubOS, and your WordPress site shows it on its own.**

KlubOS is a management system for sports clubs: groups, class schedule, fees, sign-ups and a Parent Zone. This plugin puts on your WordPress site what the club already keeps in KlubOS. No retyping, no second place to edit, no developer needed. The plugin needs a KlubOS club account (a free 14-day trial can be created from the plugin's wizard).

**How to start (about 10 minutes):**

1. Install and activate the plugin. The "KlubOS in 10 minutes" wizard opens.
2. Step 1: connect your club with a key or a code, or create a trial club (14 days free, no card) right in the wizard. The key comes back to the plugin on its own after you click the link in the e-mail.
3. Step 2: add groups, the schedule and pricing in the KlubOS panel. The wizard shows live what is already there.
4. Step 3: the wizard creates page drafts (Schedule, News, Sign-ups, Pricing, Parent Zone, Staff) with the modules inside.
5. Step 4: review the drafts and publish when you are ready. Nothing is ever published on its own.

**Native modules (HTML rendered on your server, no iframe):**

* **News**: list or tiles, number of posts, category, photos, dates, excerpts. Article structured data.
* **Class schedule**: a week of classes, filters by group, coach and day (day buttons on a phone), a "today" mode calculated in the browser, a group list with fees and free spots. Structured data for classes.
* **Pricing and passes**: group fees, passes and other charges. Offer structured data.
* **Staff**: coaches with a photo, role and bio, without phone numbers and e-mails. Person structured data.
* **Results and matches**: competition results, season medals, team matches and the league table. Children under 12 are always shown without names.
* **Event calendar** (new in 3.2: month view): the nearest events or a month grid (a list of days on a phone) with arrows that browse months without reloading the page. Event structured data.
* **Photo gallery** (new in 3.2): albums with covers or the photos of one album, with a lightbox without any libraries, responsive images and ImageGallery structured data.
* **Sponsors** (new in 3.2): sponsor logos with links marked rel="sponsored noopener".
* **Sign-up form**: groups, sections and the data processing consent come from KlubOS, and the submission goes straight from the visitor's browser to the club. Personal data is not stored in WordPress.
* **Class finder** (new in 3.3): a compact form (age, discipline or group, day) that opens the schedule or the sign-up form with the filters already set.
* **Parent Zone**: a button to the club app, with no frame and no sign-in form on your site.

**Page builders:** the plugin detects Elementor, Divi, YOOtheme, Beaver Builder, Bricks and WPBakery, shows where to paste a module in your builder, and creates page drafts in a format the builder opens (Elementor gets KlubOS widgets). Every module also works as a plain shortcode in any builder.

**Languages:** English (source language) and Polish are included. Other languages can be added on translate.wordpress.org. Days of the week and months follow the site language.

**Local SEO:** on the home page the plugin can add SportsOrganization structured data (address, phone, class hours, profiles). It switches itself off when Yoast SEO, Rank Math, All in One SEO or SEOPress is active.

**Why native, not an iframe:**

* faster, because there is no second page to load in a frame,
* it looks like your site: font from the theme, your club's colors fetched from KlubOS, light and dark mode,
* no problems with frame height, scrolling and phones,
* it keeps working when KlubOS is briefly unavailable: the site shows the last good data,
* Google sees the content because it is in the page HTML.

**Appearance without configuration, and with full control:** modules take the accent color and logo of the club from KlubOS. In the Appearance tab you change the accent, text and card colors, corner radius, font (inherited from the theme by default), width and density, with a live preview. Everything is a CSS variable (--kl-akcent, --kl-tekst, --kl-tlo, --kl-rogi and others) that your theme can override.

**Other KlubOS modules** (shop, facility rental, classes and passes, fee payments) still run in a frame from the club panel, as in version 2.0, and will get native versions in later releases.

**Four ways to insert a module:** the shortcode [klubos modul="aktualnosci"], a block in the block editor (options in the side panel), a classic widget and an Elementor widget.

**Security and data:** the plugin does not store any personal data of visitors in the WordPress database. Modules show only content that the club has published in KlubOS. WordPress safeguards are used throughout: nonces, capability checks, input sanitization and output escaping.

== External services ==

This plugin is a connector to the KlubOS service (https://www.klubos.pl), operated by the plugin's author. Without a KlubOS club account the plugin has nothing to show. The KlubOS terms of service are at https://www.klubos.pl/regulamin and the privacy policy at https://www.klubos.pl/polityka-prywatnosci.

* **Content modules** (news, schedule, pricing, staff, results, calendar, gallery, sponsors, the sign-up form definition, club contact data for structured data). Your WordPress server requests the public KlubOS API (the /api/wtyczka/v1/ path on the www.klubos.pl domain; it answers only requests that carry a club key) and keeps the answer in a cache for 5 minutes. What is sent: the public club key that you enter in the plugin settings and the module parameters (for example the number of posts or the month). The calendar's month view also calls your own site's REST route /wp-json/klubos/v1/kalendarz, which fetches the data from KlubOS in the same way. Photos and sponsor logos are loaded by the visitor's browser through the /api/wtyczka/v1/zdjecie path on the same domain, so KlubOS sees the visitor's IP address and browser data as in any image request.
* **Sign-up form.** When the visitor starts using the form, the browser asks the /api/wtyczka/v1/token path on the same domain for a signed time token (only the club identifier in the address; used against bots). When the visitor clicks Send, the browser sends the submission (name, contact, chosen group, consent, the token and, if present, the first-visit source: UTM parameters, landing page and referring site kept in the browser tab's session storage) directly to the KlubOS submission function (submit-lead), which runs on Supabase, the database and functions provider of the KlubOS service (the address on the supabase.co domain is given by the KlubOS API in the form definition and the plugin accepts only an address of that exact form). Supabase terms of service: https://supabase.com/terms, privacy policy: https://supabase.com/privacy. The data does not pass through your WordPress server. The club is the data controller. If the KlubOS operator turns on bot verification, the browser also loads the Cloudflare Turnstile script from https://challenges.cloudflare.com (off by default; Cloudflare privacy policy: https://www.cloudflare.com/privacypolicy/).
* **Domain registration and plugin pulse** (only for a site connected with a code): once a day and after the site address changes, your WordPress server sends to KlubOS, with a signed request, the address of this site and the plugin version. KlubOS uses it to allow the sign-up form on that address and shows the version and last contact date in the club panel.
* **Create a club wizard.** After you click the button, your WordPress server sends to KlubOS the club name, discipline, city, e-mail address and name of the administrator, the address of this site and your acceptance of the terms, in order to create a trial club. Then every few seconds it asks with a one-time token whether the club is confirmed.
* **Frame modules** (the fallback mode and modules without a native version): the visitor's browser loads a frame from KlubOS (the /e/ path on the club's klubos.pl address or on www.klubos.pl). The WordPress admin screens do not embed any KlubOS page in a frame: the settings preview only offers a link that opens in a new tab. In the version distributed outside the WordPress.org directory a helper script from the same domain adjusts the frame height; the directory edition does not load any remote script.
* **Connection with a code** (optional): once, the address of your site and the plugin version, then signed reads of the club state (name, available modules, choice lists for the editor).
* **Updates** (only in the version distributed outside the WordPress.org directory): a read of https://www.klubos.pl/pobierz/klubos-wordpress.json every few hours (version number, package address, SHA-256 checksum of the package, which the plugin verifies before installing).

The plugin does not send data of visitors or WordPress users to KlubOS (apart from the wizard described above, which sends the data of the administrator creating the club, and the sign-up form that the visitor submits on purpose) and does not store personal data of visitors in the WordPress database. The exception is content published by the club: the cache of the Schedule and Staff modules keeps coaches' names as shown on the site.

== Installation ==

1. Plugins, Add New, Upload Plugin, choose klubos-wordpress.zip, Install, Activate. (From the WordPress.org directory: search for "KlubOS" and install.)
2. The wizard opens (KlubOS menu, Start tab): connect your club with a key (KlubOS panel, Club website, Embeds) or a code (8 characters), or create a trial account.
3. Fill in groups and the schedule in the KlubOS panel, then in the wizard create page drafts and publish them when they are ready.
4. In the Modules tab copy a shortcode, for example [klubos modul="grafik"], or in the editor click "+", type "KlubOS" and choose a module.
5. Optionally in the Appearance tab: color, corner radius, width.

Examples: [klubos modul="aktualnosci" ile="6" uklad="karty"], [klubos modul="grafik" uklad="tydzien"], [klubos modul="grafik" uklad="dzisiaj"], [klubos modul="cennik"], [klubos modul="kadra" uklad="siatka"], [klubos modul="wyniki"], [klubos modul="kalendarz" widok="miesiac"], [klubos modul="galeria" album="turniej"], [klubos modul="sponsorzy" kolumny="4"], [klubos modul="zapis"], [klubos modul="logowanie"].

== Frequently Asked Questions ==

= Where do I get the club key? =

KlubOS panel, Club website, Embeds. The key has 32 characters. You can also use a connection code (the "Connect WordPress site" button, 8 characters, valid for 15 minutes).

= Do I need a KlubOS account? =

Yes, it holds the data. You can create a trial account in the wizard (Start tab) for 14 days, no card.

= I created a club in the wizard. What next? =

Click the link in the e-mail from KlubOS and set a password. The wizard checks on its own whether the club is confirmed and connects the site after a moment. If that address already had a KlubOS account, it receives a regular sign-in link: then paste the key from the panel.

= I changed something in KlubOS, but the site shows old data =

Modules refresh every 5 minutes. Right after a change click "Refresh data from KlubOS" in the Connection tab. If you use a page caching plugin, clear its cache.

= What happens when KlubOS does not respond? =

The site shows the last good data instead of an empty space. Editors see a short note, visitors do not.

= Does the sign-up form store data in WordPress? =

No. The visitor's browser sends the submission straight to KlubOS and it lands in "Website submissions" in the club panel. The form works only on the club's site domain: add it in the KlubOS panel (Club website, Embeds, Domains) if you did not connect the site with a code or the wizard.

= How do I match the look to my theme? =

Modules inherit the font from the theme. You set colors and corner radius in the Appearance tab, and the theme can override them with CSS variables, for example :root { --kl-akcent: #e11d48; }.

= Does it work with Elementor, Divi, YOOtheme, Beaver Builder, Bricks and WPBakery? =

Yes. The plugin detects the builder, shows where to paste a module and creates page drafts in the builder's format. Elementor has KlubOS widgets in the "KlubOS" group, and in the other builders you paste a shortcode.

= Is the plugin available in English? =

Yes. English is the source language of the plugin. The package from klubos.pl bundles a Polish translation, so a Polish site shows Polish; the WordPress.org edition gets translations from translate.wordpress.org. A site in any other language shows English until a translation is installed from WordPress.org (you can contribute one at translate.wordpress.org). Days of the week and months follow the site language.

= I have version 2.0. Will anything change after the update? =

Not until you want it to. Pages with plugin 2.0 stay in frame mode: shortcodes, blocks and widgets work as before. You switch to native modules with one button in the Modules tab or with the option osadzenie="natywnie" in a single module.

= I want to go back to the frame =

Modules tab: "In a frame (fallback mode)" for the whole site, or the option osadzenie="ramka" in a single module.

= A frame module shows a gray rectangle =

The domain of this site is not on the club's domain list. Connect the site with a code or add the domain in the KlubOS panel (Embeds, Domains). Native modules (except the sign-up form) do not have this limitation.

= Old [klubos adres="..."] shortcodes from version 1.x =

They work unchanged, and so does the "KlubOS embed" block.

== Screenshots ==

1. The "KlubOS in 10 minutes" wizard: account, club data, page drafts, done.
2. The Modules tab: a ready shortcode, options and a preview of every module.
3. The Appearance tab with a live preview.
4. Month view of the calendar on a phone and on a computer.
5. Photo gallery with a lightbox, and sponsor logos.

== Changelog ==

= 3.4.1 (2026-10-24) =
* Review fixes for the WordPress.org directory: no external page is embedded in a frame in the WordPress admin (the settings preview is now a link that opens in a new tab), nonce and capability checks sit directly in every request handler, the readme lists every external service with its terms and privacy links, and the directory edition no longer bundles translation files or calls load_plugin_textdomain (translations come from translate.wordpress.org). The package from klubos.pl still bundles the Polish translation.

= 3.4.0 (2026-10-23) =
* English is now the source language of every text in the plugin (WordPress.org directory requirement). The Polish translation is bundled with the plugin and a Polish site looks exactly as before. A site in another language shows English until a translation is installed from WordPress.org.
* Plurals (groups, sessions, coaches, posts, passes, photos, medals) use WordPress plural forms, so translations can have the correct number of forms (Polish has three).
* Fix: the club key field in the wizard fits inside its card on a phone.
* Updated screenshots and the directory edition of the package (no own updater, no remote script).

= 3.3.0 (2026-10-22) =
* Ready for live clubs: updates are verified with a SHA-256 checksum before installation (only https and the klubos.pl host), a mismatch stops the update with a clear message.
* The site address is registered in KlubOS automatically (daily WP-Cron task and right after the site address changes, with and without www). If KlubOS rejects the domain, an administrator sees a short message with a "Fix" button, visitors a polite general message.
* Sign-up form: bot protection with a signed time token issued by KlubOS, limits per IP and per e-mail address, a limit of pending submissions per group, optional Cloudflare Turnstile (off by default). The "I have read the information" consent is separate from the consent to be contacted, and the notice names the club as the data controller.
* Works with cache and optimization plugins (LiteSpeed Cache, WP Rocket, W3 Total Cache, Autoptimize, Cloudflare): 5-minute cache, pages without data are never cached, "Refresh data from KlubOS" clears the page cache, plugin scripts are excluded from combining and delaying.
* New "Test connection" button and tests in Tools, Site Health: key and its scope, API reachability, domain registration, a page with a module, detected cache plugins, PHP and WordPress versions, plugin version. KlubOS shows the plugin version and the last contact in the club panel.
* The club key field is a password field with a "Show" button, the settings are not autoloaded, disconnecting removes the cron task and cached state.
* New: class finder module (age, discipline or group, day) that opens the schedule or the sign-up form with filters already set.
* New: an optional "Sign up" bar on phones (safe area on iOS, hidden when the keyboard is open).
* New: analytics events without tracking (klubos:* CustomEvents and window.dataLayer for GA4) and the first-visit source (UTM) attached to the sign-up.

= 3.2.0 (2026-10-21) =
* New: month view of the calendar (a grid, a list of days on a phone, arrows that browse months without reloading the page).
* New: Photo gallery module (albums and photos, a lightbox without libraries, responsive images, ImageGallery structured data) and Sponsors module (logos, links with rel="sponsored noopener").
* Page builders: detection of Elementor, Divi, YOOtheme, Beaver Builder, Bricks and WPBakery, instructions in the Modules tab, page drafts in the builder's format, Elementor widget for Pricing.
* English version of the interface and modules, days of the week and months follow the site language.
* The league table shows the club team's official name.
* Panel: tabs scroll on a phone, compact wizard buttons.
* Preparation for the WordPress.org directory: the directory edition has no own updater and loads no remote script.

= 3.1.0 (2026-10-15) =
* New: the "KlubOS in 10 minutes" wizard (Start tab, opens after activation): connect or create a trial club from WordPress, live club status, page drafts with modules, a checklist on the dashboard.
* New native modules: Pricing and passes, Staff, Results and matches with the league table, Event calendar, Sign-up form and Parent Zone (a button to the club app).
* The sign-up form sends the submission from the browser straight to KlubOS, without storing personal data in WordPress. Bot protection: a honeypot field, a minimum fill time, a rate limit and a domain check on the KlubOS side.
* News and staff photos go through the KlubOS CDN with a long cache.
* Local SEO: SportsOrganization structured data once on the home page (setting in the Settings tab).
* Schedule: on a phone the day is chosen with buttons, the "today" view calculates the day in the browser (works with cached pages).
* Excerpts and bios fade out instead of ending with an ellipsis. The Modules tab is compact on a phone (collapsible groups).
* Compatible with WordPress 7.1.

= 3.0.0 (2026-10-14) =
* New: native News and Class schedule modules. HTML on the server, structured data for Google, a 10-minute cache and the last good copy when KlubOS fails.
* Schedule: week view, lists of groups and today's classes, filters by group, coach and day, a list of days on a phone.
* KlubOS menu with the Connection, Modules, Appearance, Frame modules and Help tabs.
* Connection with the club key alone or with a code. The club's colors and logo are fetched from KlubOS.
* Appearance: accent, text and background colors, corner radius, font, width, density, live preview. CSS variables --kl-*.
* Shortcode generator and a preview of every module in the panel.
* Own updates from WordPress and a "Check for updates" button.
* Backward compatibility: pages with plugin 2.0 stay in frame mode, all shortcodes, blocks and widgets work as before.

= 2.0.0 =
* Settings screen: connect the site with a code from the KlubOS panel, default appearance with a live preview, fetching the appearance from the KlubOS configurator.
* A separate block for every KlubOS module with a side panel for content and appearance.
* The [klubos modul="..."] shortcode, a classic widget, Elementor widgets, a button in the classic editor.
* Signed connection with KlubOS (site secret), automatic key change after rotation in the panel.
* A fallback link under the module when KlubOS does not respond.
* Translations (text domain klubos), uninstall cleans up the settings.

= 1.1.0 =
* Configurator parameters as shortcode attributes, validation of address parameters.

= 1.0.0 =
* The shortcode and the "KlubOS embed" block.

== Upgrade Notice ==

= 3.4.1 =
Security and review fixes: the admin preview no longer uses a frame, request handlers check nonces and permissions directly. Nothing changes on your pages.

= 3.4.0 =
English source texts with a bundled Polish translation. Polish sites look exactly as before, nothing changes on your pages without your decision.

= 3.3.0 =
Safer updates (checksum), automatic domain registration, bot protection for the sign-up form, a connection test and Site Health checks, cache plugin support, a class finder and optional analytics events. Nothing changes on your pages without your decision.

= 3.2.0 =
Month view of the calendar, gallery, sponsors, page builder support and an English version. Nothing changes on your pages without your decision.

= 3.1.0 =
The "KlubOS in 10 minutes" wizard, new native modules (pricing, staff, results, calendar, sign-ups, Parent Zone) and local SEO. Pages with plugin 2.0 stay in frame mode, nothing changes without your decision.

= 3.0.0 =
News and the class schedule as fast native modules, a new panel in the KlubOS menu and own updates. Pages with plugin 2.0 stay in frame mode, nothing changes without your decision.
