Integrate hCaptcha

Thanks to Arne Lap for this hCaptcha integration:

Step #1

Install and activate the hCaptcha plugin, create a free hCaptcha account and add your credentials in the hCaptcha plugin settings.

Step #2

Add the following code snippet to your website:

    // If a form is submitted without a hcaptcha validation, show the oops something went wrong error
    add_filter('hf_validate_form',    function( $error_code, $form, $data ) {
        $result = hcaptcha_verify_post();
        if ( null !== $result ) {
              $error_code = 'catcha_failed';
        }
        return $error_code;
    },10,3);
    
    // Execute the hcaptcha shortcode when a {{hcaptcha}} template tag is found in the fields code
    add_filter(
        'hf_template_tags',
        function( $tags ) {
            $tags['hcaptcha'] = do_shortcode( '[hcaptcha]' );
            return $tags;
        }
    );
    
    // Turn off the validation on how many fields are expected, as hcaptcha is adding some fields to the form
    add_filter( 'hf_validate_form_request_size', '__return_false');

    GitHub user despecial recommends this additional code snippet to filter out the hCaptcha fields from your form results:

    // Filter hcaptcha fields
    function ignored_hf_fields() {
    	return array(
    		'hcaptcha-widget-id',
    		'g-recaptcha-response',
    		'h-captcha-response',
    		'hcaptcha_nonce'
    	);
    }
    add_filter('hf_ignored_field_names','ignored_hf_fields');

    Step #3

    Add {{hcaptcha}} to your HTML-Forms fields where you want to show the captcha. ​​​​​

    Code Snippets

    Check out our collection of simple code snippets you can use to get the most out of HTML Forms on your WordPress websites.

    Add Class Attribute to Form Tag

    add_filter(
    	'hf_form_element_class_attr',
    	function( $class_attr ) {
    		return $class_attr . ' my-class';
    	}
    );

    Add Custom Attribute to Form Tag

    add_filter(
    	'hf_form_html',
    	function( $html ) {
    		$html = str_replace( '<form ', '<form ms-signup="true" ', $html );
    		return $html;
    	}
    );

    Add Custom Form Action

    use HTML_Forms\Actions\Action;
    use HTML_Forms\Form;
    use HTML_Forms\Submission;
    
    class MyCustomAction extends Action {
    
    	public $type  = 'pushbullet';
    	public $label = '';
    
    	public function __construct() {
    		$this->label = __( 'Send to Pushbullet', 'html-forms' );
    	}
    
    	/**
    	 * @return array
    	 */
    	private function get_default_settings() {
    		return array(
    			'url' => '',
    		);
    	}
    
    	/**
    	 * @param array $settings
    	 * @param string|int $index
    	 */
    	public function page_settings( $settings, $index ) {
    		$settings = array_merge( $this->get_default_settings(), $settings );
    		?>
    		<span class="hf-action-summary"><?php printf( 'Pushbullet' ); ?></span>
    		<input type="hidden" name="form[settings][actions][<?php echo $index; ?>][type]" value="<?php echo $this->type; ?>" />
    		<table class="form-table">
    			<tr>
    				<th><label><?php echo __( 'Pushbullet API URL', 'html-forms' ); ?> <span class="hf-required">*</span></label></th>
    				<td>
    					<input name="form[settings][actions][<?php echo $index; ?>][url]" value="<?php echo esc_attr( $settings['url'] ); ?>" type="text" class="regular-text" placeholder="http://...." required />
    				</td>
    			</tr>
    		</table>
    		<?php
    	}
    
    	/**
    	 * Processes this action
    	 *
    	 * @param array $settings
    	 * @param Submission $submission
    	 * @param Form $form
    	 */
    	public function process( array $settings, Submission $submission, Form $form ) {
    		// TODO: Send HTTP request to PushBullet API URL: $settings['url']
    	}
    }
    
    $my_custom_action = new MyCustomAction();
    $my_custom_action->hook();

    Add HTML to Form Dynamically

    add_filter(
    	'hf_form_markup',
    	function( $markup ) {
    		$markup .= '<input type="hidden" name="HIDDEN_FIELD" value="My value" />';
    		return $markup;
    	}
    );
    

    HTML forms will check the number of configured fields versus the number of submitted fields, and ignore the submission if it’s mismatching. For that reason, if you like to dynamically add more than 1 field dynamically, you need to disable the field counter with the following filter:

    add_filter( 'hf_validate_form_request_size', '__return_false' );

    Add Tag to Mailchimp Contact

    This requires the MC4WP plugin to be active and configured.

    Give users a link to a form, and include “?hfmuc_email={{their_email}}” as a querystring parameter.

    Then make sure the form has a hidden field named “EMAIL” whose value is “{{hfmuc_email}}” like this example:

    <input type="hidden" name="EMAIL" placeholder="Your email" required value="{{hfmuc_email}}" />

    Find your list ID and put it in $list_id below. Then local the HTML Forms slug (seen when editing the form) and put it in $form_slug. Next, add any tags you want to $tags_data.

    Now the user will get a link to the form, fill it out (no need to re-enter their email), and upon successful submission, those tags will be added to their Mailchimp contact.

    use \HTML_Forms\Submission;
    use HTML_Forms\Form;
    
    // Get the user's email from the query parameters
    add_filter(
    	'hf_form_html',
    	function ( $html ) {
    		$email = isset( $_GET['hfmuc_email'] ) ? $_GET['hfmuc_email'] : '';
    		return str_replace( '{{hfmuc_email}}', $email, $html );
    	}
    );
    // Adds tags to the given user.
    add_action(
    	'hf_form_success',
    	function ( $submission, $form ) {
    		// Check that it's the right form.
    		$form_slug = 'survey-1';
    		if ( $form->slug !== $form_slug ) {
    			return;
    		}
    
    		$email_address = $submission->data['EMAIL'];
    		$api           = mc4wp_get_api_v3();
    
    		// aka "audience ID". See https://mailchimp.com/help/find-audience-id/
    		$list_id = '32ccd044c3';
    
    		// see https://mailchimp.com/developer/reference/lists/list-members/list-member-tags/#read-get_lists_list_id_members_subscriber_hash_tags
    		$tags_data = array(
    			'tags' => array(
    				array(
    					'name'   => 'Test',
    					'status' => 'active',
    				),
    			),
    		);
    
    		$result = $api->update_list_member_tags(
    			$list_id,
    			$email_address,
    			$tags_data
    		);
    	},
    	10,
    	2
    );

    Add URL to Email Message

    It’s possible to filter the email action message with PHP. This example will add the URL the form was submitted from to the end of the email notification message.

    add_filter(
    	'hf_action_email_message',
    	function ( $message ) {
    		return $message . sprintf( '<br />Referrer URL: %s', esc_html( $_SERVER['REQUEST_URI'] ) );
    	}
    );

    Custom Form Message

    The default message keys are:

    • success
    • invalid_email
    • required_field_missing
    • error
    add_filter(
    	'hf_form_message_success',
    	function( $message ) {
    		return 'Your custom success message here';
    	}
    );

    Custom Form Validation

    // validate form request (all forms)
    // this will validate that the field with name "BEST_VEGETABLE" is set and has a value of "carrot"
    add_filter(
    	'hf_validate_form',
    	function( $error_code, $form, $data ) {
    		if ( ! isset( $data['BEST_VEGETABLE'] ) || $data['BEST_VEGETABLE'] !== 'carrot' ) {
    			$error_code = 'wrong_answer';
    		}
    
    		return $error_code;
    	},
    	10,
    	3
    );
    
    // validate form request (form with ID 60 only)
    add_filter(
    	'hf_validate_form',
    	function( $error_code, $form, $data ) {
    		if ( $form->ID != 60 ) {
    			return $error_code;
    		}
    
    		if ( ! isset( $data['BEST_VEGETABLE'] ) || $data['BEST_VEGETABLE'] !== 'carrot' ) {
    			$error_code = 'wrong_answer';
    		}
    
    		return $error_code;
    	},
    	10,
    	3
    );
    
    // register error message for our custom error code
    add_filter(
    	'hf_form_message_wrong_answer',
    	function( $message ) {
    		return 'Sorry, but the best vegetable is a carrot!';
    	}
    );

    Do Not Store IP Address and User Agent

    add_action(
    	'hf_process_form',
    	function( $form, $submission ) {
    		$submission->ip_address = '';
    		$submission->user_agent = '';
    	},
    	10,
    	2
    );

    File Upload Direct Links

    Instruct HTML Forms to not link to WP Media attachments for uploaded files, but use a direct link to the actual file. This requires the HTML Forms Premium add-on.

    add_filter( 'hf_file_upload_use_direct_links', '__return_true' );

    Disable File Uploads to WordPress Admin Media Library

    This requires the HTML Forms Premium add-on.

    add_filter( 'hf_upload_add_to_media', '__return_false' );

    Change Maximum Size Allowed for File Uploads

    This requires the HTML Forms Premium add-on.

    add_filter(
    	'hf_upload_max_filesize',
    	function( $size ) {
    		// size in bytes, 1000000 = 1MB
    		return 1000000;
    	}
    );

    Filter Email Action to Specific Email Address

    add_filter(
    	'hf_action_email_to',
    	function( $to, $submission ) {
    		if ( $submission->data['FOO'] === 'BAR' ) {
    			return 'support@acmeinc.com';
    		}
    
    		return $to; // default "To" as specified in action settings
    	},
    	10,
    	2
    );

    Manually Load HTML Forms JavaScript

    If you’re having issues with the HTML Forms JavaScript file not being loaded, you can use the following snippet to load it manually.

    add_action(
    	'wp_enqueue_scripts',
    	function() {
    		wp_enqueue_script( 'html-forms' );
    	},
    	90
    );

    Modify Email Action Recipient

    add_action(
    	'hf_action_email_to',
    	function ( $to, \HTML_Forms\Submission $submission ) {
    		// $to contains the default recipient, from the action settings
    		// you can replace it with a different email addresses or turn it into an array of recipients
    		return array( $to, 'john.doe@email.com' );
    	}
    );

    Create a Multi-Step Form

    <!-- Step 1 -->
    <div data-show-if="_STEP:">
      <p>
          <label>Name</label>
          <input type="text" name="NAME" placeholder="" value="Danny" required />
      </p>
      <p>
        <button type="button" name="_STEP" value="2">Continue to step 2</button>
      </p>
    </div>
    
    <!-- Step 2 -->
    <div data-show-if="_STEP:2">
      <p>
          <label>Email address</label>
          <input type="email" name="EMAIL" placeholder="Your email address" value="danny@email.com" required />
      </p>
    
      <p>
          <button type="button" name="_STEP" value="3">Continue to step 3</button>
          <button type="button" name="_STEP" value="">Back</button>
      </p>
    </div>
    
    <!-- Step 3 -->
    <div data-show-if="_STEP:3">
      <p>
          <input type="submit" value="Send" />
      </p>
    </div>

    Perform Action After Successful Form Submission

    This code runs for every successful form submission.

    add_action(
    	'hf_form_success',
    	function( $submission, $form ) {
    		// You can do stuff here.
    		// $form contains details about the submitted form
    		// $submission contains details about the submission, like the form data.
    	},
    	10,
    	2
    );

    Template Tags

    This example replaces {{replace_me}} with “replaced!” using a simple string replacement.

    add_filter(
    	'hf_template_tags',
    	function( $tags ) {
    		$tags['replace_me'] = 'replaced!';
    		return $tags;
    	}
    );
    

    This example uses a function accepting a single parameter to determine the replacement value

    Example: {{replace_me.foo}}

    add_filter(
    	'hf_template_tags',
    	function( $tags ) {
    		$tags['replace_me'] = function( $key ) {
    			if ( $key === 'foo' ) {
    				return 'bar';
    			}
    
    			return 'not bar';
    		};
    		return $tags;
    	}
    );