Fluent Forms Calculation Captcha

A WordPress plugin that adds calculation-based spam protection to Fluent Forms. This plugin provides simple math questions to prevent spam submissions without requiring external API keys.

Features

• No API Keys Required: Unlike other captcha solutions, this plugin doesn't require any external API keys
• Configurable Difficulty: Choose from Easy (1-9), Medium (10-99), or Hard (100-999) difficulty levels
• Works with Regular Forms: Full support for standard Fluent Forms
• Works with Conversational Forms: Full support for Fluent Forms conversational forms
• Auto-Load Support: Can be set as the default captcha in form settings
• Secure: Uses encrypted answers to prevent tampering

Requirements

• WordPress 5.0 or higher
• PHP 7.4 or higher
• Fluent Forms plugin (free version)

Installation

Standard Installation

1. Upload the plugin files to /wp-content/plugins/fluentform-calculation-captcha/
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to Fluent Forms > Settings > Security > Calculation Spam Protection
4. Enable the plugin and configure the difficulty level
5. Add the "Calculation Spam Protection" field to your forms

Development Setup

If you're developing or modifying the plugin, you'll need to build the assets:

1. Install Node.js dependencies:

   cd fluentform-calculation-captcha
   npm install

2. Build the assets:

   # Development build (with source maps)
   npm run dev
   
   # Production build (minified)
   npm run production
   
   # Watch mode (auto-rebuild on changes)
   npm run watch

3. Required dependencies:

   • Node.js v14 or higher
   • npm or yarn
   • Fluent Forms plugin installed (for accessing Vue components)

4. Build output: The build process compiles Vue components to:

   • assets/js/calculation-captcha-settings.js - Settings page component
   • assets/js/calculation-captcha-template.js - Form editor template
   • assets/js/integration-hooks.js - Integration hooks for Fluent Forms
   • assets/js/calculation-captcha-modal.js - Disabled modal component

Usage

Global Settings

1. Navigate to Fluent Forms > Settings > Calculation Spam Protection
2. Enable the plugin
3. Select your preferred difficulty level:
   • Easy: Simple addition/subtraction with numbers 1-9
   • Medium: Addition/subtraction with numbers 10-99 (recommended)
   • Hard: Addition/subtraction with numbers 100-999

Adding to Forms

1. Edit any Fluent Form
2. Drag the "Calculation Spam Protection" field from the form builder
3. The field will display a math question to users
4. Users must answer correctly to submit the form

Auto-Load Captcha

You can set Calculation Spam Protection as the default captcha for all forms:

1. Go to Fluent Forms > Settings > Form Settings
2. Enable "Auto Load Captcha"
3. Select "Calculation Spam Protection" as the captcha type

How It Works

• When a form is loaded, a random math question is generated (e.g., "15 + 23 = ?")
• The correct answer is encrypted and stored in a hidden field
• Users enter their answer in a text field
• On submission, the plugin validates the answer server-side
• If the answer is incorrect, the form submission is rejected

Security

• Answers are encrypted using WordPress salts and SHA-256 hashing
• Hex encoding is used to ensure compatibility with WordPress sanitization
• Validation occurs server-side to prevent client-side tampering

Integration Setup Guide

This plugin integrates with Fluent Forms using WordPress hooks and JavaScript events. No modifications to Fluent Forms core are required.

How Integration Works

The plugin uses a combination of PHP filters/actions and JavaScript hooks to integrate seamlessly:

PHP Hooks

1. Component Registration

   • fluentform/editor_components - Registers the field in the form builder
   • fluentform/render_item_calculation_spam_protection - Renders the field on the frontend
   • fluentform/disabled_components - Controls whether the field is disabled in the editor

2. Validation

   • fluentform/before_form_validation - Validates the calculation answer before form submission
   • fluentform/white_listed_fields - Whitelists the calculation fields to prevent sanitization issues

3. Global Settings

   • fluentform/global_settings_components - Adds the settings page to Fluent Forms
   • fluentform/get_global_settings_values - Provides settings values to Fluent Forms
   • fluentform/global_settings_store_result - Handles saving settings

4. Conversational Forms

   • fluentform/conversational_field_types - Registers the field type for conversational forms
   • fluentform/conversational_question - Generates questions for conversational forms

5. Auto-Load Captcha

   • fluentform/auto_load_captcha_list - Adds calculation captcha to auto-load options

JavaScript Hooks

The plugin registers several JavaScript hooks that Fluent Forms core checks:

1. window.fluentformAdditionalCaptchaTypes

   • Array of additional captcha types for FormEditor.vue
   • Example: ['calculation_spam_protection']

