Formularios PDF

Al construir un formulario PDF en LaTeX —cajas de texto rellenables, casillas— siempre se pisa la misma mina. Escribe \TextField{Name}, compila y sale un PDF sin error, sin aviso y sin campo de entrada alguno. La etiqueta «Name» queda compuesta en el texto, pdfinfo responde Form: none y al mirar dentro del archivo no aparece ni una anotación de widget. Fuera de un entorno Form, los comandos de campo de hyperref no producen nada, en silencio. Esta página arranca en \begin{Form} y sigue, con mediciones, qué escribe realmente cada campo en el PDF, adónde envía sus datos un botón de envío por defecto y en qué punto conviene rendirse y hacer un formulario web.

Sin entorno Form no hay campos

Todo campo interactivo va dentro de \begin{Form} … \end{Form}. No es una convención de estilo: cambia la salida. Compila un documento con \TextField y \CheckBox fuera del entorno y pdflatex termina con código 0 y sin aviso alguno, pero el PDF resultante contiene cero anotaciones /Widget y pdfinfo sigue informando Form: none. Mueve los mismos comandos dentro y pdfinfo pasa a responder Form: AcroForm. Un formulario PDF se construye como un único diccionario AcroForm que reúne todos los campos, y el entorno Form es lo que crea ese diccionario. Además, \usepackage{hyperref} por sí solo basta: no hace falta una opción de controlador como [pdftex]; el registro muestra hpdftex.def cargándose automáticamente.

El entorno Form acepta, contando en el fuente de hyperref, exactamente cuatro claves: action (adónde van los datos), method, encoding y NeedAppearances. Todo lo relativo al aspecto y al comportamiento de un campo se fija en el [...] de ese campo, así que basta con ver las opciones del entorno como los ajustes de envío.

