Filter Hooks

It’s possible to modify or extend the default behavior of HTML Forms beyond what is possible with the available settings. To achieve this, you can use any of the available action hooks and filter hooks in the plugin.

To learn more about what filter hooks are, please refer to the WordPress plugin API documentation.

Available Filter Hooks

Below is a list of all available filter hooks in the plugin.

hf_form_element_action_attr

Filters the action attribute for the form element.

Default value: null

hf_form_element_class_attr

Filters the CSS classes which are added to the form element’s class attribute.

Default value: ""

hf_form_html

Filters the complete form HTML when the form is outputted.

hf_validate_form

Filters the error code when a form is validated. Return an empty string if the form validates without errors.

Default value: ""

Conditional Elements

Conditional elements are supported in HTML Forms by using two special attributes: data-show-if and data-hide-if.

Using these attributes allows you to hide or show parts of your form by referencing the name attribute of a field in your form.

For example, you could choose to only show the submit button after the email field is filled.

<input type="email" name="EMAIL" required />
<input type="submit" value="Send" data-show-if="EMAIL" />

Let’s do another example where you have a help text is hidden after someone starts typing in the field it describes.

<input type="text" name="NAME" />
<p data-hide-if="NAME">Enter your name in the field above.</p>

Specifying an Exact Value

The examples above will show or hide an element whenever the field that it is depending on contains any value, regardless of the actual value.

Sometimes you want to depend on an exact value though. This can be done by following the field name with a colon and the value you need, like this: NAME:VALUE.

Let’s build a form with a list of checkboxes, where a message shows up only when one particular choice is selected.

<input type="checkbox" name="JOB" value="Marketeer" /> Marketeer
<input type="checkbox" name="JOB" value="Developer" /> Developer
<input type="checkbox" name="JOB" value="Recruiter" /> Recruiter

<div data-show-if="JOB:Recruiter">
    Hi, recruiter!
</div>

Specifying Multiple Values

Continuing with the above example, what if you wanted to show part of your form for both developers and marketeers?

You can specify multiple expected values by separating them with a |.

<input type="checkbox" name="JOB" value="Marketeer" /> Marketeer
<input type="checkbox" name="JOB" value="Developer" /> Developer
<input type="checkbox" name="JOB" value="Recruiter" /> Recruiter

<div data-show-if="JOB:Marketeer|Developer">
    Hi, marketeer or developer!
</div>

JavaScript Events

HTML Forms fires several JavaScript events when visitors interact with a form on your site. You can hook into these events to run your own code, for example to send events to Google Analytics.

Available Events

The following events are available:

submit

Fires right after the form is submitted, but before the request is processed.

submitted

Fires after the request is processed, for both successful submissions and errors.

error

Fires after the request is processed when a validation error occurs, for example, when a required field is missing.

success

Fires after the request is processed, and the submission was a success.

Hooking Into an Event

The following code example hooks into the “success” event for all forms (see above).

<script>
html_forms.on('success', function(formElement) {
   // your code goes here
});
</script>

Alternatively, you can hook into a specific form using the default browser events API too.

<script>
document.querySelector('.hf-form-5').on('hf-success', function(e) {
   // your code goes here
});
</script>

You can add this code directly to your form mark-up or to any other JavaScript file that is loaded on your site.

Custom Form Validation

HTML Forms will perform the following form validation by itself:

  • All input fields marked as required should have a non-empty value.
  • All fields of type “email” should have a value that looks like an email address, or no value at all (if not required).

If you want to perform additional form validation, then you can do so by hooking into the hf_validate_form filter hook.

The following example will only accept the form submission if the field named “BEST_VEGETABLE” is filled and the value “carrot” is submitted.

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 );

Showing a Custom Error Message

The $error_code indicates what message should be shown to the person filling out the form. Since we did not register a message with that error code, the plugin will default to showing the general error message instead.

Let’s improve upon this by showing a more detailed error message describing exactly why the form validation failed.

add_filter( 'hf_form_message_wrong_answer', function( $message ) {
    return 'Sorry, but the best vegetable is a carrot!';
});

Action Hooks

It’s possible to modify or extend the default behavior of HTML Forms beyond what is possible with the available settings. To achieve this, you can use any of the available action hooks and filter hooks in the plugin.

To learn more about what action hooks are, please refer to the WordPress plugin API documentation.

Available Action Hooks

Below is a list of all available action hooks in the plugin.

hf_form_success

Runs when a form is submitted successfully, after the submission was saved.

Parameters: $submission$form

hf_form_error

Runs when a form is submitted but a validation error occurs.

Parameters: $error_code$form$data