2. window.fluentformExtendCaptchaStatus

   • Function to extend captcha status in GlobalSettings.vue
   • Merges calculation captcha status with existing captcha statuses

3. window.fluentformAdditionalCaptchaOptions

   • Object providing captcha options for Layout.vue
   • Used to add radio buttons in form settings

4. window.fluentformCaptchaLabels

   • Object mapping captcha types to display labels
   • Example: { 'calculation_spam_protection': 'Calculation Spam Protection' }

5. window.fluentformItemDisabledComponents

   • Object mapping disabled component modals
   • Used by ItemDisabled.vue to show custom modals

6. window.fluentformExternalCaptchaFieldNames

   • Array of captcha field names that should be non-editable
   • Used by nameAttr.vue to disable field name editing

7. window.fluentformGlobalSettingsComponents

   • Object registering Vue components for global settings
   • Used by global_settings.js to dynamically load components

8. window.ffEditorTemplates

   • Object registering form editor templates
   • Used by NestedHandler.js to render field templates

File Structure

fluentform-calculation-captcha/
├── assets/js/                          # Built JavaScript files (generated)
│   ├── calculation-captcha-settings.js
│   ├── calculation-captcha-template.js
│   ├── integration-hooks.js
│   └── calculation-captcha-modal.js
├── includes/                            # PHP classes
│   ├── Bootstrap.php                   # Main plugin initialization
│   ├── Components/
│   │   └── CalculationSpamProtection.php  # Frontend renderer
│   ├── Modules/
│   │   └── CalculationSpamProtection.php  # Question generation & validation
│   └── Services/
│       ├── ValidationService.php       # Form validation
│       └── GlobalSettingsService.php   # Settings management
├── resources/assets/admin/              # Source Vue components
│   ├── components/
│   │   ├── modals/
│   │   │   ├── CalculationSpamProtectionModal.vue
│   │   │   └── register-modal.js
│   │   └── templates/
│   │       ├── calculationSpamProtection.vue
│   │       └── register-template.js
│   ├── settings/
│   │   ├── CalculationSpamProtection.vue
│   │   └── settings.js
│   └── integration-hooks.js            # JavaScript integration hooks
├── resources/img/                       # Images
│   └── calculation-captcha-placeholder.png
├── fluentform-calculation-captcha.php  # Main plugin file
├── webpack.mix.js                      # Build configuration
└── package.json                        # Node.js dependencies

Troubleshooting

Plugin Not Showing in Editor

1. Check if plugin is enabled:

   • Go to Fluent Forms > Settings > Security > Calculation Spam Protection
   • Ensure "Enabled" is turned on

2. Rebuild assets:

   npm run production

3. Clear browser cache:

   • Hard refresh the form editor page (Ctrl+Shift+R or Cmd+Shift+R)

4. Check browser console:

   • Look for JavaScript errors that might prevent registration

Settings Page Not Loading

1. Verify built files exist:

   • Check that assets/js/calculation-captcha-settings.js exists
   • If missing, run npm run production

2. Check script dependencies:

   • Ensure Fluent Forms admin scripts are loaded
   • The settings script depends on fluentform-admin-app

3. Check component registration:

   • Verify window.fluentformGlobalSettingsComponents is set
   • Check browser console for registration errors

Validation Not Working

1. Check field names:

   • Ensure fields are named ff-calculation-answer and ff-calculation-question
   • These are whitelisted and cannot be changed

2. Check form data:

   • Verify the fields are included in form submission
   • Check browser network tab for submitted data

3. Check validation hook:

   • Ensure fluentform/before_form_validation hook is firing
   • Check PHP error logs for validation errors

Conversational Forms Not Working

1. Verify conversational plugin:

   • Ensure Fluent Forms Conversational plugin is installed and active

2. Check field type registration:

   • Verify fluentform/conversational_field_types filter is working
   • Check that the field type is registered as FlowFormCalculationSpamProtectionType

3. Check question generation:

   • Ensure fluentform/conversational_question action is firing
   • Verify question data structure matches expected format

Development Notes

• The plugin uses Fluent Forms' Vue instance and components
• Vue components are compiled using Laravel Mix (webpack)
• The plugin follows Fluent Forms' hook-based architecture
• All integrations use WordPress filters/actions and JavaScript events
• No direct modifications to Fluent Forms core files are required

For detailed integration documentation, see INTEGRATION_GUIDE.md

Support

For issues, feature requests, or questions, please contact the plugin author or visit the Fluent Forms support forum.

Changelog

1.0.0

• Initial release
• Support for regular forms
• Support for conversational forms
• Configurable difficulty levels
• Auto-load captcha support

License

GPLv2 or later