\documentclass{article}
\usepackage{hyperref}          % no driver option needed
\begin{document}
\begin{Form}[action={https://example.org/collect},method=post]
  \TextField[name=fullname,width=6cm]{Name}\par
  \CheckBox[name=agree]{I agree}\par
  \ChoiceMenu[combo,name=affil]{Affiliation}{University,Company,Other}\par
  \Submit{Send}\quad\Reset{Clear}
\end{Form}
\end{document}

Los comandos de campo y qué escribe cada uno en el PDF

Hay cinco comandos de campo y, del lado del PDF, se reducen a tres tipos: el texto es /Tx, la elección es /Ch, y todo lo que tenga forma de botón —casilla, botón, envío, reinicio— es /Btn. Compila el ejemplo anterior, extrae los objetos y encontrarás justo eso: dos /Tx, uno /Ch y cuatro /Btn. Agrupar los botones es lo que prescribe la especificación PDF; la diferencia entre una casilla y un botón no está en el tipo sino en bits del campo de banderas (/Ff). Esa estructura —el carácter lo deciden las banderas— importará en la sección siguiente.

Si omites name=, la etiqueta pasa a ser el nombre del campo, y la trampa del grupo de radio

Si omites name=, el texto de la etiqueta pasa a ser el nombre del campo. Mira dentro de un PDF hecho con \TextField{Your name} y el nombre del campo es /T (Your name), espacios incluidos. Es un nombre incómodo para lo que reciba los datos, y una etiqueta en español da un nombre de campo en español. La práctica profesional es dar siempre un identificador ASCII con name=. Hay una segunda consecuencia: escribe el mismo name= dos veces y PDF trata los campos con el mismo nombre como uno solo. Dos \TextField con name=dup producen dos objetos que llevan ambos /T (dup), y escribir en uno rellena el otro con el mismo valor. Es útil cuando quieres repetir a propósito un valor en dos sitios, pero una colisión accidental genera un fallo cuya causa cuesta ver.

Los botones de radio esconden un problema más hondo. Compila \ChoiceMenu[radio,name=r1]{Pick}{a,b,c} y obtienes tres objetos /Btn llamados todos r1, pero solo el primero aparece en el array /Fields del diccionario AcroForm. Los otros dos quedan sueltos, sin que ningún campo los referencie. Pasa el archivo por qpdf y lo dice dos veces: WARNING: this widget annotation is not reachable from /AcroForm in the document catalog. La especificación PDF quiere que un grupo de radio se exprese con un campo padre que reúna a sus hijos mediante /Kids; hyperref los coloca en plano. Muchos visores lo muestran igualmente, por lo que el problema pasa inadvertido, pero es una estructura que puede romperse ante un procesador PDF estricto o un extractor automático. Cuando las opciones son fijas, combo o popdown es la herramienta más honesta.

Las opciones que conviene conocer: cuáles se vuelven banderas y cuáles no

Cada campo acepta una larga lista de opciones en [...] — hyperref define cerca de treinta claves. Las habituales son name=, width=/height=, default= (valor inicial), bordercolor/backgroundcolor, charsize, align (0 = izquierda, 1 = centro, 2 = derecha), maxlen= (máximo de caracteres) y menulength= (cuántas filas muestra una lista). De todas ellas, solo multiline, readonly y password son interruptores sin valor que se corresponden uno a uno con banderas PDF: desde la línea 5283, hyperref.sty define ReadOnly como bit 1, Multiline como bit 13 y Password como bit 14; al compilar un formulario y releer /Ff salen exactamente 1, 4096 y 8192. maxlen=5, en cambio, no es una bandera: se escribe como una entrada aparte, /MaxLen 5. Saber cuál es cuál indica dónde mirar cuando una opción no hace lo esperado.

\begin{Form}
  \TextField[name=notes,multiline,width=8cm,height=3cm]{Notes}\par
  \TextField[name=locked,readonly,width=4cm,default={fixed}]{Locked}\par
  \TextField[name=short,maxlen=5,width=3cm]{Max 5}\par
  \TextField[name=email,width=5cm,align=0,
             bordercolor={0 0 0},backgroundcolor={1 1 0.9}]{Email}
\end{Form}

\Submit envía FDF por defecto: method=post por sí solo no basta

Este es el punto más importante de la página. Escribe \begin{Form}[action={https://example.org/collect},method=post], pulsa el botón de envío y lo que llega a tu servidor no es un POST de formulario HTML sino FDF, el formato de datos propio de Acrobat. La causa está en la línea 5371 de hyperref.sty: \def\Fld@export{fdf} fija el formato de exportación por defecto en FDF. Compila y extrae la acción de envío: encontrarás /S /SubmitForm sin entrada /Flags alguna, es decir, todas las banderas a cero, o sea FDF. ¿Y method=post? Lee \HyField@FlagsSubmit desde la línea 5378: la bandera GetMethod que fija method solo se usa en las ramas HTML y PDF, y se ignora por completo en la rama FDF. Por tanto, method=post por sí solo no hace absolutamente nada.

Para que lo reciba un servidor web corriente, añade encoding=html al entorno Form. Es una clave dedicada que ejecuta \def\Fld@export{html} hacia la línea 5665 de hyperref.sty; con ella, la acción de envío gana /Flags 4: el bit 3, ExportFormat, queda activado, es decir, codificación HTML. Por cierto, escribir algo distinto de html en encoding solo produce un aviso Form 'encoding' key with unknown value antes de ignorarse en silencio. Los demás formatos de exportación disponibles son xfdf (una variante XML de FDF) y pdf (que envía el PDF relleno entero).

% FDF (the default) -- your endpoint receives an Acrobat-specific blob
\begin{Form}[action={https://example.org/collect},method=post]

% an ordinary HTML form post -- note encoding=html
\begin{Form}[action={https://example.org/collect},encoding=html,method=post]

Qué hacen los visores reales y cuándo rendirse

Los formularios de hyperref no escriben la apariencia del campo en el archivo en absoluto. Fijan /NeedAppearances true en el diccionario AcroForm, lo que equivale a pedirle al visor que dibuje él mismo los controles. Acrobat Reader atiende esa petición, pero el soporte varía: en el visor PDF integrado de un navegador o en un visor ligero puede que no aparezca el recuadro, o que no se pueda escribir en él. En cuanto al JavaScript de \PushButton[onclick=...], los visores que lo ejecutan son minoría. La misma propiedad repercute en otro sitio: todo lo que dependa de /NeedAppearances no puede cumplir PDF/A. Basta un campo de entrada para que veraPDF suspenda el archivo en la cláusula 6.3.3, «An annotation does not contain an appearance dictionary» (la página de PDF/A lo detalla).

Sumado todo, las razones para elegir un formulario PDF se estrechan bastante. Para validación o scripting existen insdljs y eforms de AcroTeX, pero por mucho que construyas encima no podrás garantizar que funcione en el visor del destinatario. Si solo quieres recoger respuestas en línea, la conclusión honesta es que un formulario web es más fiable y más rápido de construir. Donde un formulario PDF sí encaja es en un impreso pensado para repartirse en papel, que el destinatario resulta rellenar en el ordenador antes de imprimirlo o guardarlo como PDF, es decir, un caso en el que la función de envío no se usa nunca. Para ese uso, tener casillas escribibles es realmente útil, y combinarlas con campos fijados por readonly da una plantilla estable.