=== ForgePress Country Choice Rules for Gravity Forms ===
Contributors: forgepress
Tags: gravity forms, choices, country, geolocation, conditional logic
Requires at least: 5.8
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.3.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Country-based choice rules for Gravity Forms. Hide or replace field choices per country, with optional VPN/Proxy handling.


== Description ==

**ForgePress Country Choice Rules for Gravity Forms** lets you define rules that remove specific **choices** (radio, dropdown, checkbox options) for visitors from selected countries. This happens **server-side** (secure), and you can configure a **fallback choice** to auto-select when an option is removed.

### Highlights
- **Per-country choice blocking** for radio, dropdown, and checkbox fields
- **Multi-form / multi-field** rules (simple repeater UI)
- **Fallback choice** (optional) if a blocked option is removed
- **Server-side filtering** (not just CSS/JS hiding)
- **Optional VPN/Proxy handling**:  
  - *Do nothing*  
  - *Show warning* message  
  - *Force a default country* for rule evaluation  
  - *Block submission* with a custom message
- **Cloudflare aware** (`CF-IPCountry`) with 1h caching for IP lookups
- Lightweight and admin-friendly

> This plugin is **not** affiliated with or endorsed by Gravity Forms. It simply integrates with Gravity Forms via its standard hooks.

### How it works (in short)
1. You add rules: **Form ID + Field ID + Choice Text/Value + Countries** (+ optional fallback).
2. On render/validation, the plugin detects the visitor **country**.
3. If a rule matches, the corresponding **choice(s) are removed** and an optional **fallback** is selected.

---

## External Services & Data Flow (Guideline 6)

This plugin may use third-party services to determine the visitor’s country and (optionally) detect VPN/Proxy usage.

- **Cloudflare (if your site is on Cloudflare):**  
  We read the `CF-IPCountry` header provided by Cloudflare. No outbound request is made by this plugin.  
  Privacy: https://www.cloudflare.com/privacypolicy/

- **ipapi.co (free)** *(default geolocation when Cloudflare is not present)*:  
  The plugin requests `https://ipapi.co/{IP}/json/` to map visitor IP → country.  
  **Data sent:** visitor IP only.  
  **Retention:** result cached in WordPress for 1 hour.  
  Privacy: https://ipapi.co/privacy/

- **Optional VPN/Proxy checks (opt-in by the site admin):**
  - **ipregistry.co** (if an API key is configured):  
    **Data sent:** visitor IP to check proxy/VPN indicators.  
    Privacy: https://ipregistry.co/privacy
  - **ipapi.com PRO** (if an API key is configured):  
    **Data sent:** visitor IP with `security=1` to check VPN/Proxy/Tor.  
    Privacy: https://ipapi.com/privacy

No form entries or personal form fields are sent to these providers. Admins can **disable** optional VPN checks entirely.

**GDPR/Privacy:** Only an IP address may be sent to the selected provider(s) to derive country/VPN status. You should disclose this in your site privacy policy if enabled.

---

## Notes on Naming / Trademarks

This is an independent plugin **for** Gravity Forms and is not affiliated with or endorsed by Gravity Forms. The name and readme make this relationship clear.

---

## Features in Detail

- **Rule builder UI** under *Settings → ForgePress Country Choice Rules*  
  - Add multiple rows; each row targets a **Form ID + Field ID**, the **choice label/value**, and a list of **countries (ISO-2)**.  
  - Optionally set a **Fallback choice** to auto-select if the blocked option is removed.
- **Runtime enforcement**  
  - Choices are removed on `gform_pre_render` and validated on `gform_validation`.  
  - If a blocked value is posted manually, validation fails with a clear message.
- **VPN/Proxy handling**  
  - Admin can choose: *Do nothing*, *Show warning*, *Force country*, or *Block submission*.  
  - Works without an API key (heuristics). With a key (ipregistry/ipapi PRO), detection is more accurate.

---

## Installation

1. Install and activate **Gravity Forms** first.
2. Upload the plugin ZIP and activate **ForgePress Country Choice Rules for Gravity Forms**.
3. Go to **Settings → ForgePress Country Choice Rules** to add rules.
4. (Optional) Configure **VPN/Proxy handling** and provider API key(s).

---

## Frequently Asked Questions

**Does this work without JavaScript?**  
Yes. Filtering is server-side.

**What happens if the user is on a VPN?**  
By default, geolocation is based on the detected IP, which may reflect the VPN’s exit node. You can enable **VPN/Proxy handling**: show a warning, force a default country for rule evaluation, or block the submission. For higher accuracy, add an API key for *ipregistry* or *ipapi PRO*.

**How do I find Field IDs and Choice values?**  
In the Gravity Forms editor, each field shows an **ID**. Choices have **text** and **value**; match either (the plugin compares case-insensitively).

**Is this compatible with caching?**  
Yes. Country detection is per-request and cached (IP result for 1 hour). For full-page caching, ensure your CDN/proxy varies cache by country (or bypass cache on form pages) if you need per-country differences on the same URL.

**Is there a performance impact?**  
Minimal. A single fast IP lookup is cached; Cloudflare country header avoids lookups entirely.

---

## Screenshots

1. **Rules UI** – Add rules per form/field with countries and optional fallback  
2. **VPN/Proxy settings** – Choose action, set forced country, optional API and messages  
3. **Frontend** – Choices removed per country; fallback auto-selected (if configured)

---

## Changelog

### 1.3.0
- Initial public release under the new name/slug.
- Country-based choice filtering with fallback selection.
- Optional VPN/Proxy handling (warn/force/block).
- Cloudflare header + ipapi.co fallback with 1h caching.
- Admin UI for multi-form/multi-field rules.

---

## Upgrade Notice

### 1.3.0
Renamed to **ForgePress Country Choice Rules for Gravity Forms**. If you used a previous ForgePress build, your settings will migrate automatically.

