Clase HtmlForm para PHP

[dec]


A ver qué os parece la siguiente clase que pretende servir para "definir" e "imprimir" formularios HTML, así como, hasta cierto punto, procesar los resultados luego de que el usuario envíe dicho formulario HTML. En efecto, la clase "HtmlForm" para PHP pretende servir para una de las dos cosas mencionadas o para ambas dos.

La clase "HtmlForm" es realmente sencilla y su utilización es muy intuitiva en mi opinión, aunque también tengo ciertas razones que luego se echarán de ver. En principio está pensada para que una aplicación pueda "dar salida" o imprimir formularios HTML partiendo de una "definición" escrita en PHP.

De este modo, cualquiera desde PHP (un plugin de la aplicación, por ejemplo) podrá añadir elementos al formulario, definiéndolos previamente, antes de que el propio HTML del formulario sea impreso por ver primera. Una vez se define un formulario es posible imprimir su HTML, recuperar este (sin imprimirlo) y, opcionalmente, comprobar si el formulario ha sido "enviado" y, por lo tanto, podemos trabajar con sus "valores".


Primera parte: definiendo el formulario

La clase es muy sencilla en todo caso, también a la hora de utilizarla, como decía. Y es que la definición de un formulario, como ahora verás, es en mi opinión lo suficientemente intuitiva como para no perderse en ella. De hecho, si alguna vez has escrito un formulario HTML, sabrás enseguida definirlo con HtmlForm. E incluso podrás utilizar los nuevos "input" de HTML 5, sencillamente, como luego se verá.

Fijáos en el siguiente código fuente:

Código PHP:

require( './classes/htmlform.php' );

$definition = array
(
  array
  (
    'name' => 'userlogin'
  ),
  array
  (
    array( 'type' => 'text', 'name' => 'login' ),
    array( 'name' => 'password', 'type' => 'password' ),
    array( 'type' => 'submit', 'value' => 'Login now!' )
  )
);

$form = new HtmlForm( $definition );

$form->Html();

if( $form->Submitted() )
{
  if( $form->login != '' && $form->password != '' )
  {
    printf
    (
      'Your login is: <b>%s</b> and your password: <b>%s</b>? Hurray!',
      $form->login,
      $form->password
    );
  }
} 


Vamos a repasarlo de forma pormenorizada. Obviando el requerimiento de la clase HtmlForm (que acaso podría evitarse si utilizas algún tipo de "autoload" gracias a PHP 5.x) lo primero que vemos es, precisamente, la definición de un formulario. Como ves, dicha definición es un "Array" que contiene dos elementos, que a su vez son Arrays.

O sea, la definición es un Array de dos elementos que a su vez son Arrays. ¿Complicado? Verás como no, como al menos te parece más o menos razonable,... o eso me parece a mí. El primer elemento define las propiedades del formulario. Luego entraremos en detalles. El segundo elemento, por su parte, define todos los elementos del formulario.

Más concretamente, el primer elemento de la definición de un formulario, el primer Array contiene los atributos que serán añadidos a la etiqueta HTML "form", y, además, opcionalmente, puede contener otras "atributos", que, en realidad no se incluirán en la etiqueta "form". Por eso he dado en llamar a este primer Array "propiedades" del formulario y no atributos, porque, las primeras incluyen a los segundos.

No te asustes. En realidad sólo hay un par propiedades que no sean atributos. En el ejemplo de arriba no hemos incluida ninguna, porque, además son opcionales. Si volvemos al ejemplo de arriba vemos que las propiedades del formulario se definen así:

Código PHP:

  array
  (
    'name' => 'userlogin'
  ), 


En efecto, el único atributo obligatorio es "name", todos los demás son opcionales, y, en este caso, lo que al cabo se obtendría sería una etiqueta HTML "form" tal que así:

Código PHP:

 <form name="userlogin" method="post"> 


Como ves, si no indicas el atributo "method" el valor "post" se utiliza por defecto. Pero a lo que íbamos. Si quieres puedes añadir más atributos, más propiedades del formulario: en realidad puedes utilizar todos los atributos válidos para dicha etiqueta, incluso "inválidos", puesto que la clase HtmlForm no se dedica a comprobar su valided.

