🎁 Mavera WooCommerce Donation Plugin

The most comprehensive donation management plugin for WooCommerce
Transform your WooCommerce store into a powerful donation platform

Features • Installation • Shortcodes • Elementor • Use Cases • Changelog

---

📖 Overview

Mavera WooCommerce Donation Plugin is a full-featured donation management solution built specifically for nonprofits, charities, foundations, and religious organizations. It seamlessly integrates with WooCommerce to provide donation name fields, open pricing (name your price), goal tracking, custom form fields, popup donation forms, and much more.

Why This Plugin?

Challenge	Solution
🎯 Donors want to dedicate donations	✅ "In whose name?" fields with per-item support
💰 Fixed prices limit flexibility	✅ Open Pricing lets donors choose their amount
📊 Campaign progress is invisible	✅ Visual Goal Tracker with animated progress bar
🌍 Global Audience	✅ Multi-Currency support with Geo-IP detection
🛡️ Fraud & Security	✅ Backend price validation & Security audits
📦 Stock Management	✅ Auto-close campaigns when stock/goal is reached
📝 Complex donor requirements	✅ Custom Checkboxes & Selectboxes per product
🚀 Low conversion rates	✅ Fixed Bottom Bar & Popup forms for instant donations
🔌 Integration headaches	✅ WooCommerce native, REST API, Elementor ready
📚 Learning curve	✅ Built-in documentation & CSS Tricks tabs

---

✨ Features

🏷️ Donation Name Fields

Allow donors to specify whose name the donation is made on behalf of.

• Dynamic fields - One name field per quantity (2 items = 2 name fields)
• "Copy to All" button - Quickly fill all fields with the first name
• Required field validation - Ensure names are provided before checkout
• Edit in cart/checkout - Modify names at any stage
• Order display - Names shown in admin, emails, and customer account

💵 Open Pricing (Name Your Price)

Let donors choose their own donation amount.

• Min/Max limits - Set boundaries for donation amounts
• Default amount - Pre-fill a suggested donation
• +/- buttons - Easy increment/decrement controls
• Hide Min/Max info - Clean UI option
• Currency integration - Automatic WooCommerce currency support

📈 Goal Tracker

Visualize campaign progress with beautiful progress bars.

• Per-product goals - Set unique targets for each campaign
• Real-time tracking - Auto-updates when orders complete
• Animated progress bar - Shimmer effect & gradient styling
• Manual override - Admin can edit/reset collected amounts
• Shortcode support - Display anywhere on your site

☑️ Custom Fields (Checkboxes & Selectboxes)

Add unlimited custom form fields to any donation product.

Checkbox Fields:

• Unlimited checkboxes per product
• Title, description, and tooltip support
• Optional "required" validation
• Green styling in order details

Selectbox Fields:

• Single-select (dropdown) or multi-select
• Comma-separated options
• Checkbox list UI for multi-select
• Blue styling in order details

🎯 Fixed Bottom Bar (Quick Donation Bar)

A sticky donation bar that follows users as they scroll.

• Always visible - Drives impulse donations
• Mobile optimized - Thumb-zone friendly positioning
• Product filtering - Show only specific campaigns
• Customizable - Colors, text, and excluded pages
• Smart spacing - Auto-adjusts page content

🪟 Popup Donation Forms

Modern popup forms for quick donations without page navigation.

• URL triggers - Open popup via #dnf-popup-{id} links
• Shortcode triggers - Place popup buttons anywhere
• Elementor widget - Full styling control
• "Go to Cart" or "Checkout" - Flexible post-add actions
• Hide WooCommerce notices - Clean popup experience
• Required field validation - Checkbox/Selectbox validation with red asterisk indicators

🌍 Multi-Currency Support (NEW in v2.6.0)

Reach global donors with native currency support.

• TRY, USD, EUR, GBP - Supports all major currencies
• Automatic Exchange Rates - TCMB API integration for daily updates
• Geo-IP Detection - Automatically switch currency based on donor's country
• [dnf_currency_switcher] - Customizable switcher widget for your site
• Gateway Restrictions - Show specific payment methods for specific currencies

