# Cloudflare Turnstile Field - User Guide

## Overview

Contact Forms by Cimatti now includes native support for Cloudflare Turnstile, a modern CAPTCHA alternative that provides bot protection without frustrating user experiences.

**Version Added:** 1.9.14

## How It Works

Unlike traditional CAPTCHA integrations that automatically appear on all forms, the Turnstile field uses a **field-based approach**:

- ✅ Appears as a draggable field in the form builder
- ✅ You control which forms use Turnstile
- ✅ You control where the Turnstile widget appears
- ✅ Existing forms remain unchanged

## Quick Start

### 1. Install Simple Cloudflare Turnstile (Required)

The Turnstile field requires the [Simple Cloudflare Turnstile](https://it.wordpress.org/plugins/simple-cloudflare-turnstile/) plugin to function:

1. Go to **Plugins → Add New**
2. Search for "Simple Cloudflare Turnstile"
3. Install and activate

### 2. Configure Your Cloudflare Keys

1. Get your keys from [Cloudflare Dashboard](https://dash.cloudflare.com/)
2. Go to **Settings → Cloudflare Turnstile**
3. Enter your **Site Key** and **Secret Key**
4. Save settings

### 3. Add Turnstile to Your Form

1. Go to **Forms → Edit Form**
2. Find **Turnstile** in the Fields sidebar
3. **Drag it** into your form (typically before the Submit button)
4. Save your form

That's it! The Turnstile widget will now appear when users view your form.

## Widget Appearance

The Turnstile widget appears as a checkbox-style verification:
- Shows Cloudflare branding
- Displays a green checkmark when completed
- Automatically resets after form submission
- Works in all modern browsers

## Configuration Options

The Turnstile field uses these default settings:

- **Theme:** Auto (matches user's browser preference)
- **Language:** Auto-detected from browser
- **Size:** Normal
- **Appearance:** Always visible

These settings work well for most use cases. Future versions may include customization options.

## Testing

For testing purposes, you can use Cloudflare's test keys:

- **Site Key:** `1x00000000000000000000AA`
- **Secret Key:** `1x0000000000000000000000000000000AA`

Test keys always show a success state, which is perfect for development and testing.

## Validation

The Turnstile field validates server-side, meaning:

- ✅ Users cannot bypass it by disabling JavaScript (validation happens on the server)
- ✅ Bot protection is maintained even with creative bypass attempts
- ✅ Integrates seamlessly with Contact Forms' existing validation system

## Privacy & Performance

Cloudflare Turnstile is designed with privacy in mind:

- No personal data collection
- No cookies required
- Minimal impact on page load time
- Compliant with privacy regulations (GDPR, etc.)

## Troubleshooting

### Widget doesn't appear

1. Check that Simple Cloudflare Turnstile plugin is installed and activated
2. Verify Cloudflare Turnstile keys are configured in Settings → Cloudflare Turnstile
3. Check that Turnstile field is added to the form
4. Clear browser cache
5. Check browser console for JavaScript errors

### "Plugin Required" or "Configuration Required" message

If you see "Plugin Required":
1. Install Simple Cloudflare Turnstile plugin from https://it.wordpress.org/plugins/simple-cloudflare-turnstile/
2. Activate the plugin
3. Refresh the form page

If you see "Configuration Required":
1. Go to Settings → Cloudflare Turnstile
2. Configure your Site Key and Secret Key
3. Refresh the form page

### Form submission fails

1. Check that Cloudflare Turnstile service is working (check Cloudflare status)
2. Verify your Secret Key is correct
3. Check that your domain is authorized in Cloudflare Dashboard
4. Look for validation errors in the form

## For Developers

### Architecture

The Turnstile field follows Contact Forms' standard architecture:

- **Element Class:** `AccuaForm_Element_Turnstile` (`/classes/Element/Turnstile.php`)
- **Validation Class:** `AccuaForm_Validation_Turnstile` (`/classes/Validation/Turnstile.php`)

### Customization Hooks

Future versions may include WordPress filters for customization. Current version focuses on working out-of-the-box with sensible defaults.

### API Integration

The validation class uses these methods (in order of preference):

1. `cfturnstile_check()` - From Simple Cloudflare Turnstile plugin
2. `wp_remote_post()` - Direct Cloudflare API call
3. `curl` - Fallback if wp_remote_post fails

This ensures maximum compatibility across different WordPress configurations.

## Support

For issues specific to:

- **Turnstile Field:** Contact [Cimatti](https://www.cimatti.it/en/wordpress-plugins/contact-forms/)
- **Cloudflare Turnstile Plugin:** Visit [WordPress Support](https://wordpress.org/support/plugin/simple-cloudflare-turnstile/)
- **Cloudflare Service:** Check [Cloudflare Documentation](https://developers.cloudflare.com/turnstile/)

## Changelog

### Version 1.9.14 (2025-01-24)

- Initial release of Turnstile field integration
- Field-based approach (drag-and-drop)
- Works standalone or with Simple Cloudflare Turnstile plugin
- Server-side validation with multiple fallbacks
- Auto-reset after AJAX submissions
- Backward compatible with existing forms