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.

Esta es la primera entrada de una serie de artículos para ayudar a los desarrolladores a personalizar Contact Form 7.

El primer tema que trataremos será cómo ampliar las etiquetas de formulario de Contact Form 7. Como probablemente ya sabes, las etiquetas de formulario son códigos en un formato específico entre corchetes, que generalmente representan controles de formulario como campos de entrada de texto y botones de envío. Actualmente, Contact Form 7 incluye 30 tipos diferentes de etiquetas de formulario por defecto.

Estos son ejemplos de etiquetas de formulario típicas:

[text* tu-nombre]
[textarea tu-mensaje]
[submit "Enviar"]

Se parecen a los shortcodes de WordPress, pero a diferencia de estos, las etiquetas de formulario solo funcionan dentro del área de edición de formularios de Contact Form 7.

Tú también puedes añadir tus propias etiquetas de formulario personalizadas. Debes seguir estos dos pasos para hacerlo: (1) registrar los tipos de etiquetas de formulario y una función de retorno correspondiente, y (2) definir la función de retorno. Veamos cada paso.

wpcf7_add_form_tag

Para registrar tipos de etiquetas de formulario, llama a la función wpcf7_add_form_tag(). Esta función acepta tres parámetros, dos obligatorios y uno opcional.

El primer parámetro es un valor de tipo cadena que contiene el tipo de etiqueta. La primera palabra en una etiqueta de formulario es su tipo. En los ejemplos presentados anteriormente, «text*», «textarea» y «submit» son tipos. Puedes usar letras minúsculas ([a-z]), dígitos ([0-9]), guiones bajos («_») y asteriscos («*») en un tipo de etiqueta de formulario. Los tipos de etiquetas con un asterisco al final (p. ej., «text*», «email*») se usan para hacer que los campos de entrada sean obligatorios.

Si tienes dos o más tipos de etiquetas de formulario que comparten la misma función de retorno, es posible que desees registrarlas juntas. En ese caso, especifica un array de cadenas como primer parámetro.

El segundo parámetro es una función de retorno que se llama cuando Contact Form 7 analiza la etiqueta de formulario. Volveremos a las funciones de retorno más adelante.

El tercer parámetro opcional es un array de características que admite el tipo de etiqueta de formulario. Por ejemplo, un tipo de etiqueta de formulario cuyas instancias tengan un nombre compatible con el atributo name-attr.

El nombre de una etiqueta de formulario es la segunda palabra en la etiqueta de formulario. En los ejemplos anteriores, «tu-nombre» y «tu-mensaje» son nombres. Algunas etiquetas de formulario no tienen nombres, como [submit "Enviar"].

Para los tipos de etiquetas de formulario que sean compatibles con el atributo name-attr, escribe array( 'name-attr' => true) como tercer parámetro de wpcf7_add_form_tag().

Ten en cuenta que debes usar el gancho de acción wpcf7_init cuando llames a wpcf7_add_form_tag(). Para referencia, consulta cómo Contact Form 7 registra las etiquetas de formulario por defecto.

add_action( 'wpcf7_init', 'wpcf7_add_form_tag_text' );

function wpcf7_add_form_tag_text() {
  wpcf7_add_form_tag(
    array( 'text', 'text*', 'email', 'email*', 'url', 'url*', 'tel', 'tel*' ),
    'wpcf7_text_form_tag_handler',
    array( 'name-attr' => true )
  );
}

Función de retorno

El siguiente paso es definir la función de retorno. Esta función toma un objeto WPCF7_FormTag como único argumento, que representa la información de una etiqueta de formulario actual, incluyendo su tipo, nombre, opciones, valores, etc.

La función de retorno debe devolver un valor de tipo texto. Por lo general, devuelven fragmentos de código HTML que representan un control de formulario. El texto devuelto reemplaza la etiqueta de formulario cuando Contact Form 7 genera un formulario a partir de una plantilla que contiene etiquetas de formulario.

Como demostración, creemos una etiqueta de formulario simple que muestre la hora actual (llamémosla «[reloj]»).

Añade el siguiente código en un lugar apropiado. Muchos desarrolladores prefieren usar el archivo functions.php del tema para pequeños fragmentos de código personalizados. No edites archivos directamente en la carpeta del plugin (contact-form-7) porque corres el riesgo de romper el código de Contact Form 7 y además perderás tu personalización cuando se actualice el plugin.

add_action( 'wpcf7_init', 'custom_add_form_tag_clock' );

function custom_add_form_tag_clock() {
  wpcf7_add_form_tag( 'reloj', 'custom_clock_form_tag_handler' ); // «reloj» es el tipo de etiqueta de formulario
}

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

Luego, añade esta línea a tu área de formulario:

Hora actual: [reloj]

Si funciona correctamente, deberías ver una línea como esta en el formulario:

Hora actual: 12:16 pm

Eso es todo. Obviamente, esta demostración de «[reloj]» es demasiado sencilla para un uso práctico, pero es suficiente para mostrar el concepto de las etiquetas de formulario de Contact Form 7. Para mejorarlas y hacerlas más adecuadas para un uso práctico, deberás aprender:

• Cómo recuperar información de componentes de etiquetas de formulario y construir controles de formulario más complejos utilizando esta información.
• Cómo validar la entrada del usuario y, si no es válida, cómo mostrar un error de validación.

En los próximos artículos cubriremos estas áreas.