Dicho esto, hemos comentado que hay atributos/propiedades que no se incluirán en la etiqueta HTML form. Estas propiedades son: "wrap", "markup" y "legend". ¡Ya te dije que no eran pocos! El primero de ellos puede especificar una etiqueta HTML que se utilizará para "envolver" a los elementos del formulario.

Esto último es obligatorio si pretendes que tus documento XHTML "validen". Pero no tendrás que preocuparte, si no quieres, puesto que por defecto los elementos se envuelven en un "div", pero, tú puedes cambiar esto por otras etiquetas como "p", e incluso especificar una "cadena vacía", de manera que se "fuerze" la no utilización de ningún "envoltorio".

La propiedad "markup" que puedes utilizar determina el tipo de "final" para los "inputs" del formulario. Si "markup" no está presente en la definición del formulario se utilizará el "final" conforme al lenguaje XHTML. Si "markup" está presente y vale "html" se usará HTML para el final de las etiquetas "inputs".

Código PHP:


# Sin "markup", por defecto

<input type="text" name="login" />

# Con "markup = html"

<input type="text" name="login"> 


Esta última propiedad debes usarla para adaptar el HTML del formulario al del documento que lo incluya, como podrás imaginar. Y al fin tenemos la última propiedad (que no atributo) opcional en la definición de las propiedades del formulario, la propiedad "legend". Por defecto HtmlForm encierra los elementos del formulario en una etiqueta "fieldset", pues bien, si usas la propiedad "legend" también se incluirá también dicha etiqueta al principio del "fieldset".

Y eso es todo lo que se tiene que decir para la versión actual de HtmlForm en lo que respecta a la definición de las propiedades del formulario. ¿Parece mucho? Pero recuerda que sólo el atributo "name" es obligatorio... puesto que el formulario ha de tener un nombre: todos los demás atributos y propiedades son opcionales. ¡Pero lo mejor es que puedes añadir cuantos atributos te sean necesarios!

El segundo Array de la definición de un formulario, tal como dijimos arriba, contiene todos los elementos que puede albergar un formulario. ¿Todos? En principio así es. Incluso puedes utilizar los "inputs" de HTML 5, ya disponibles en algunos navegadores, y, sin miedo, puesto que, de no estar disponibles, todos ellos "degradan" como "inputs" de tipo "texto", o sea que no hay problema alguno.

Pero no sólo pueden incluirse todos los "inputs" de tipo "text", "password", "hidden", "button", "submit", "reset", "image", "email", "tel", "date", "datetime", "range", etc. Por supuesto, también es posible incluir "textareas" y "selects", aunque, para esto últimos aún no se soportan los "grupos de opciones", simplemente "opciones".

Todos los elementos del formulario se definen de igual forma, básicamente, indicando su "tipo" en su definición. Para el caso de los "textareas" y los "selects" habrá que indicar como tipo "textarea" y "select", respectivamente, luego veremos cómo se añaden las opciones a estos últimos "inputs". De momento y siguiendo con el ejemplo de arriba veíamos definidos estos "inputs" o elementos para el formulario:

Código PHP:

  array
  (
    array( 'type' => 'text', 'name' => 'login' ),
    array( 'type' => 'password', 'name' => 'password' ),
    array( 'type' => 'submit', 'value' => 'Login now!' )
  ) 


Como puedes ver se definene tres elementos, un "text", un "password" y un botón "submit". Y como puedes ver se trata de añadir Arrays con "propiedades" (en el mismo sentido que hablamos más arriba para la definición de las propiedades del fomulario) en este caso para cada elemento. La única propiedad obligatoria es "type", aunque se entiende que si no proporcionas un "name" para el elemento sus valores no serán enviados con el formulario.

¡Puedes añadir tantos atributos o propiedades como quieras! Todos los que sean válidos para los diferentes "inputs", "title", "class", "value", "min", "max", "required", "multiple"... simplemente añádelos en la definición de los elementos. Obviamente los "textareas" pueden contar con atributos "cols" y el resto de "inputs" no, pero, la clase HtmlForm no se preocupa de esto, en otras palabras, confía en tu saber hacer en este sentido.

Como en el caso de las propiedades del formulario, existen unas cuentas propiedades opcionales para los elementos, que, como ya sabes, de cualquier modo no serán "impresas" en las etiquetas HTML correspondientes. Estas propiedades son dos, de momento: "wrap" y "legend" y no vamos a repetir ahora para qué sirven y pueden utilizarse puesto que las hemos podido ver más arriba, ¿verdad? Pues eso.

