The Visual Donation Form Builder is a drag-and-drop form builder that allows you to create custom donation forms for campaigns. This document provides technical details for developers, designers, and theme developers working with the visual form builder system.

---

Table of Contents

---

Hooks and Filters

The following PHP hooks and filters are available for extending and customizing the visual form builder:

Theme and Styling Filters

• charitable_visual_form_theme_classes – Filter the resolved visual form theme classes (density theme)
  • Parameters: $result (array), $visual_theme (string)
  • Returns: Array with density_theme key
• charitable_visual_form_theme_variables – Filter the theme variables map for visual forms
  • Parameters: $result (array), $density_theme (string)
  • Returns: Array with variables key containing CSS variable definitions
• charitable_visual_form_default_styles – Filter default styles for visual forms
  • Parameters: $defaults (array), $context (string)
  • Returns: Array of default style values
• charitable_visual_form_styles – Filter the complete styles array for a form
  • Parameters: $styles (array), $campaign_id (int), $form_data (array)
  • Returns: Modified styles array
• charitable_visual_form_field_styles – Filter styles for individual fields
  • Parameters: $field_styles (array), $field_id (string), $field_data (array), $campaign_id (int)
  • Returns: Modified field styles array
• charitable_visual_form_field_classes – Filter CSS classes applied to form fields
  • Parameters: $classes (array), $field_id (string), $field_data (array), $campaign_id (int)
  • Returns: Modified classes array
• charitable_visual_form_field_full_width – Determine if a field should be full width
  • Parameters: $is_full_width (bool), $field_id (string), $field_data (array), $campaign_id (int)
  • Returns: Boolean
• charitable_visual_form_enable_theme_inheritance – Enable/disable theme style inheritance
  • Parameters: None
  • Returns: Boolean (default: false)
• charitable_visual_form_detected_theme_styles – Filter detected theme styles
  • Parameters: $detected (array), $active_theme (string)
  • Returns: Modified detected styles array
• charitable_visual_form_theme_style_map – Map detected theme styles to form variables
  • Parameters: $mapped (array), $detected_styles (array), $theme_name (string)
  • Returns: Modified mapping array
• charitable_visual_form_theme_fallback – Provide fallback values for theme variables
  • Parameters: $fallback (mixed), $form_variable (string), $detected_value (mixed), $context (string)
  • Returns: Fallback value or null
• charitable_visual_form_enable_elementor_inheritance – Enable/disable Elementor style inheritance
  • Parameters: None
  • Returns: Boolean (default: true)
• charitable_visual_form_detected_elementor_styles – Filter detected Elementor styles
  • Parameters: $detected (array), $elementor_active (bool)
  • Returns: Modified detected styles array
• charitable_visual_form_elementor_style_map – Map Elementor styles to form variables
  • Parameters: $mapped (array), $detected_styles (array)
  • Returns: Modified mapping array

Multi-Step Form Filters

• charitable_multistep_animation_type – Filter the animation type for multi-step forms
  • Parameters: $animation_type (string), $campaign_id (int)
  • Returns: Animation type string
• charitable_multistep_prev_button_text – Filter the “Previous” button text
  • Parameters: $text (string), $campaign_id (int)
  • Returns: Button text string
• charitable_multistep_next_button_text – Filter the “Next” button text
  • Parameters: $text (string), $campaign_id (int)
  • Returns: Button text string
• charitable_multistep_show_step_number – Control whether step numbers are displayed
  • Parameters: $show (bool), $step_number (int), $campaign_id (int)
  • Returns: Boolean
• charitable_multistep_step_label – Filter step labels
  • Parameters: $label (string), $step_number (int), $campaign_id (int)
  • Returns: Step label string

Form and Field Actions

• charitable_donation_form_before_fields – Action fired before form fields are rendered
  • Parameters: $current_form (array)
• charitable_visual_form_before_payment_section – Action fired before payment section is rendered
  • Parameters: $current_form (array), $campaign_id (int), $visual_form_data (array), $section_index (int by reference)
• charitable_visual_form_file_uploaded – Action fired when a file is uploaded
  • Parameters: $attachment_id (int), $donation_id (int), $file_key (string)

Field-Specific Filters

• charitable_visual_form_address_country_default – Filter default country for address fields
  • Parameters: $default_country (string), $campaign_id (int), $field_data (array)
  • Returns: Country code string
• charitable_donation_form_gateway_fields – Filter gateway-specific fields
  • Parameters: $gateway_fields (array), $gateway (object)
  • Returns: Modified gateway fields array
