=== DonorCore - Donations for WooCommerce ===

Contributors: lalitpurohit, rupeshjorkar  
Tags: donations, woocommerce, fundraising, campaigns, charity  
Requires at least: 6.5  
Tested up to: 7.0  
Requires PHP: 7.4  
Requires Plugins: woocommerce  
Stable tag: 1.3.1  
License: GPLv2 or later  
License URI: https://www.gnu.org/licenses/gpl-2.0.html  

Professional donation management for WooCommerce with campaigns, donor analytics, automated emails, and PDF receipts.

== Description ==

DonorCore is a professional donation plugin that transforms WooCommerce into a powerful fundraising platform. It allows organizations to manage donation campaigns, track donors, analyze fundraising performance, and automatically generate email and PDF receipts — all from a modern React-based admin dashboard.

DonorCore is ideal for organizations, community groups, and fundraisers that want a reliable, scalable, and fully WooCommerce-native donation solution without depending on third-party fundraising platforms.

= Why DonorCore? =

Unlike generic donation plugins, DonorCore is built specifically for professional fundraising workflows:

• Uses WooCommerce’s secure and flexible checkout system  
• Modern React-powered admin dashboard (no legacy admin tables)  
• Dedicated donor analytics instead of simple order lists  
• Automatic email and PDF receipt generation  
• Deep styling control without writing custom code  
• Clean architecture following WordPress.org coding standards  

= Core Features =

**React Admin Dashboard**

* Real-time donation analytics  
* Interactive charts showing donation trends  
* Quick stats: total raised, donor count, active campaigns, monthly revenue  
* Top donors leaderboard  
* Clean Material-UI based interface  

**Campaign Management**

* Create unlimited donation campaigns  
* Set fundraising goals and track progress visually  
* Custom suggested donation amounts per campaign  
* Campaign end dates with automatic donation form locking  
* Live progress tracking  

**Donation Forms & Blocks**

* 2 Gutenberg Blocks:
  - **Donation Form Block** – fully customizable donation form  
  - **Progress Bar Block** – real-time campaign progress display  

* 2 Shortcodes:
  - `[donorcore_donation_form campaign_id="123"]`
  - `[donorcore_campaign_progress id="123"]`

* Live preview in block editor  
* Mobile-responsive layouts  
* Custom suggested donation amounts  

**Complete Styling Control**

* Central admin panel for all styling options  
* Button styling: colors, hover states, padding, border radius  
* Progress bar styling: colors, height, text, radius  
* Font family, size, and weight controls  
* Color pickers with alpha transparency  
* Live CSS generation from admin settings  

**Donor Management**

* Searchable donor database  
* Individual donor profiles including:
  - Lifetime donation total  
  - Total number of donations  
  - Contact details (email, phone)  
  - Full donation history  
  - Campaign-specific donations  

* Material-UI drawer interface for detailed views  

**Automated Email Receipts**

⚠️ SMTP configuration required for email functionality (install WP Mail SMTP plugin)

* Automatic email receipts on successful donations  
* Fully customizable HTML email templates  
* Dynamic placeholders available:
  - **Donor Info**: `{donor_name}`, `{donor_first_name}`, `{donor_last_name}`, `{donor_email}`, `{donor_address}`
  - **Donation Info**: `{amount}`, `{currency}`, `{date}`, `{order_id}`, `{receipt_number}`
  - **Campaign Info**: `{campaign}`, `{campaign_name}`
  - **Site Info**: `{site_name}`, `{site_url}`, `{site_logo}`, `{org_name}`, `{org_address}`
* HTML editor with syntax highlighting  
* Custom email subject lines  
* Background processing using Action Scheduler  

**PDF Receipt Generation**

* Automatic PDF receipt generation for every donation  
* Customizable HTML-based PDF templates  
* Same placeholder system as email templates  
* PDF receipts attached to donation emails  
* Download links available for donors  

**Advanced Settings Panel**

* General settings:
  - Minimum donation amount  
  - Default suggested amounts  
  - Data management tools  

* Email template settings:
  - Subject customization  
  - HTML editor  
  - Placeholder reference  

* PDF template settings:
  - Layout customization  
  - Template editor  

* Donation form styling:
  - Button colors, fonts, spacing  
  - Responsive design controls  

* Progress bar styling:
  - Fill and background colors  
  - Text colors for amounts and percentage  
  - Height, radius, and typography controls  

**Security Features**

* Fully WordPress.org compliant  
* Nonce validation on all REST API endpoints  
* Capability checks (`manage_options`)  
* Prepared database queries  
* Input sanitization and output escaping  
* GDPR-compatible using WordPress privacy tools  

