# ReferAll - Referral Tracking & Visibility for Elementor
**Version 1.1.0** | **Requires: WP 6.0+, PHP 7.4+**

ReferAll is a WordPress plugin that allows you to manage referral associates, track their visits, and dynamically change your website content (via Elementor or Shortcodes) based on which associate referred the visitor.

## ✨ Features

- **Associate Management**: Create and manage "Associates" as a Custom Post Type.
- **Dynamic Content**: Use tags like `%ref_name%` and `%ref_id%` in Elementor or shortcodes.
- **Elementor Visibility**: Completely hide or show any Elementor element based on the presence of a referral cookie.
- **Cache-Safe**: Automatically bypasses Elementor's internal element cache for dynamic elements.
- **Unique Statistics**: Tracks visits per associate, ensuring only 1 count per 30 days per unique visitor.
- **Contact Form 7 Integration**: Automatically detect the referral ID in form submissions.

## 🛠️ Usage

### 1. Creating Associates
Go to **ReferAll > Add New Associate**.
- **Title**: The legal or display name of the associate.
- **Slug**: This will be the referral code (e.g., `coca-cola`).
- **Meta Fields**: Add contact name, email, phone, and a logo.

### 2. Referral Links
Share links to your site with the `ref` parameter:
`https://your-site.com/?ref=associate-slug`

### 3. Elementor Integration

#### Widgets
We provide three custom widgets in the "ReferAll" category:
- **ReferAll Logo**: Displays the current associate's logo.
- **ReferAll Title**: A heading widget supporting `%ref_name%` and `%ref_id%` tags.
- **ReferAll Text**: A text editor widget supporting `%ref_name%` and `%ref_id%` tags.

#### Visibility Controls (Advanced Tab)
For **any** Elementor element (Container, Section, Widget):
1. Go to the **Advanced** tab.
2. Open the **ReferAll Visibility** section.
3. Choose a mode:
   - **Show Only If Referral Cookie Exists**: Use this for personalized "Welcome [Name]" sections.
   - **Hide If Referral Cookie Exists**: Use this for generic lead-capture forms or intro sections.

### 4. Shortcodes
Use these anywhere in WordPress (Shortcode widget, Gutenberg, etc.):
- `[referall_name]`: Outputs the current associate name.
- `[referall_id]`: Outputs the current associate slug.
- `[referall_status]`: (Admin Only) Displays a debug box with cookie and tracking information.

### 5. Tag Replacement
In ReferAll widgets, you can use these placeholders:
- `%ref_name%` -> Replaced with Associate Title.
- `%ref_id%` -> Replaced with Associate Slug.

## 📝 Contact Form 7 Integration

ReferAll provides two ways to work with Contact Form 7:

### 1. Identify Referrals in Emails
To see which associate referred a lead, you can use the custom `[referall_id]` mail tag:
1. In your CF7 Form template, add `[referall_id]` (it will be rendered as a hidden field).
2. In your CF7 **Mail** tab, add `Referral ID: [referall_id]` to the Message Body.
   - **Output Format**: This tag will output as `Associate Name (associate-slug)`.

### 2. Automatic Associate Notifications (Cc)
You can automatically send form submissions to the active associate:
1. **Enable the Feature**: On the Associate's edit page, ensure an **Email** is set and check the box **"Enable CF7 Email Notifications"**.
2. **How it works**: When a visitor with an active referral cookie submits *any* form on your site, the plugin detects the associate and adds their email to the `Cc` header of the notification email automatically.
3. **Requirement**: This feature requires the Contact Form 7 plugin to be active. If CF7 is not installed, the setting will not appear.

## 🔍 Debugging
If visibility isn't working as expected:
1. Log in as Admin.
2. Add the `[referall_status]` shortcode to your page.
3. It will show if the cookie is set, the ID found, and any environment issues (like cookie path/domain).

---

## 🔒 Security Notes
- Content from the Title/Text widgets is automatically escaped for XSS protection (**Late Escaping**).
- Referral IDs are validated against the database before being set as cookies.
- Statistics are protected against duplicate spamming via cookie-based uniqueness.
- Admin actions are secured with nonces and permission checks.

---

## 📜 Changelog

### 1.1.0
- **CF7 Integration**: Added automatic CC notifications for associates on form submissions.
- **Security Hardening**: Implemented "Late Escaping" and hardened nonces/permissions for repository compliance.
- **UI Previews**: Added Associate logo previews in the meta box and "All Associates" list table.
- **Improved i18n**: Full translation support across all components.

### 1.0.0
- Initial release.