• charitable_html_field_allowed_html – Filter allowed HTML tags for HTML fields
  • Parameters: $allowed_html (string|array), $field_data (array), $field_id (string)
  • Returns: ‘default’ or array of allowed HTML
• charitable_checkbox_field_use_fieldset – Determine if checkbox fields should use fieldset wrapper
  • Parameters: $use_fieldset (bool), $normalized_id (string), $render_data (array), $visual_field_data (array)
  • Returns: Boolean (default: false)
• charitable_visual_form_donate_label – Filter the donate button label
  • Parameters: $donate_label (string), $campaign_id (int), $visual_form_data (array)
  • Returns: Button label string

Form Builder Filters

• charitable_default_visual_form_template – Filter the default visual form template
  • Parameters: $default_template (array), $campaign_id (int), $form_type (string)
  • Returns: Template array
• charitable_form_builder_load_fields – Filter the list of field types to load
  • Parameters: $form_fields (array)
  • Returns: Modified field types array
• charitable_builder_form_buttons – Filter the form field buttons in the builder sidebar
  • Parameters: $fields (array)
  • Returns: Modified fields array
• charitable_builder_form_field_button_attributes – Filter attributes for form field buttons
  • Parameters: $attributes (array), $field (array), $form_data (array)
  • Returns: Modified attributes array
• charitable_visual_form_conditional_logic_enabled – Enable/disable conditional logic globally
  • Parameters: $enabled (bool), $field_data (array)
  • Returns: Boolean (default: true)
• charitable_visual_form_debug – Enable/disable debug mode for visual forms
  • Parameters: $enable_debug (bool)
  • Returns: Boolean

---

Field Categories and Settings

Fields in the visual form builder are organized into three categories: Required Fields, Form Fields (regular), and Pro Fields.

Common Field Settings

Most fields support the following common settings (note: not all fields have all of these settings):

• Label – The text label displayed to users on the donation form
• Placeholder – Placeholder text shown in empty input fields
• Required – Whether the field must be filled out before form submission
• Align – Field alignment (left, center, right) – not available on all fields
• CSS Class – Custom CSS classes for styling – not available on all fields

Required Fields

These fields are essential for donation forms and typically can only be added once per form.

Donor Name Fields

• Type: donor-name-fields
• Settings:
  • Layout (side-by-side or stacked)
  • Label
  • Align
  • CSS Class
• Field Limit: 1 per form
• Cannot be duplicated

Donor Email Field

• Type: donor-email-field
• Settings:
  • Label
  • Align
  • CSS Class
• Field Limit: 1 per form
• Cannot be duplicated

Address Fields

• Type: address-fields
• Settings:
  • Label
  • Align
  • CSS Class
• Field Limit: 1 per form
• Cannot be duplicated
• Note: Includes address, address line 2, city, state, postcode, and country fields

Privacy Policy

• Type: privacy-policy
• Settings:
  • Label
  • Align
  • CSS Class
• Field Limit: 1 per form
• Cannot be duplicated

Donation Amounts

• Type: suggested-donation-amounts
• Settings:
  • Label
  • Align
  • CSS Class
• Field Limit: 1 per form
• Cannot be duplicated
• Note: Displays suggested donation amounts from campaign settings

Payment Section

• Type: payment-section
• Settings:
  • Gateway Selection (multi-select checkboxes for available payment gateways)
  • Label
  • Align
  • CSS Class
• Field Limit: 1 per form
• Cannot be duplicated

Form Fields (Regular)

These are standard form fields available for building custom donation forms.

Single Text Field

• Type: single-text
• Settings:
  • Label
  • Placeholder
  • Required
  • Default Value
  • Align
  • CSS Class
  • Advanced Options

Dropdown Field

• Type: dropdown
• Settings:
  • Label
  • Placeholder
  • Required
  • Allow Multiple Selection (checkbox)
  • Options Management (add/edit/remove options with value and label pairs)
  • Default Option (radio selection)
  • Align
  • CSS Class
  • Advanced Options

Checkbox Field

• Type: checkbox-field
• Settings:
  • Label
  • Required
  • Checkbox Options Management (add/edit/remove checkboxes with value and label pairs)
  • Default Selections (checkboxes for pre-selected options)
  • Align
  • CSS Class
  • Advanced Options

Radio Field

• Type: radio-field
• Settings:
  • Label
  • Required
  • Radio Options Management (add/edit/remove radio buttons with value and label pairs)
  • Default Selection (radio selection)
  • Align
  • CSS Class
  • Advanced Options

Textarea Field