🛡️ Security & Stock Management (NEW in v2.8.0)

Professional campaign management with automated controls.

• Stock-Based Closing - Auto-disable "Donate" button when stock/goal is hit
• Custom Closing Messages - Professional messages instead of "Out of Stock"
• Backend Validation - Server-side Min/Max checks for Open Pricing
• Security Audited - Memory leak protection and stable DOM management

📚 Documentation & CSS Tricks (NEW in v2.5.0)

Built-in help guides for developers and beginners alike.

• Shortcode Tab - Parameters, defaults, and interactive examples
• CSS Tricks Tab - 13+ categories of ready-to-use CSS snippets
• Selector Badges - Easy identification of CSS selectors for styling
• Turkish language - Full local support for Turkish organizations

📝 Product Notes

Let donors add personal messages to their donations.

• Per-product enable/disable
• Custom title & placeholder
• Quantity multiplier - Multiple note fields per item
• Yellow styling in order details

🎁 Gift Aid (UK)

HMRC-compliant Gift Aid declaration for UK donors.

• Legal text included
• WooCommerce Blocks support
• Order details integration

🔗 Reference Code Tracking

Track donation sources with URL parameters.

• Capture ?ref=XXX from URLs
• Store in order meta
• REST API accessible

📋 Settings Copy/Paste

Quickly duplicate donation settings between products.

• One-click copy - Copy all settings from a product
• Instant paste - Apply to any other product
• Includes everything - Checkboxes, selectboxes, notes, etc.

---

🛠️ Installation

Requirements

• WordPress 5.0 or higher
• WooCommerce 5.0 or higher (tested up to 8.0+)
• PHP 7.4 or higher

Installation Steps

1. Download the plugin ZIP file
2. Navigate to WordPress Admin → Plugins → Add New → Upload Plugin
3. Upload the ZIP file and click "Install Now"
4. Activate the plugin
5. Configure donation settings on any WooCommerce product

Manual Installation

# Clone or download to your plugins directory
cd /wp-content/plugins/
git clone https://github.com/Oguzhan-Ozpinar/mavera-wc-donation.git

# Or extract ZIP
unzip mavera-wc-donation.zip

---

📝 Shortcodes

Donation Card

Display a beautiful donation card anywhere on your site.

[dnf_donation_card id="123"]

All Parameters

