Posts in the developer's cookbook category describe topics that require technical knowledge. Be warned and use the techniques at your own risk. Unless you are an experienced developer, you are strongly advised to ask a professional for support.
The previous recipe illustrated how you can add custom form-tags simply. In this recipe, you’ll learn how to retrieve values from a form-tag and use those values in the HTML output in a form.
We are going to create a custom form-tag that represents an input field with an associated datalist. Datalist is a new element introduced in HTML5; it provides a list of predefined options for an input field associated with a datalist.
The following listing shows an example HTML markup for a text input field and a datalist.
<input name="currency" type="text" list="currency-options" />
<datalist id="currency-options">
<option>U.S. Dollars ($)</option>
<option>Euros (€)</option>
</datalist>
In this example, the list
attribute of the input
element and the id
attribute of the datalist
element share the same value (“currency-options”), thus the two elements are associated with each other.
This input field expects a currency name. While you can type an arbitrary currency name here, it provides “U.S. Dollars ($)” and “Euros (€)” as predefined options because they are the most likely answers.
Designing a form-tag
Let’s design the form-tag for an input field with a datalist. First, you need to decide the type of form-tag. Let’s name it “datalist”.
You can see three variables in the HTML markup in the listing above: the name
attribute value (“currency” in the example), the list
and id
attribute values (“currency-options”), and the option
element contents (“U.S. Dollars ($)” and “Euros (€)”).
The list
and id
attributes need to have the same value, and it doesn’t matter what that value is (as long as it is valid as an id
value). If the value can be automatically defined, say, by adding a suffix -options to the name
attribute value, you can reduce the number of variables. Now, you only have to define the name
attribute value and option
element contents in the form-tag.
For the name
attribute value, let’s use the name part (the second word) in a form-tag because it’s commonly used for the name
attribute value in other form-tag types of Contact Form 7.
For the option
element contents, since the contents are likely to be in a free format, using the values part (quoted strings; the final part) in a form-tag is suitable.
See also: How tags work
To sum up these design decisions, the following simple form-tag should be able to represent the example HTML markup in the listing above:
[datalist currency "U.S. Dollars ($)" "Euros (€)"]
Let’s start coding to implement this form-tag.
Implementing the form-tag
First, register the “datalist” form-tag type with wpcf7_add_form_tag()
function. Unlike the [clock] form-tag that we saw in the previous recipe, this tag has a name part so you need to set the third argument of wpcf7_add_form_tag()
to array( 'name-attr' => true )
.
add_action( 'wpcf7_init', 'custom_add_form_tag_datalist' );
function custom_add_form_tag_datalist() {
wpcf7_add_form_tag(
'datalist',
'custom_datalist_form_tag_handler',
array( 'name-attr' => true )
);
}
Then, define the callback function that generates HTML output.
function custom_datalist_form_tag_handler( $tag ) {
$atts = array(
'type' => 'text',
'name' => $tag->name,
'list' => $tag->name . '-options',
);
$input = sprintf(
'<input %s />',
wpcf7_format_atts( $atts )
);
$datalist = '';
foreach ( $tag->values as $val ) {
$datalist .= sprintf( '<option>%s</option>', esc_html( $val ) );
}
$datalist = sprintf(
'<datalist id="%1$s">%2$s</datalist>',
$tag->name . '-options',
$datalist
);
return $input . $datalist;
}
The $tag
parameter passed to the callback function is a WPCF7_FormTag
object. WPCF7_FormTag
class provides several properties and methods to access information from the form-tag.
In this function, you first create the input
element. There, you set the necessary attributes (type
, name
, and list
) as items of an array ($atts
), and then using wpcf7_format_atts()
function, you generate a formatted attribute string. Using wpcf7_format_atts()
is recommended because it properly escapes values to provide a secure output.
Then, you build the datalist
element that contains child option
elements with the values from the form-tag. Finally, the input
and datalist
elements are concatenated and returned as the result of this function.
That’s it. This form-tag is still too simple and doesn’t even provide user-input validation. Upcoming recipes will deal with validation.