Adding A Custom Form-Tag

This is the first entry in a series of articles to help developers customize Contact Form 7.

The first topic is expanding Contact Form 7’s form-tags. As you probably know, form-tags are code in a specific format within square brackets, usually representing form controls like text input fields and submit buttons. Currently, Contact Form 7 supports 30 different types of form-tags by default.

These are examples of typical form-tags:

[text* your-name]
[textarea your-message]
[submit "Send"]

They look like WordPress shortcodes, but unlike shortcodes, form-tags only work within a Contact Form 7 form area.

You can add your own custom form-tags as well. There are two steps to add custom form-tags: (1) register form-tag types and a corresponding callback function, and (2) define the callback function. Let’s look at each step.

wpcf7_add_shortcode

To register form-tag types, call wpcf7_add_shortcode() function. wpcf7_add_shortcode() accepts three parameters (two required and one optional).

The first parameter is a string value containing the type of the tag. The first word in a form-tag is its type. In the examples presented above, “text*”, “textarea”, and “submit” are types. You can use lower-case letters ([a-z]), digits ([0-9]), underscores (“_“), and asterisks (“*“) in a form-tag type. Tag types with a trailing asterisk (e.g., “text*”, “email*”) are used for required input fields.

If you have two or more form-tag types sharing the same callback function, you may want to register them together. In such cases, specify an array of strings as the first parameter.

The second parameter is a callback function called when Contact Form 7 parses the form-tag. More on callback functions later.

The third parameter is an optional Boolean value (default: false). If the form-tag has a name part, set this to true. The name of a form-tag (if it has a name) is the second word in the form-tag. In the examples above, “your-name” and “your-message” are names. Some form-tags don’t have names, like [submit "Send"].

Note that you have to use wpcf7_init action hook when you call wpcf7_add_shortcode(). For reference, see how Contact Form 7 registers default form-tags.

add_action( 'wpcf7_init', 'wpcf7_add_shortcode_text' );

function wpcf7_add_shortcode_text() {
	wpcf7_add_shortcode(
		array( 'text', 'text*', 'email', 'email*', 'url', 'url*', 'tel', 'tel*' ),
		'wpcf7_text_shortcode_handler', true );
}

Callback Function

The next step is defining the callback function, which only receives a parameter that is an array containing components (type, name, options, values, etc.) of an actual form-tag.

The callback function must return a text value. Usually they return HTML snippets that represent a form control. The returned text replaces the form-tag when Contact Form 7 generates a form from a form template containing form-tags.

As a demonstration, let’s create a simple form-tag that displays the current time (let’s call it “[clock]”).

Add the following code at an appropriate place. Many developers prefer to use theme’s functions.php file for small custom coding. Don’t directly edit files in the plugin (contact-form-7) folder because you risk breaking the plugin code, and you’ll lose your customization when the plugin is updated.

add_action( 'wpcf7_init', 'custom_add_shortcode_clock' );

function custom_add_shortcode_clock() {
	wpcf7_add_shortcode( 'clock', 'custom_clock_shortcode_handler' ); // "clock" is the type of the form-tag
}

function custom_clock_shortcode_handler( $tag ) {
	return date_i18n( get_option( 'time_format' ) );
}

Then, add this line to your form area:

Current Time: [clock]

If it works correctly, you should see a line like this in the form:

Current Time: 12:16 pm

That’s it. Obviously this “[clock]” demo is too simple for practical use, but it’s enough to show the concept of the Contact Form 7 form-tags. To improve and make it suitable for practical use, you’ll need to learn:

• How to retrieve information from form-tag components and construct more complex form controls using this information.
• How to validate user input, and if it’s invalid, how to show a validation error.

Upcoming recipes will cover these areas.