=== 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.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add a KindLumen donation button or embedded form to any WordPress page. Connect in one click. Payments and donor data stay securely in KindLumen.

== 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.

Connecting takes one click: press **Connect with KindLumen**, sign in, pick a form, and you're done — no IDs to copy, no code to paste.

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 =

* **One-click connect** — link your KindLumen account and choose a form without copying IDs.
* **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 the plugin through the **Plugins** screen.
3. Go to **Settings → KindLumen**.
4. Click **Connect with KindLumen**, sign in if prompted, and choose the form you want. (Prefer to do it by hand? Paste your form link, or type your organization slug and Form ID.)
5. Add the form to a page:
   * **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.

== 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, sign up at [kindlumen.com](https://www.kindlumen.com).

= 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. Pass attributes, for example `[kindlumen_button form_id="abc123"]` or `[kindlumen_form campaign_id="spring-2026" height="760"]`.

= 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.

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

Make sure your organization slug and Form ID are correct and the form is published in KindLumen. Logged-in administrators see a short setup message when configuration 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`.

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"]`

== 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.
* **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. 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 settings screen — connect with KindLumen in one click, then copy a shortcode.
2. A Donate button on a WordPress page, with the donation popup open.
3. A donation form embedded inline on a page.
4. Adding the KindLumen Donation Form block and choosing Button or Inline.

== Changelog ==

= 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.0.0 =
Initial release of KindLumen Donation Forms.
