=== KindLumen Donation Forms ===
Contributors: kindlumen
Tags: donations, donate, fundraising, nonprofit, charity
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept donations on WordPress in three guided steps: connect KindLumen, connect Stripe, add a Donate button. Payments go to your own Stripe account.

== Description ==

**KindLumen Donation Forms** puts your existing [KindLumen](https://www.kindlumen.com) donation form on any WordPress page or post — as a **Donate button** that opens the form in a popup, or as an **inline form** embedded right in the page. Add it with a shortcode or a block.

Setup is three guided steps, right on the plugin's screen:

1. **Connect with KindLumen** — sign in, or create a free account on the spot, and pick a form. Everything is filled in for you; no IDs to copy, no code to paste.
2. **Connect Stripe** — done inside KindLumen. WordPress shows you whether donations are open yet.
3. **Put a Donate button on your site** — one click creates a Donate page with the form on it. Or use the built-in embed builder: pick what to show (your form, another form, or a campaign) and how (popup button, form on the page, campaign card, full campaign page, or a link that opens the popup), then copy the shortcode.

This is a lightweight **embed plugin**. It does not process payments, store donor information, or handle Stripe inside WordPress. Your form is rendered from KindLumen in a secure iframe, and everything sensitive — card entry, payment processing, receipts, donor records — stays inside KindLumen, exactly as on your KindLumen-hosted page.

= Highlights =

* **Guided setup** — connect, Stripe, add to site: the settings screen walks you through it and shows what's done.
* **One-click connect** — link your KindLumen account (or create one) and choose a form without copying IDs.
* **Donate page in one click** — creates a draft page with the form already on it.
* **Campaigns** — show a campaign's goal, progress bar, and Donate button as a card, or embed the whole campaign page, with `[kindlumen_campaign]` or the block.
* **Embed builder** — choose what to show and how; copy a ready-made shortcode or link. No IDs to remember.
* **Donate links** — point any button, menu item, or image at `#kindlumen-donate` and it opens the donation popup.
* **Donate button** — `[kindlumen_button]` shows a button that opens the form in a polished popup.
* **Inline form** — `[kindlumen_form]` embeds the form directly in the page, with automatic height.
* **Gutenberg block** — add "KindLumen Donation Form" and switch between Button and Inline.
* **Customizable** — set the button label, color, size, and alignment; set inline height and theme; preselect an amount or monthly giving.
* **Fast & clean** — loads assets only on pages that use it, no layout shift, no jQuery, no heavy frameworks.
* **Attribution** — donations made through WordPress are labeled in KindLumen so you can see where gifts come from.

= What it does NOT do =

* It does **not** process payments in WordPress.
* It does **not** store donor names, emails, amounts, card data, or Stripe IDs in WordPress.
* It does **not** create donations, donors, campaigns, or reports in WordPress.
* It does **not** ask for Stripe keys, API tokens, or webhook secrets.

= Requirements =

A free [KindLumen](https://www.kindlumen.com) account with at least one published donation form. The plugin embeds that form — it doesn't replace it.

= How donations are handled =

When a visitor donates, the form is served by KindLumen and the payment is processed by KindLumen's payment provider (such as Stripe) on KindLumen's domain. WordPress only displays the embedded form. See the External services and Privacy sections below.

== Installation ==

1. Install the plugin from the WordPress plugin directory, or upload the `kindlumen-donation-forms` folder to `/wp-content/plugins/`.
2. Activate it. You land on **Settings → KindLumen**, which walks you through the rest.
3. Click **Connect with KindLumen**. Sign in — or create a free account — and choose the form you want. You're sent straight back with everything filled in. (Prefer to do it by hand? Paste your form link instead.)
4. Connect Stripe in KindLumen. The setup screen shows whether donations are open yet and where to go.
5. Click **Create a Donate page**, or add the form yourself:
   * **Donate button:** add `[kindlumen_button]` to any page or post.
   * **Inline form:** add `[kindlumen_form]`.
   * **Block:** add the **KindLumen Donation Form** block and choose Button or Inline.
   * **Menu:** Appearance → Menus → tick **Donate button** in the KindLumen box.

== Frequently Asked Questions ==

= Do I need a KindLumen account? =

Yes. This plugin embeds a form you create in KindLumen. If you don't have an account yet, click **Connect with KindLumen** on the setup screen — you can create a free account right there and you'll be brought straight back.

= What's the difference between the button and the inline form? =

`[kindlumen_button]` shows a Donate button; clicking it opens the donation form in a popup over your page. `[kindlumen_form]` places the form directly in the page content. Use the button on busy pages or in menus/hero sections; use the inline form on a dedicated "Donate" page.

= How do I connect without copying IDs? =

On **Settings → KindLumen**, click **Connect with KindLumen**. You'll sign in to KindLumen (if you aren't already), pick a form, and you'll be sent back to WordPress with everything filled in.

= Are payments processed in WordPress? =

No. Payments are processed entirely by KindLumen and its payment provider on KindLumen's domain. WordPress only displays the embedded form.

= Is any donor or payment data stored in WordPress? =

No. The plugin stores only your display settings (organization slug, form ID, button label, height, and similar). No donor, payment, or card data ever touches WordPress.

= Can I customize how it looks? =

Yes. The button's label, color, size, and alignment are configurable in settings or per shortcode. The inline form's height and theme are configurable too. The form's own colors, content, and suggested amounts are set in KindLumen and apply everywhere the form appears.

= Can I use it with the Classic Editor or a page builder? =

Yes. The shortcodes work in the Classic Editor, the block editor, and most page builders that render shortcodes.

= Can I show different forms on different pages? =

Yes. In **Settings → KindLumen**, step 3 has an embed builder: choose the form or campaign and how to show it, then copy the shortcode. Under the hood that's `[kindlumen_button form_id="abc123"]`, `[kindlumen_form form_id="abc123"]`, and so on. The block has the same dropdown.

= How do I show a campaign (goal and progress bar)? =

Publish the campaign in KindLumen, then in the embed builder choose the campaign and pick **Campaign card** (goal, progress bar, Donate button — good for a homepage or sidebar) or **Full campaign page** (story, goal, and form — good on its own page). The shortcodes are `[kindlumen_campaign id="spring-2026"]` and `[kindlumen_campaign id="spring-2026" display="page"]`. The card's Donate button opens the donation popup right on your page.

= I already have a button in my theme or page builder. Can it open the donation popup? =

Yes. Set the button's link to `#kindlumen-donate` (the embed builder gives you the exact link, e.g. `https://example.org/#kindlumen-donate`). Clicking it opens the popup for your connected form. To open a specific form or campaign, use `#kindlumen-donate:form:abc123` or `#kindlumen-donate:campaign:spring-2026`. Opening such an address directly (from an email, say) opens the popup as the page loads.

= How do I add a Donate button to my navigation menu? =

The easy way (classic menus):

1. Connect a default form in **Settings → KindLumen**.
2. Go to **Appearance → Menus**. In the **KindLumen donation** box on the left, tick **Donate button** and click **Add to Menu**.
3. Click **Save Menu**. Done — the menu item opens the donation popup and is styled as a button automatically.

If you don't see the KindLumen box, open **Screen Options** (top right) and enable it.

Block themes / manual: edit the **Navigation** block, select the link, and add `kindlumen-donate-trigger` under **Advanced → Additional CSS class(es)**. The same class works on any link or button.

Either way, the menu item is **automatically styled as a pill button** matching your button color — no extra CSS needed. Restyle it with your own CSS if you prefer.

= Donations say "open soon". Why? =

Stripe isn't verified in KindLumen yet. Open **Settings → KindLumen** — step 2 shows the current status and a button to connect Stripe. Once KindLumen reports it as verified, the form takes donations.

= The form doesn't appear. What should I check? =

Open **Settings → KindLumen**. Step 1 shows which organization and form the site is connected to (and warns if the form can't be found or is still a draft in KindLumen). Logged-in administrators see a short setup message in place of the form when the connection is missing; visitors simply see nothing.

== Shortcodes ==

**Donate button** — opens the form in a popup:

`[kindlumen_button]`

Attributes (all optional; fall back to your settings):

* `form_id` — the KindLumen form to open.
* `campaign_id` — open a campaign instead of a single form.
* `organization` — your organization slug.
* `label` — button text (e.g. "Donate", "Give now").
* `color` — button color as a hex value (e.g. `#5C60FF`).
* `size` — `small`, `medium`, or `large`.
* `align` — `left`, `center`, or `right`.
* `amount` — preselect a donation amount (in your currency's main unit).
* `frequency` — `one-time` or `monthly`.
* `source` — attribution label recorded on the donation.
* `class` — extra CSS class on the wrapper.
* `title` — accessible label for the popup.

**Inline form** — embeds the form in the page:

`[kindlumen_form]`

Attributes: `form_id`, `campaign_id`, `organization`, `height`, `min_height`, `theme` (`inherited`/`light`/`minimal`), `amount`, `frequency`, `source`, `class`, `title`.

**Campaign** — a campaign's card (default), full page, popup button, or form:

`[kindlumen_campaign id="spring-2026"]`

Attributes: `id` (the campaign), `display` (`card`, `page`, `button`, or `inline`), plus the button/inline attributes above.

**Donate link** — no shortcode needed: link anything to `#kindlumen-donate` (or `#kindlumen-donate:form:abc123` / `#kindlumen-donate:campaign:spring-2026`) and clicking it opens the donation popup.

Examples:

`[kindlumen_button label="Give now" color="#0a7f5b" size="large"]`
`[kindlumen_button form_id="abc123" amount="50" frequency="monthly"]`
`[kindlumen_form]`
`[kindlumen_form campaign_id="spring-2026" height="760"]`
`[kindlumen_campaign id="spring-2026"]`
`[kindlumen_campaign id="spring-2026" display="page"]`

== External services ==

This plugin relies on KindLumen to display and process your donation form.

**KindLumen** (https://www.kindlumen.com)

* **What it is:** Your KindLumen-hosted donation form is embedded in an iframe on your WordPress page (as a button popup or inline). All payment processing, donor records, and receipts happen inside KindLumen.
* **When data is sent:** A request is made to KindLumen each time a page containing the form is viewed (to load the form), when a visitor opens the popup, and when a visitor submits a donation. The one-click connect also sends you to KindLumen and back. Additionally, when an administrator opens **Settings → KindLumen** or the block editor, WordPress asks KindLumen for the connection status (`/api/wordpress/status`) so it can show which form is connected, whether donations are open, and the list of your live forms and campaigns to pick from; the answer is cached for about five minutes.
* **What is sent:** The form/organization identifiers you configure; a source label (default "WordPress"); and, only if you turn the matching options on, your site's public domain and the page address. The status check sends only the organization slug and form id (plus your site address in the request's user agent). When a visitor donates, the details they enter are sent directly to KindLumen — never to or through WordPress.
* **Terms & privacy:** https://www.kindlumen.com/terms and https://www.kindlumen.com/privacy

By default the form is loaded from `https://www.kindlumen.com`. You can point the plugin at a different KindLumen environment in **Settings → KindLumen → Advanced**.

== Privacy ==

This plugin does not collect, process, or store any personal data in WordPress.

The donation form is loaded from KindLumen inside an iframe. When a visitor interacts with the form, their information is handled by KindLumen and its payment provider under KindLumen's privacy policy — not by your WordPress site.

For attribution, the plugin can include the following non-personal information in the embedded form's URL: a source label you choose (e.g. "WordPress"); optionally your site's public domain (off by default); and optionally the address of the page showing the form (off by default). No visitor or donor data is added to these.

== Screenshots ==

1. The setup screen — connect KindLumen, connect Stripe, add a Donate button.
2. A Donate button on a WordPress page, with the donation popup open.
3. A donation form embedded inline on a page.
4. The KindLumen Donation Form block — pick what to show and how in its settings.
5. A campaign card (goal, progress bar, Donate) and a Donate button on a page.

== Changelog ==

= 1.1.0 =
* Guided setup: the settings screen is now three steps — connect KindLumen, connect Stripe, add a Donate button — and shows what's done.
* Create a free KindLumen account from the connect flow; you're brought straight back to pick a form.
* Stripe status from KindLumen shown in WordPress, with a link to connect it.
* "Create a Donate page" adds a draft page with the form already on it.
* Activating the plugin opens the setup screen; a reminder appears on the Dashboard and Plugins screens until you're connected.
* Campaigns: `[kindlumen_campaign]` shows a campaign card (goal, progress bar, Donate button) or the full campaign page; the card's Donate button opens the popup on your page.
* Embed builder on the setup screen: pick what to show (your form, another form, or a campaign) and how; copy the shortcode or link.
* Block: "What to show" dropdown of your live forms and campaigns, with card and full-page options for campaigns.
* Donate links: any link to `#kindlumen-donate` (optionally `:form:{id}` / `:campaign:{id}`) opens the donation popup.
* Fixed: the block ignored the connected form when its own fields were left blank.
* Organization slug / Form ID fields moved under Advanced (still filled in automatically).

= 1.0.0 =
* Initial release.
* One-click connect with KindLumen (pick a form, no copy-paste).
* `[kindlumen_button]` popup button and `[kindlumen_form]` inline embed.
* KindLumen Donation Form block with Button/Inline display.
* Customizable button label, color, size, and alignment; inline height, theme, and auto-resize.
* Loading state, no-JS fallback, and source attribution recorded on donations in KindLumen.

== Upgrade Notice ==

= 1.1.0 =
Guided three-step setup with Stripe status and one-click Donate page. Your existing connection and settings are kept.

= 1.0.0 =
Initial release of KindLumen Donation Forms.
