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

Sending E-mail Notifications

You can configure HTML Forms to send out an email notification whenever a form is successfully submitted.

To set this up, edit your form and open up the Actions tab. Near the bottom of the page should be a heading titled Add Form Action with a Send Email button.

Clicking that Send Email button will add a settings block to the page that should look like this:

Settings

Here’s what each setting does.

From

Define the email address you wish the message to come from. This field accepts field value placeholders.

It is advised to pick an address with the same domain name as your website to prevent ending up in someone’s SPAM folder. For example, if your website is flowers.com, then lee@flowers.com is better than leeflowers@gmail.com.

Also note that if you use a third-party email senders on your WordPress site that the address in this field must be validated with that service.

To

The email address that the email should be sent to. This field also accepts field value placeholders.

Subject

The subject of your email message. This field also accepts field value placeholders.

Message

The actual message body of the email. This field also accepts field value placeholders.

Content Type

You can decide if your email is HTML or plain text.

Additional Headers

You can include custom headers with your email. We recommend, if you want to define a Reply-To address, you use this setting with placeholders.

Redirect to URL After Form Submit

You can configure HTML Forms to redirect to a certain page on your website after each successful form submission. An example use case would be to send visitors to a “Thank You” page after they submit your form.

To set this up, open up your form, navigate to the Settings tab and locate the setting for a redirect:

Make sure to use complete (absolute) URL’s and to redirect to a page that describes that the form was processed successfully. You don’t want to confuse your visitors with a random redirect.

Template Variables

HTML Forms provides several template variables you can use in your form content. These form variables will be dynamically replaced when the form is shown. Currently, you can use the following variables.

user

Will be replaced with the specified property of the currently logged-in user.

{{ user.user_email }}

url_params

This will be replaced with a parameter from the page URL, or with an empty string if the specified URL parameter does not exist.

{{url_params.utm_source}}

post

This will be substituted with the specified property of the post that is viewed on the page the form is displayed on.

{{post.ID}}

Hide Form Fields After Submission

Hiding a form after it was successfully submitted is easy with HTML Forms.

Open up your form, navigate to the Settings tab and toggle the setting shown below to Yes.

This will hide your form fields after the form is submitted without errors. The success message you enter will still show, regardless of the setting.

Installing the HTML Forms Premium Add-on

Let’s walk through how to install the HTML Forms Premium add-on. After registering your account and processing your payment, you immediately have access to the HTML Forms account area.

Download HTML Forms Premium

After logging in to your account, head on over to the plugins page.

Click the Download button to download the latest version of HTML Forms Premium.

Note for Safari for Mac users for which the .zip file automatically extracts after downloading, either go to Preferences > General and uncheck “Open safe files after downloading” or simply re-compress the files to a .zip again.

Installing & Activating HTML Forms Premium

Log in to your WordPress admin panel, go to Plugins > Add New and locate the Upload Plugin link.

Browse to the location where the downloaded plugin package is located on your computer and select it. WordPress will automatically upload the plugin to your server. After that is done, you can safely click the Activate link to activate the plugin.

Now that HTML Forms Premium is active, all premium features are instantly unlocked.