Huelga decir que un formulario puede contener cuantos elementos o "inputs" sean necesarios. Hemos comentado que también pueden incluirse "selects". Añadiremos ahora que también es posible añadir "inputs" del tipo "file" sin problemas. Para estos últimos no hay mucho que decir (se definen como cualquier otro elemento), salvo que de utilizar alguno las propiedades del formulario han de incluir un "enctype" tal que "multipart/form-data", por ejemplo. De lo contrario el valor de "file" no nos llegará tal como esperamos.

Pero, ¿qué pasa con los "inputs" de tipo "select"? Son los únicos que tienen cierta característica especial: pueden y aun deben contener "opciones". ¿Y cómo se define un elemento de este tipo? Muy sencillamente, como verás, tal como cualquier otro elemento, pero, añadiendo las opciones necesarias:

Código PHP:

  array
  (
    array
    ( 
      'type' => 'select', 
      'name' => 'color',
      'options' => array
      (
        array( 'value' => 'red', 'text' => 'Red color ),
        array( 'value' => 'blue', 'text' => 'Blue color )        
      )
    )
  ) 


¡Eso sería todo! Pero vamos a descubrir un par de cosas aquí. En primer lugar podemos observar que cada "option" es un Array tal que cualquier otro elemento del formulario, puede contener atributos y propiedades. ¿Qué atributos? Cualquiera que necesites. ¿Qué propiedades? Sólo "text", y acaso obligatoria, puesto que su valor se incluirá entre las etiquetas "option": será lo que el usuario vea para seleccionar un color, en este caso, "Red color" o "Blue color".

Cabe añadir que pueden añadirse "selects múltiples" sin problema tal que así:

Código PHP:

  array
  (
    array
    ( 
      'type' => 'select', 
      'name' => 'color[]',
      'multiple' => 'multiple',
      'options' => array
      (
        array( 'value' => 'red', 'text' => 'Red color ),
        array( 'value' => 'blue', 'text' => 'Blue color )        
      )
    )
  ) 


Como ves hemos añadido unos corchetes al "name" del elemento y el atributo "multiple". El usuario podrá elegir varios elementos de la lista de una vez y lo que nosotros obtendremos será un Array con los elementos escogidos en la variable "color", en este caso, y por supuesto luego de procesarse el formulario. ¡Y mira! ¡De eso vamos a tratar justo a continuación!


Segunda parte: procesando el formulario

Sólo teniendo en cuenta lo que se ha explicado en la primera parte de este texto ya podríamos dar algún juego a la clase HtmlForm. Y es que como dije al principio HtmlForm persigue dos objetivos separados: la definición e impresión de un formulario HTML y su posterior, pero, opcinal procesamiento. Ahora vamos a tratar de este asunto, ¡y verás como es muy sencillo! Además te prometo algo más de brevedad. ;-)

Veamos un momento de nuevo el código de ejemplo escribí más arriba:

Código PHP:

require( './classes/htmlform.php' );

$definition = array
(
  array
  (
    'name' => 'userlogin'
  ),
  array
  (
    array( 'type' => 'text', 'name' => 'login' ),
    array( 'name' => 'password', 'type' => 'password' ),
    array( 'type' => 'submit', 'value' => 'Login now!' )
  )
);

$form = new HtmlForm( $definition );

$form->Html();

if( $form->Submitted() )
{
  if( $form->login != '' && $form->password != '' )
  {
    printf
    (
      'Your login is: <b>%s</b> and your password: <b>%s</b>? Hurray!',
      $form->login,
      $form->password
    );
  }
} 


Centrémonos ahora justo después de la definición del formulario y de sus elementos. Es ahí cuando creamos un objeto de la clase "HtmlForm", pasándole como único argumento a su "constructor" el Array con la mencionada definición. Acto seguido, ¿qué hacemos? En este caso podemos ver que escribo "$form->Html()". Pues bien, de este modo estaremos imprimiendo el código HTML del formulario que acabamos de definir.

¿Es necesario hacerlo justo después de construir nuestro objeto "$form"? No; en absoluto. Piensa que, una vez definido el formulario, este puede ser procesado, es decir, podremos comprobar si ha sido "enviado" o no, y acceder a sus "valores" si es así, independientemente de que mostremos o no el HTML del formulario. Obviamente, si queremos que el usuario rellene el formulario tendremos que "presentárselo", pero, no es absolutamente obligatorio. Podemos o no hacerlo a nuestra voluntad.

Bien. ¿Qué hacemos después en el ejemplo de arriba? En efecto, ejecutamos otro método de "HtmlForm", "$form->Submitted()". Este método retorna un valor Booleano, True si el formulario ha sido ya enviado por el usuario, False en el caso de que no haya sido así. Ahora viene algo interesante. Observa qué hacemos cuando entramos en la condición, es decir, cuando conocemos que el formulario se ha enviado.

¡Podemos acceder a los valores de los elementos del formulario, directamente, como si fueran propiedades de nuestro objeto "form"! Esto es gracias a la magia de PHP y su método mágico "__get()" con el que cuenta "HtmlForm". En efecto, siguiendo con el ejemplo, comprobamos que el campo o elemento con nombre "login" tiene algún valor distinto de una "cadena vacía", simplemente, accediendo al mismo escribiendo "$form->login".

Pues bien, exactamente igual podremos acceder al resto de campos o elementos del formulario. Sin preocuparse de que la propiedad "login" esté definida, en este caso, puesto que en caso de no estarlo "login" tendrá un valor "nulo" sin más. Estas propiedades del objeto "$form", que representan a los valores de los elementos enviados en el formulario, pueden también "escribirse".

Esto significa que podríamos asignar un nuevo valor a "login", y lo haríamos al mismo tiempo tanto para el valor del elemento del formulario enviado, como para la propia definición del formulario, que se conserva. Quiere decirse que podrías cambiar el valor de "login", mejor dicho, darle un valor a "login", de forma que, si imprimes el HTML formulario, dicho elemento tendrá el valor que hayas establecido.

Todos los valores de los elementos del formulario pueden accederse como si fueran, por tanto, propiedades del objeto "$form", en el caso del ejemplo de que tratamos. Y también es posible utilizar "unset" con dichas propiedades, de manera que, a la vez, estés "borrando" el valor enviado junto al elemento del formulario, así como el propio elemento de la definición del formulario.


Conclusión

Creo que me he pasado con el rollo, porque, en efecto, ¡que me maten si esta clase HtmlForm es complicada de utilizar! Así que lo que ocurre es que no he sabido explicarme mejor, pero, junto con la clase incluyo algún que otro ejemplo de uso, y, la misma clase HtmlForm está profusamente documentada, o eso he intentado. Así que lo dejaré aquí, de momento, puesto que además tengo para mí que en los próximos días quisiera hacer algunos cambios... espero que sin romper la "compatibilidad" con lo ya explicado. ;-)

P.D. De veras que vuestros comentarios, sugerencias, críticas, puntualizaciones, etc., serán más que bienvenidas, también agradecidas.

P.D.2. Este texto se ha publicado a la vez en PHP-Hispano, pero, no he querido dejar de hacerlo aquí para comportar "HtmlForm" también con vosotros. Os pido por favor que descarguéis "HtmlForm" desde PHP-Hispano, de manera que, como pienso trabajar más en el "invento", pueda "actualizar" sólo en lugar. ¡Gracias!

[roman]

Hola dec,

Mira, mi opinión no puede ser muy objetiva porque no me convence eso de generar código html con php. Quizá para ciertos contextos específicos pueda servir, pero como algo de caracter general me parece que sería muy limitado. Claro que con CSS puedes controlar algo de la apariencia final del formulario pero aún así me parece que la estructura sería muy rígida. Desde luego, puedo estar equivocado.

Ahora bien, limitándonos al script en sí; de lo poco qe he visto y de lo que describes, creo que lo que sí es fundamental es que añadas soporte para los rótulos de los campos (igual y ya lo tienes, pero no lo he podido ver). También cambiaría el default del método, pues si el método por defecto en HTML es GET, creo que habría que respetarlo.

De todas maneras, pienso que la manipulación de los datos del formulario mediante propiedades de un objeto puede ser muy útil. La parte que no me cuadra es la de la definición en sí del formulario mediante código PHP.

// Saludos

[dec]

Hola,

Gracias por tus comentarios Román. En principio la clase está "pensada", precisamente, para obviar el HTML, pero, no por gusto, sino por una razón importante, sobre todo, cuando se trabaja con "plugins" que deben poder modificar el HTML. Se hace complicado, en fin, imprimir código HTML "por partes", puesto que unas partes no tienen conocimiento de lo que otras escriben, por ejemplo.

De ahí que sea útil poder definir el formulario sólo utilizando PHP. De este modo, por ejemplo, una parte (la aplicación principal) puede definir un formulario y pasar la definición a otras partes, quienes modrán modificar la definición del formulario, todo esto sin que el HTML aparezca para nada. Por supuesto, uno de los posibles inconvenientes (no todo pueden ser ventajas) es la posible rigidez de los formularios.

De momento sí que es posible añadir "labels" a los elementos del formulario. Luego, con CSS, podría controlarse su estilo, por no decir que cada elemento puede tener su atributo "style". Pero pueden tener atributos "id" y "class" si se precisa. Ya digo, el objetivo, completado hasta cierto punto o no, es poder trabajar con la "definición" de un formulario, toda ella en PHP, antes de que al cabo se imprima el código HTML del mismo.

De todas formas se trata de una primera aproximación al problema. Mejor dicho, llevé a cabo algún que otro intento anterior pero no funcionaron como este último. Cabría todavía añadir a la clase "HtmlForm" algunos métodos útiles, por ejemplo, para dar la posiblidad de "resituar" los elementos en la definición y alguna que otra cosilla más. Espero que se entienda el objetivo, puesto que se tiene que entender el problema de trabajar con HTML "por partes".

[dec]

Hola,

Me gustaría añadir algo más. Concretamente, los problemas que he mencionado para trabajar con HTML "por partes" los he podido "ver" en Gesbit. La clase "HtmlForm" no está basada en, pero, hasta cierto punto me la inspiró cierta clase similar que existe en el proyecto Habari. En efecto, este proyecto utiliza una clase "UIForm" (creo recordar) con la que se construyen los formularios del panel de administración de la aplicación.

Pues bien, el objeto "form" va pasando de plugin en plugin, de manera que cada uno puede trabajar con el mismo. Es cierto que los formularios del panel de administración de Habari se ven un poco,... como tú has dicho..."rígidos". Sin embargo, como he dicho arriba, no todo pueden ser ventajas, pero en Habari han pensado que estas son mayores que los inconvenientes. Desde luego yo en Gesbit sí he podido ver el problema de trabajar con HTML "por partes", pero, no sé si he conseguido dejar claro este "concepto".

P.D. En pocas palabras, de hecho los formularios de Habari se construyen con ayuda del objeto "form", los plugins, la propia base de datos... es una gozada, porque, todo es algo abstracto, pero,... funciona.

[dec]

Hola,

Acabo de hacer una actualización sencilla a la par que potente y me gustaría comentarla aquí. Para acceder al valor de un elemento de un formulario luego de que este sea enviado, ya no basta con escribir algo como: "$form->login". Ahora, para acceder al valor del elemento "login" ha de escribirse esto: "$form->login->Value()".

Por el momento sólo existen los métodos "IsEmpty()" y "Value()", pero, es claro que podrán añadirse más en el futuro, por ejemplo, "IsInteger()", "IsString()", etc., etc, de ahí que antes hablase de que se trata de una solución sencilla y potente al mismo tiempo. Bueno, sobre todo que cambia la forma de hacer las cosas tal como las expliqué ayer, por eso he querido comentar esta actualización.

[[movorack]]

hasta ahora no lo he leido mucho... mañana le echo ojo... pero dime algo... ¿la clase permitiria implementar javascript para el formulario en si y/o para los elementos del formulario?... si se puede implementar javascript, ¿da soporte a frameworks?... si se implementara el javascript (independiente del framework) ¿permite AJAX?... los pocesamientos se deben hacer al recargar la pagina (desventaja php) o ¿se pueden hacer asincronos?...

perdona que solo me halla enfocado en esto pero como sabes ahora para los formularios el javascript es full necesario a la hora de validar y evitar perdidas de tiempo en recargas completas de la pagina.

de todos modos... mañana miro a ver...