• Type: textarea-field
• Settings:
  • Label
  • Placeholder
  • Required
  • Rows (number of textarea rows)
  • Max Length (character limit)
  • Align
  • CSS Class
  • Advanced Options

Email Field

• Type: email-field
• Settings:
  • Label
  • Placeholder
  • Required
  • Align
  • CSS Class
  • Advanced Options

Phone Field

• Type: phone-field
• Settings:
  • Label
  • Placeholder
  • Required
  • Align
  • CSS Class
  • Advanced Options

Number Field

• Type: number-field
• Settings:
  • Label
  • Placeholder
  • Required
  • Min Value (optional)
  • Max Value (optional)
  • Step (increment/decrement value)
  • Align
  • CSS Class
  • Advanced Options

Date Field

• Type: date-field
• Settings:
  • Label
  • Placeholder
  • Required
  • Date Format
  • Min Date (optional)
  • Max Date (optional)
  • Align
  • CSS Class
  • Advanced Options

URL Field

• Type: url-field
• Settings:
  • Label
  • Placeholder
  • Required
  • Align
  • CSS Class
  • Advanced Options

File Field

• Type: file-field
• Settings:
  • Label
  • Required
  • Allowed File Types (multi-select)
  • Max File Size (MB)
  • Enable Image Cropping (for JPEG/PNG only)
  • Align
  • CSS Class
  • Advanced Options

Editor Field (WYSIWYG)

• Type: editor-field
• Settings:
  • Label
  • Required
  • Editor Content (rich text editor)
  • Align
  • CSS Class
  • Advanced Options

Headline Field

• Type: headline-field
• Settings:
  • Text Content
  • Heading Level (H1-H6)
  • Align
  • CSS Class
  • Note: Does not have Advanced Options

Divider Field

• Type: divider-field
• Settings:
  • Style (solid, dashed, dotted)
  • Width (percentage)
  • Align
  • CSS Class
  • Note: Does not have Advanced Options

Picture Field

• Type: picture-field
• Settings:
  • Image Selection
  • Alt Text
  • Link URL (optional)
  • Align
  • CSS Class
  • Advanced Options

HTML Field

• Type: html-field
• Settings:
  • HTML Content (code editor)
  • Align
  • CSS Class
  • Advanced Options

Shortcode Field

• Type: shortcode-field
• Settings:
  • Shortcode Content
  • Align
  • CSS Class
  • Note: Does not have Advanced Options

Hidden Field

• Type: hidden-field
• Settings:
  • Field Name
  • Default Value
  • Advanced Options
  • Note: Does not have Label, Placeholder, Required, Align, or CSS Class settings

Pro Fields

These fields are available in Charitable Pro and appear in the “Pro Fields” category.

Donor Comment Field

• Type: donor-comment-field
• Settings:
  • Label
  • Placeholder
  • Required
  • Rows (number of textarea rows)
  • Max Length (character limit)
  • Align
  • CSS Class
  • Advanced Options
• Note: Requires donor comments to be enabled in Charitable settings

Referral Code Field

• Type: referral-code-field
• Settings:
  • Label
  • Placeholder
  • Required
  • Align
  • CSS Class
  • Advanced Options
• Note: Requires donor referrals to be enabled in Charitable settings

---

Advanced Options

Advanced Options are available on most form fields (with some exceptions noted above). These options control how field data is handled and displayed in various contexts.

Show in Export

When enabled, this field’s data will be included in donation exports and reports. This is useful for fields that contain important donor information you want to track and analyze.

Technical Details: Field data is stored in donation meta and included when export functions query donation data. The field must have this option enabled for its data to appear in CSV exports and other reporting tools.

Show in Email

When enabled, an email tag is created for this field that can be used in email templates. The tag format is typically {field_field_id} or a custom tag based on the field name.

Technical Details: Email tags are registered with Charitable’s email system and can be used in donation receipt emails, admin notifications, and other email templates. The field value is automatically formatted and inserted when the email is sent.

Show in Meta

When enabled, this field’s data will be displayed in the admin donation details page under the donation meta section. This allows administrators to view custom field data when reviewing donations.

Technical Details: Field data is displayed in the donation meta box on the WordPress admin donation edit screen. This provides a convenient way to view all custom field data associated with a donation without needing to export or query the database.

Note: Some fields (like donor comment field and referral code field) have “Show in Meta” enabled by default and cannot be disabled, as this information is considered essential for donation records.

---

Conditional Logic

Conditional logic allows you to show or hide fields based on values in other fields. This creates dynamic, interactive forms that adapt based on user input.

How It Works

Conditional logic uses a rule-based system where you can:

1. Enable Conditional Logic – Toggle conditional logic on/off for any field
2. Set Action Type – Choose to “Show” or “Hide” the field when conditions are met
3. Create Rules – Define conditions based on other field values
4. Group Rules – Use AND/OR logic to create complex conditions

Rule Structure

• Field – Select which field to check
• Operator – Choose comparison operator (equals, not equals, contains, etc.)
• Value – Enter the value to compare against

Logic Groups

Rules can be grouped using:

• AND – All rules in a group must be true
• OR – Any rule in a group can be true (separate groups)

Technical Implementation

Conditional logic is evaluated on the frontend using JavaScript. Rules are stored in the field’s conditionals array and conditional_logic boolean flag. The system supports real-time evaluation as users interact with the form.

Filter: charitable_visual_form_conditional_logic_enabled – Can be used to disable conditional logic globally or for specific fields.

---

Multi-Step Forms

Multi-step forms allow you to break donation forms into multiple pages or steps, improving user experience for longer forms.

Form Types

• Single-Page Form – All fields on one page (default)
• Multi-Step Form – Fields divided across multiple steps/slides

Step Management

• Minimum Steps: 2 steps required for multi-step forms
• Maximum Steps: 4 steps allowed
• Step Labels: Each step can have a custom label
• Step Navigation: Previous/Next buttons with customizable text
• Progress Indicators: Visual progress indicators show form completion

Step Configuration

Steps (also called “slides”) are managed in the Form Options panel. You can:

• Add new steps
• Remove steps (minimum 2 required)
• Rename steps
• Reorder steps
• Assign fields to specific steps

Navigation

• Previous Button – Navigate to previous step (hidden on first step)
• Next Button – Navigate to next step (validates current step before proceeding)
• Submit Button – Only visible on final step
• Step Headers – Optional clickable step headers for navigation (can be disabled)

Validation

Each step is validated before allowing progression to the next step. Only fields that have been interacted with are validated, preventing premature validation errors.

Animation

Step transitions can be animated. The animation type can be filtered using charitable_multistep_animation_type.

Filters:

• charitable_multistep_prev_button_text – Customize “Previous” button text
• charitable_multistep_next_button_text – Customize “Next” button text
• charitable_multistep_show_step_number – Control step number display
• charitable_multistep_step_label – Customize step labels

---

Field Validation

Field validation ensures that users provide correct and complete information before form submission.

Validation Types

1. Required Field Validation – Ensures required fields are not empty
2. Format Validation – Validates field format (email, URL, number, etc.)
3. Range Validation – Validates min/max values for number and date fields
4. File Validation – Validates file type, size, and other upload constraints
5. Custom Validation – Field-specific validation rules

Validation Timing

• On Submit – Full form validation occurs when the submit button is clicked
• On Step Progression – Multi-step forms validate current step before allowing next step
• Real-Time – Some fields may validate as user types (browser-dependent)

Validation Actions

Each field type has a validate() method that is called via the charitable_form_process_validate_{field_type} action. Validation errors are displayed to users and prevent form submission until resolved.

Error Display

Validation errors are displayed:

• Below the field that failed validation
• In a summary at the top of the form (if multiple errors)
• With clear, user-friendly error messages

---

Frontend Rendering

The visual form builder uses a specialized rendering system that converts builder field data into functional HTML forms on the frontend.

Rendering Process

1. Form Data Retrieval – Form configuration is loaded from campaign post meta
2. Field Registration – Fields are registered with Charitable’s Donation Fields API
3. Template Rendering – Fields are rendered using theme-aware templates
4. Style Application – CSS classes and inline styles are applied based on form settings
5. JavaScript Initialization – Frontend JavaScript handles interactions and validation

Rendering Classes

Forms receive CSS classes based on:

• Form type (single-page or multi-step)
• Theme selection
• Density settings
• Custom CSS classes

Field Wrappers

Each field is wrapped in containers that provide:

• Consistent spacing and layout
• Alignment support
• Responsive behavior
• Theme integration

Multi-Step Rendering

Multi-step forms are rendered with:

• Step containers that show/hide based on current step
• Navigation controls
• Progress indicators
• Step-specific validation

---

Theme Integration

The visual form builder includes sophisticated theme integration that automatically adapts forms to match your active WordPress theme or page builder styles.

Theme Detection

The system automatically detects:

• Active WordPress theme
• Elementor page builder styles (if active)
• Theme color schemes and typography

Style Inheritance

Forms can inherit styles from:

• WordPress Themes – Automatically detects and applies theme colors, fonts, and spacing
• Elementor – Inherits Elementor global colors and typography settings
• Custom CSS Variables – Uses CSS custom properties for easy theming

