El API de CakePHP: FormHelper::input


De una discusión del grupo CakePHP-esp me ha surgido la idea para este post (y dependiendo de la audiencia, podría convertirlo en una serie).

CakePHP 1.2 presenta, en su helper Form, una función muy poderosa para crear los campos de un formulario.
function input($fieldName, $options = array())

El primer parámetro de esta función debe ser el nombre del campo de la tabla que deseamos solicitar al usuario. Por ejemplo:

Teniendo una tabla person con un campo name VARCHAR(140) NOT NULL
echo $form->input("name");

Generará un campo input de tipo texto cuya longitud máxima es 140 y será requerido.

Ahora bién, toda ese conocimiento lo saca Cake de la base de datos. Sin embargo, la función ofrece al desarrollador un el segundo parámetro con el cual modificar el resultado. El parámetro $options, el cual debe ser un arreglo asociativo (los índices son strings):

  • type – permite modificar el tipo de campo a crear, los valores para este índice pueden ser: checkbox, radio, text, password, file, select, time, date, datetime y textarea

    • Si no se indica, CakePHP trata de adivinarlo a partir de la definición del campo en la base de datos.

    • Si no se indica y el nombre del campo es psword, passwd, o password, type será password.

    • Si en el controlador se hace una llamada a Controller::set con una variable cuyo nombre sea el plural del campo, cake utilizará type=’select’ (se puede forzar a que sea ‘radio’).
      Por ejemplo:
      //Controlador:
      $this->set("names", array("nombre", "nombre 1"));
      // Vista:
      echo $form->input("name");
      echo $form->input("name", array("type" => "radio"));

  • options – arreglo de pares para popular campos de seleccion (select, checkbox y radio). Si este campo se indica pero type no, entonces será ’select’. El ejemplo anterior, se puede hacer sin modificar el controlador, de la siguiente manera:
    // Vista:
    echo $form->input("name",
    array(
    "type" => "select", // también sirve "radio"
    "options" => array("nombre", "nombre1")
    )
    );

  • maxlength – este campo permite limitar el número de caracteres que puede insertar el usuario en el campo (por supuesto, sólo es válido si type es ‘input’).

  • timeFormat – permite definir el formato en el que se introducirá el tiempo (campos de tipo ‘time’ o ‘datetime’ sólamente).

    • Los valores posibles son 24, 12 o NONE

  • dateFormat – permite definir el formato en el que se introducirán las fechas (campos de tipo ‘datetime’ y ‘date’ sólamente)

    • Los valores posbiles DMY, MDY, YMD o NONE

  • selected – opción (el valor, no el texto visible) pre-seleccionada (sólo en campos de tipo ’select’).

    • Los campos de tipo ‘date’, ‘datetime’ y ‘time’ también aceptan este índice. El valor debe expresarse en formato estandar de fechas: ‘Y-m-d’, ‘Y-m-d H:M:S’ o ‘H:M:S’

    • Para fechas y tiempos, selected puede ser un arreglo asociativo. Los índices válidos son: day, month, year, hours, minutes, seconds y meridian (am o pm)

  • multiple – sólo para campos select. Indica si es un select mútiple o no (true, false).

    • Si el select es múltiple, selected puede ser un arreglo con varias entradas para cada valor seleccionado)

  • empty – sólo para campos select. Indica si el select tendrá un primer valor vacío.

  • label – permite al desarrollador seleccionar el texto que identifica al campo.

    • El valor de este índice también puede ser un arreglo asociativo cuyos índices pueden ser: text y otros atributos html propios del tag label (for, class, id, style, etc).

  • div - permite definir las características del div que rodea al input y al label.

    • Si se indica false, cake no crea el div.

    • Si se indica un string, se selecciona como valor del atributo class (en lugar de type que se usa normalmente).

    • Si es un un arreglo asociativo, se admiten los siguientes índices:

      • class -  sustituye en el atributo class el valor por defecto (type).

      • tag – nombre del tag a usar en lugar de div (p, span, etc…)

      • otros atributos html para el div.

  • id – atributo id del input. Cake cambia automáticamente el atributo for del label.

    • Utilizar algo distinto a un string es malo para la accesibilidad ya que hace que el atributo for del label falle.

  • before – texto que aparecerá antes del label

  • between – texto que aparecerá después del label.

  • after – texto que aparecerá después del input.

Esas son todas los parámetros que pude detectar luego de ver por un ráto el tan temido API de CakePHP. Si encuentras que algún  dato es incorrecto notificamelo en los comentarios.

Si te pareció interesante esta entrada y te gustaría que haga una serie, deja un comentario también indicando qué funciones te parecen interesantes.

Entradas que pueden interesarte