Parameter	Default	Description
id	required	WooCommerce Product ID
main_color	-	Hex color code for buttons (e.g., #e74c3c)
show_goal	true	Show/hide goal progress bar
show_price	true	Show/hide product price
show_description	true	Show/hide short description
show_category	true	Show/hide category label
show_info_button	true	Show/hide "More Info" button
button_text	Bağış Yap	Main button text
button_action	popup	popup or direct (product page)

Examples

[dnf_donation_card id="123" main_color="#e74c3c" button_text="Donate Now"]

[dnf_donation_card id="123" show_goal="false" show_description="false"]

[dnf_donation_card id="123" button_action="direct" button_text="View Details"]

---

Donation Slider (Carousel)

Display multiple donation cards in a swipeable slider.

[dnf_donation_slider category_id="15"]

All Parameters

Parameter	Default	Description
source	category	category or custom
category_id	-	Category ID (if source=category)
product_ids	-	Comma-separated IDs (if source=custom)
limit	8	Maximum products to display
columns	3	Desktop columns (auto 1 on mobile)
autoplay	0	Autoplay interval in ms (0=off)
loop	true	Enable infinite loop
main_color	-	Accent color for arrows/dots

Examples

[dnf_donation_slider category_id="25" columns="3" autoplay="3000"]

[dnf_donation_slider source="custom" product_ids="101,102,105" main_color="#27ae60"]

---

Goal Progress Shortcodes

[dnf_goal_progress id="123"]  // Displays progress bar
[dnf_goal_total id="123"]     // Displays total collected
[dnf_goal_remaining id="123"] // Displays remaining amount

---

Popup Shortcodes

[dnf_popup_trigger id="123"]  // Renders hidden popup HTML
[dnf_popup_button id="123" text="Donate Now"]  // Styled popup button

URL Trigger: Add #dnf-popup-123 to any link to open that product's popup.

---

🎨 Elementor Widgets

The plugin includes four powerful Elementor widgets:

1. Donation Card Widget (Bağış Kartı)

Drag-and-drop donation cards with full styling control.

• Product selector dropdown
• Color customization
• Toggle visibility of goal, price, description
• Button text and action settings

2. Donation Slider Widget (Bağış Kartları Slider)

Carousel of donation cards with Swiper integration.

• Category or custom product selection
• Autoplay and loop settings
• Responsive column controls

3. Popup Button Widget (Bağış Popup Butonu)

Stylized popup trigger button with icon support.

• Product dropdown selector
• FontAwesome icon picker
• Full typography and color controls
• Padding, border-radius, hover effects

4. Goal Progress Widget (Bağış Hedefi İlerlemesi)

Visual progress bar for donation goals.

• Default, minimal, detailed, or radial display styles
• Animated progress bar
• Customizable colors and dimensions

---

💼 Use Cases

🕌 Qurbani/Sacrifice Donations

• Open Pricing: Select share amount
• Donation Names: Whose name for each sacrifice
• Selectbox: Animal type (Cow, Sheep)
• Checkbox: "Distribute to those in need"
• Goal Tracker: Campaign progress

🌙 Zakat & Fitr

• Open Pricing: Enter exact Zakat amount
• Product Notes: Special instructions
• Checkbox: "Keep my donation anonymous"

📚 Education Scholarships

• Donation Names: Scholar or donor name
• Selectbox: Education level
• Goal Tracker: Fund target progress
• Notes: Personal messages

🏥 Medical Aid Campaigns

• Selectbox: Aid type (Medicine, Surgery, Treatment)
• Multi-select: Target regions
• Goal Tracker: Campaign visualization

🍞 Food Package Programs

• Quantity: Number of packages
• Donation Names: Name per package
• Selectbox: Distribution region
• Goal: Package target

---

🔧 Technical Details

File Structure

mavera-woocommerce-donation/
├── mavera-woocommerce-donation.php   # Main plugin file
├── README.md
├── MARKETING-DOCUMENTATION.txt
├── admin/
│   ├── settings.php                  # Global settings (6 tabs)
│   ├── class-product-metabox.php     # Product metabox
│   └── class-order-metabox.php       # Order metabox
├── includes/
│   ├── class-cart-handler.php        # Cart functionality
│   ├── class-order-handler.php       # Order processing
│   ├── class-open-pricing.php        # Name your price
│   ├── class-goal-tracker.php        # Goal tracking
│   ├── class-shortcode.php           # Donation card shortcode
│   ├── class-shortcode-slider.php    # Slider shortcode
│   ├── class-fixed-bar.php           # Fixed bottom bar
│   ├── class-blocks-integration.php  # WC Blocks support
│   ├── class-string-replacement.php  # Terminology customization
│   ├── class-elementor-widget.php    # Elementor integration
│   ├── class-elementor-donation-widget.php
│   ├── class-elementor-goal-widget.php
│   ├── class-elementor-popup-button-widget.php
│   └── class-elementor-donation-slider.php
└── assets/
    ├── css/
    │   ├── frontend.css
    │   ├── widget.css
    │   ├── slider.css
    │   ├── fixed-bar.css
    │   └── swiper-bundle.min.css
    └── js/
        ├── frontend.js
        ├── cart.js
        ├── widget.js
        ├── slider.js
        ├── fixed-bar.js
        ├── blocks-cart.js
        └── swiper-bundle.min.js

Database

• Uses WordPress post meta (no custom tables)
• Clean uninstall support
• Order meta for donation data

Performance

• Conditional script loading
• Minified CSS/JS assets
• Optimized database queries
• Elementor widget caching

Security

• Nonce verification on all forms
• Input sanitization
• XSS protection
• CSRF protection

Compatibility

• ✅ WooCommerce HPOS (High-Performance Order Storage)
• ✅ WooCommerce Blocks (Cart & Checkout)
• ✅ WooCommerce REST API
• ✅ Elementor & Elementor Pro
• ✅ Block-based themes (Twenty Twenty-Five, etc.)
• ✅ Classic themes
• ✅ Mobile responsive
• ✅ Dark mode support

---

🎨 Design & UX

Design Language

• Modern, minimal aesthetic
• Soft border-radius throughout
• Gradient backgrounds
• Smooth transition animations

Color Palette

Purpose	Color	Hex
Primary	Blue	#3498db
Success	Green	#27ae60
Warning	Yellow	#ffc107
Info	Light Blue	#2196f3

Responsive Design

• 📱 Mobile-first approach
• 📊 Tablet optimized
• 🖥️ Desktop enhanced
• 👆 Touch-friendly controls

---

📊 Competitive Advantages

Feature	Mavera	WC Name Your Price	WC Donations	GiveWP
Open Pricing	✅	✅	❌	✅
Donation Names	✅	❌	❌	❌
Goal Tracking	✅	❌	❌	✅
Custom Fields	✅	❌	❌	⚠️
Fixed Bar	✅	❌	❌	❌
Popup Forms	✅	❌	❌	⚠️
Elementor Widgets	✅	❌	❌	❌
Built-in Docs	✅	❌	❌	❌
WooCommerce Native	✅	✅	✅	❌
HPOS Compatible	✅	⚠️	❌	❌
Gift Aid (UK)	✅	❌	❌	✅

---

📋 Changelog

v2.8.5 (Latest)

• 🔧 JS Blocks Fix 2: Enhanced the MutationObserver to do robust, case-insensitive regex replacements for "Place Order" and "Proceed to Checkout" when standard React filters fail to mount in time. Removed wp-hooks dependency for better compatibility.

v2.8.4

• 🎨 UI/UX Refinement: Added section dividers to the Terminology list in the admin panel to improve readability and separate English and Turkish translations.

v2.8.3

• 🔧 JS Blocks Fix: Resolved translation issues on React-based cart and checkout pages using registerCheckoutFilters API and MutationObserver for complete JS-based dynamic terminology replacement.

v2.8.2

• 🆕 Enhanced Terminology: Added support for Cart Totals, Proceed to Checkout, Place Order, etc.
• 🌍 Internationalization: Full translation support for both English and Turkish originals.
• 🔗 Blocks Compatibility: Translation support for woo-gutenberg-products-block.

v2.8.0 - v2.8.1

• 🆕 Stock-Based Closing: Auto-disable donations when WooCommerce stock reaches zero.
• 🆕 Custom Closing Messages: Define global or per-product "Donation Closed" messages.
• 🔧 WP 6.7+ Fix: Resolved translation loading warnings (_load_textdomain_just_in_time).

v2.7.0

• 🛡️ Security Audit: Backend Min/Max validation for Open Pricing (prevents console hacks).
• 🔧 Memory Leak Fixes: Optimized JS event listeners and DOM cloning.
• 🌍 GeoIP Fix: Prevented infinite reload loops in restricted cookie environments (Safari/Brave).

v2.6.0

• 🆕 Multi-Currency: TRY, USD, EUR, GBP support with TCMB API exchange rates.
• 🆕 Geo-IP Detection: Automatic currency selection based on visitor location.
• 🆕 [dnf_currency_switcher]: New shortcode and widget for currency switching.
• 🆕 Gateway Restriction: Filter payment methods based on selected currency.

v2.5.0

• 🆕 CSS Tricks tab in settings with 13 categories of styling snippets.
• 🎨 UI Refinement: Cleaner inputs, optimized spacing, and better mobile UX.

v2.4.0

• 🆕 Name Fields Multiplier: Set a multiplier (e.g., 7 shares) for names per quantity.
• 📝 Readme.txt: Standardized documentation for WordPress.org.

v2.3.0

• 🆕 Popup required field validation for checkboxes/selectboxes
• 🆕 Red asterisk (*) indicator for required fields
• 🆕 Customizable popup texts (title, subtitle, buttons)
• 🆕 {product} variable for dynamic popup titles
• 🔧 Fixed checkbox/selectbox validation in popup

v2.2.6

• 🔧 Goal Progress Widget bar display fix (gray bar issue)
• 🔧 CSS loading fix for Elementor widget
• 🔧 Radial progress animation smoothing
• 🎨 Gradient effect for progress bar
• 🎨 Percentage color matches bar color

v2.2.5

• 🆕 Goal Progress Widget (Elementor & Shortcode)
• 🆕 Bar and Radial display styles
• 🆕 Animated progress bar and percentage

v2.2.4

• 🆕 Donation Terminology feature (Order → Donation, Cart → Donation Cart)
• 🆕 40+ default term mappings (TR + EN)
• 🆕 Accordion-style term customization UI
• 📊 Settings page split into 5 tabs

v2.2.3

• 🆕 WooCommerce Blocks (React cart) full support
• 🆕 Maximum donation quantity limiter
• 🔧 "Edit" button persistence in WC Blocks

v2.2.2

• 🔧 Fixed price display in popup for non-open-pricing products
• 🔧 Fixed popup clone issue on second open
• 🎨 Elementor widget icon color fix

v2.2.1

• 🆕 Elementor "Donation Popup Button" widget
• 🆕 Product dropdown, FontAwesome icon picker
• 🆕 Full button styling controls

v2.2.0

• 🆕 Popup URL Trigger: #dnf-popup-{id} links
• 🆕 [dnf_popup_trigger] shortcode
• 🆕 [dnf_popup_button] shortcode

v2.1.x

• 🆕 Fixed Bottom Bar with full admin controls
• 🆕 Swiper integration for donation slider
• 🔧 Block theme compatibility (Twenty Twenty-Five)

v2.0.x

• 🆕 Donation Card Widget & Shortcode
• 🆕 Donation Slider Widget & Shortcode
• 🆕 Popup form system
• 🆕 Color customization (main_color)

v1.9.0

• 🆕 Reference code tracking (?ref=XXX)

v1.8.x

• 🆕 Settings Copy/Paste between products

v1.7.x

• 🆕 Order metabox for donation details
• 🆕 REST API donation_fields
• 🆕 WC Mobile App order notes

v1.6.x

• 🆕 Gift Aid support (UK)
• 🆕 WooCommerce Blocks support

v1.5.0

• 🆕 Add to Cart Popup system

v1.4.x

• 🆕 ERP/CRM Project Name field
• 🆕 Note field quantity multiplier

v1.3.x

• 🆕 Custom Checkbox & Selectbox fields
• 🆕 HPOS compatibility

v1.2.x

• 🆕 Product Notes feature

v1.1.x

• 🆕 Open Pricing (Name Your Price)
• 🆕 Goal Tracker with progress bar

v1.0.x

• 🎉 Initial release
• Donation Name Fields
• Cart/Checkout integration

---

🤝 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the GPL v2 or later - see the LICENSE file for details.

---

🏢 About Mavera

Mavera Dijital A.Ş. is a Turkish digital agency specializing in WordPress and WooCommerce solutions for nonprofits and e-commerce businesses.

• 🌐 Website: https://mavera.site
• 📧 Support: destek@mavera.site

---

⭐ Show Your Support

If this plugin helps your organization, please consider:

• ⭐ Starring this repository
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features
• 📢 Sharing with other nonprofits

---

Made with ❤️ for nonprofits and charities worldwide
Hayır kurumları ve vakıflar için sevgiyle geliştirildi