CSS Variables

Forms use CSS custom properties (variables) for styling, allowing easy customization:

• --charitable-field-gap – Spacing between fields
• --charitable-input-padding-y – Vertical padding for inputs
• --charitable-input-padding-x – Horizontal padding for inputs
• --charitable-input-border-color – Input border color
• --charitable-input-border-radius – Input border radius
• --charitable-focus-ring-color – Focus ring color
• And more…

Theme Classes

Forms receive theme-specific CSS classes that allow theme developers to target forms with custom styles:

• Density classes (base, spaced)
• Theme-specific classes
• Form type classes (single, multistep)

For Theme Developers

To customize visual forms in your theme:

1. Use CSS Variables – Override CSS custom properties in your theme stylesheet
2. Target Theme Classes – Use the theme classes applied to forms for specific styling
3. Use Filters – Hook into theme detection filters to customize style inheritance
4. Custom CSS Classes – Add custom CSS classes to fields via the CSS Class setting

Filters for Theme Integration

• charitable_visual_form_theme_classes – Modify theme classes
• charitable_visual_form_theme_variables – Customize CSS variables
• charitable_visual_form_enable_theme_inheritance – Enable/disable theme inheritance
• charitable_visual_form_detected_theme_styles – Modify detected theme styles
• charitable_visual_form_theme_style_map – Customize style mapping
• charitable_visual_form_theme_fallback – Provide fallback values

For Designers

The visual form builder provides:

• Consistent Styling – Forms automatically match your site’s design
• Responsive Layout – Forms adapt to different screen sizes
• Accessibility – Forms follow accessibility best practices
• Customization Options – Easy-to-use settings for colors, spacing, and layout

Density Themes

Two density options are available:

• Base – Standard spacing (default)
• Spaced – Increased spacing for better readability

Density affects field gaps, input padding, and overall form spacing.

---

Field Duplication

Fields can be duplicated to quickly create similar fields with the same settings.

Duplication Process

1. Click the duplicate icon on any field
2. Choose duplication mode:
   • Copy Settings – Duplicates field with all settings (except conditional logic and advanced options)
   • Use Defaults – Creates new field with default settings but keeps original label (with “(Copy)” appended)

What Gets Duplicated

When copying settings:

• Field label (with “(Copy)” appended if not already present)
• Field type
• All field-specific settings (options, placeholders, etc.)
• Required status
• Alignment
• CSS classes
• Default values

What Does NOT Get Duplicated

• Conditional logic (always reset)
• Advanced options (always reset)
• Field ID (new unique ID assigned)

Field ID Management

Each duplicated field receives a new, unique field ID. The system uses transients to track the next available field ID and prevent conflicts.

---

Field Limits and Restrictions

Certain fields have restrictions on how many times they can be added to a form.

Fields with Limits

The following fields can only be added once per form:

• Donor Name Fields (max_allowed: 1)
• Donor Email Field (max_allowed: 1)
• Address Fields (max_allowed: 1)
• Privacy Policy (max_allowed: 1)
• Donation Amounts (max_allowed: 1)
• Payment Section (max_allowed: 1)

Fields That Cannot Be Duplicated

Some fields cannot be duplicated even if they don’t have a strict limit:

• All required fields listed above
• Payment Section

Multi-Step Form Limits

• Minimum Steps: 2 steps required for multi-step forms
• Maximum Steps: 4 steps allowed

Field Availability

Some fields require specific settings to be enabled:

• Donor Comment Field – Requires donor comments to be enabled in Charitable → Settings → Donors
• Referral Code Field – Requires donor referrals to be enabled in Charitable → Settings → Donors

These fields will be disabled in the builder if the required settings are not enabled, with a modal explaining how to enable them.

---

Admin Donation Entry Limitation

Important: When manually adding a donation in the WordPress admin (via Donations → Add New), the visual form builder’s custom fields are not supported or displayed.

Only donations submitted through the frontend visual form will capture and store custom field data. Admin-created donations will not have access to:

• Custom form fields added via the visual builder
• Field-specific validation
• Custom field data storage
• Advanced options settings

This limitation exists because the admin donation entry interface uses Charitable’s standard donation form, not the visual form builder system. Custom fields created in the visual builder are only processed and stored when donations are submitted through the frontend form.

---

Additional Resources

For more information about extending the visual form builder:

• Charitable Developer Documentation
• WordPress Hooks and Filters Documentation
• Charitable GitHub Repository

---

Document Version: 1.0 Last Updated: November 28, 2025