**Performance Optimizations**

* Database indexing for faster queries  
* Query caching using transients (30 minutes)  
* Optimized React admin bundle  
* Lazy loading of admin components  
* Compatible with WooCommerce HPOS  

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/donorcore/`  
2. Activate the plugin through the ‘Plugins’ screen in WordPress  
3. Ensure WooCommerce is installed and activated  
4. Navigate to **DonorCore → Settings** to configure  

= Initial Setup =

1. Configure general settings (minimum donation, suggested amounts)  
2. Customize email and PDF receipt templates  
3. Style donation forms and progress bars  
4. Create your first campaign via **Campaigns → Add New**  
5. Add donation forms using blocks or shortcodes  

For detailed setup instructions, see: [Complete Documentation](https://github.com/lalitraj881/donorcore-docs/blob/main/DOCUMENTATION.md)

== Frequently Asked Questions ==

= Does this require WooCommerce Subscriptions? =

No. DonorCore works with standard WooCommerce and does not require WooCommerce Subscriptions.

= Can I customize the donation form appearance? =

Yes. You can customize buttons, fonts, colors, spacing, progress bars, and more from the Settings panel — no coding required.

= How do I add a donation form to my site? =

You can add donation forms using:
1. Gutenberg blocks  
2. Shortcodes  
3. Campaign progress shortcodes  

= Are PDF receipts generated automatically? =

Yes. PDF receipts are automatically generated and emailed when a donation payment is completed. 

Note: Email delivery requires SMTP configuration. Install and configure WP Mail SMTP plugin for reliable email delivery.

= Can I customize email and PDF templates? =

Absolutely. Both templates are editable using HTML and dynamic placeholders from the Settings panel.

= Is DonorCore GDPR compliant? =

Yes. DonorCore integrates with WordPress privacy tools for data export and erasure.

= Are donations subject to taxes? =

No. Donation products are automatically tax-exempt. DonorCore sets all donations as non-taxable to comply with donation tax regulations.

= Do donations require shipping? =

No. Donations are virtual products and never require shipping. If a customer has both regular products and donations in their cart, shipping fees apply only to physical products.

= Can I sell regular products and accept donations in the same cart? =

Yes. DonorCore handles mixed carts seamlessly:
- Regular products: Taxable and require shipping (as configured)
- Donations: Tax-exempt and no shipping needed
- Both can be purchased together in a single checkout

= What happens with offline donation payments (Cash, Bank Transfer)? =

Offline payment methods work differently from online payments:

**Online Payments (Stripe, PayPal, etc.):**
- Donation is tracked immediately after payment
- Order status: "Completed" automatically
- Receipt sent immediately

**Offline Payments (Cash on Delivery, Bank Transfer):**
- Order status: "Processing" (awaiting payment)
- Donation is NOT tracked until admin confirms payment
- Admin must manually mark order as "Completed" after receiving payment
- Receipt sent only after admin confirmation

This prevents donations from being counted before payment is actually received.

== Screenshots ==

1. React-based admin dashboard with real-time analytics and donation timeline  
2. Campaign management interface with goal tracking and progress  
3. Donor database with searchable profiles and lifetime value tracking  
4. Donor details drawer showing donation history and contact information
5. Donation form block in Gutenberg editor with live preview
6. PDF template editor with HTML syntax highlighting and placeholders
7. Email template editor with HTML syntax highlighting and placeholders 
8. Donation form styling panel with typography and color controls   
9. Progress bar styling customization settings
10. Campaigns post type with goal, dates, and Progress.
11. Campaign creation interface with title, goal amount, start date, end date, and suggested donation amounts configuration.
 
== Changelog ==

= 1.3.1 =
* Resolved progress bar font-family inheritance and styling in block editor preview.
* Enhanced Gutenberg block compatibility and CSS container scoping.
* Optimized admin script builds and bundle dependencies.
* General performance enhancements, code cleanup, and stability fixes.

= 1.1.3 =
* Initial release for WordPress.org repository.
* Campaign management with fundraising goal tracking and live progress display.
* Gutenberg blocks & shortcodes for donation forms and progress bars.
* Automated email and PDF receipt generation.
* Professional donor analytics and management dashboard.
* Comprehensive typography, color, and layout styling controls.
* Resolved campaign settings sidebar styling and horizontal layout in block editor.
* Cleaned up inline CSS font family escaping and added Google Fonts support.

== Upgrade Notice ==

= 1.3.1 =
Maintenance release with Gutenberg block editor progress bar styling fixes and performance updates.

= 1.1.3 =
Initial production release of DonorCore for WooCommerce.
