Los artículos de la categoría Manual del desarrollador abordan temas que requieren conocimiento técnico. Ten cuidado y utiliza las técnicas descritas a continuación bajo tu propia responsabilidad. Si no tienes experiencia en desarrollo, y necesitas ayuda, te recomendamos solicitar el apoyo de un profesional.
En la receta anterior vimos cómo añadir etiquetas de formulario personalizadas de forma sencilla. En esta receta aprenderás a recuperar los valores de una etiqueta de formulario y utilizarlos en el HTML que genera un formulario.
Vamos a crear una etiqueta de formulario personalizada que represente un campo de entrada asociado a una lista de datos. Datalist es un elemento nuevo introducido en HTML5 que proporciona una lista de opciones predefinidas para un campo de entrada asociado a dicha lista.
El siguiente ejemplo muestra el marcado HTML de un campo de texto y una lista de datos.
<input name="currency" type="text" list="currency-options" />
<datalist id="currency-options">
<option>Dólares estadounidenses ($)</option>
<option>Euros (€)</option>
</datalist>
En este ejemplo, el atributo list del elemento input y el atributo id del elemento datalist comparten el mismo valor («currency-options»), por lo que ambos elementos quedan asociados.
Este campo de entrada espera el nombre de una moneda. Aunque puedes escribir cualquier nombre de moneda, ofrece «Dólares estadounidenses ($)» y «Euros (€)» como opciones predefinidas, ya que son las respuestas más probables.
Diseñar una etiqueta de formulario
Vamos a diseñar la etiqueta de formulario para un campo de entrada con una lista de datos. Primero, debes decidir el tipo de etiqueta. La llamaremos «datalist».
En el marcado HTML del ejemplo anterior puedes identificar tres variables: el valor del atributo name («currency», en el ejemplo), los valores de los atributos list e id («currency-options») y el contenido de los elementos option («Dólares estadounidenses ($)» y «Euros (€)»).
Los atributos list e id deben tener el mismo valor, pero ese valor puede ser cualquiera, siempre que sea válido para un atributo id. Si se puede definir automáticamente, por ejemplo, añadiendo el sufijo -options al valor del atributo name, podemos reducir el número de variables. Así, solo tendrás que definir en la etiqueta de formulario el valor del atributo name y el contenido de los elementos option.
Para el valor del atributo name, vamos a utilizar la parte name (la segunda palabra) de la etiqueta de formulario, ya que es lo habitual en otros tipos de etiquetas de formulario de Contact Form 7.
En cuanto al contenido de los elementos option, como probablemente será de formato libre, lo más adecuado es utilizar la parte values (las cadenas entre comillas, al final) de la etiqueta de formulario.
Consulta también: Cómo funcionan las etiquetas
En resumen, estas decisiones de diseño nos permiten representar el marcado HTML del ejemplo anterior con la siguiente etiqueta de formulario sencilla:
Ahora vamos a escribir el código para implementar esta etiqueta de formulario.
Implementar la etiqueta de formulario
Primero, registra el tipo de etiqueta de formulario «datalist» mediante la función wpcf7_add_form_tag(). A diferencia de la etiqueta de formulario [clock], que vimos en la receta anterior, esta etiqueta tiene una parte name, por lo que debes establecer el tercer argumento de wpcf7_add_form_tag() como 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 )
);
}
A continuación, define la función de retorno de llamada que genera el HTML.
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;
}
El parámetro $tag que se pasa a la función de retorno de llamada es un objeto WPCF7_FormTag. La clase WPCF7_FormTag proporciona varias propiedades y métodos para acceder a la información de la etiqueta de formulario.
En esta función, primero creas el elemento input. Para ello, defines los atributos necesarios (type, name y list) como elementos de una matriz ($atts) y, después, utilizas la función wpcf7_format_atts() para generar una cadena de atributos con el formato adecuado. Se recomienda utilizar wpcf7_format_atts() porque escapa correctamente los valores y permite generar una salida segura.
A continuación, construyes el elemento datalist, que contiene elementos option secundarios con los valores de la etiqueta de formulario. Por último, concatenas los elementos input y datalist y devuelves el resultado de la función.
Y eso es todo. Esta etiqueta de formulario sigue siendo muy sencilla y ni siquiera valida los datos introducidos por el usuario. En próximas recetas veremos cómo implementar la validación.