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.
