Elementos de formulario

Resumen de los elementos de formulario estándar.

addText (string|int $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Agrega un campo de texto de una línea (clase TextInput). Si el usuario no rellena el campo, devuelve una cadena vacía '', o mediante setNullable() se puede especificar que devuelva null.

$form->addText('name', 'Nombre:')
	->setRequired()
	->setNullable();

Valida automáticamente UTF-8, recorta los espacios iniciales y finales y elimina los saltos de línea que un atacante podría enviar.

La longitud máxima se puede limitar mediante setMaxLength(). Modificar el valor introducido por el usuario permite addFilter().

Mediante setHtmlType() se puede cambiar el carácter visual del campo de texto a tipos como search, tel o url ver especificación. Recuerde que el cambio de tipo es solo visual y no reemplaza la función de validación. Para el tipo url es conveniente agregar una regla de validación específica URL.

Para otros tipos de entradas, como number, range, email, date, datetime-local, time y color, utilice métodos especializados como addInteger, addFloat, addEmail addDate, addTime, addDateTime y addColor, que aseguran la validación del lado del servidor. Los tipos month y week aún no son totalmente compatibles con todos los navegadores.

Al elemento se le puede establecer el llamado empty-value, que es algo así como un valor predeterminado, pero si el usuario no lo cambia, el elemento devuelve una cadena vacía o null.

$form->addText('phone', 'Teléfono:')
	->setHtmlType('tel')
	->setEmptyValue('+34');

addTextArea (string|int $name, $label=null): TextArea

Agrega un campo para introducir texto multilínea (clase TextArea). Si el usuario no rellena el campo, devuelve una cadena vacía '', o mediante setNullable() se puede especificar que devuelva null.

$form->addTextArea('note', 'Nota:')
	->addRule($form::MaxLength, 'La nota es demasiado larga', 10000);

Valida automáticamente UTF-8 y normaliza los separadores de línea a \n. A diferencia del campo de entrada de una sola línea, no se realiza ningún recorte de espacios.

La longitud máxima se puede limitar mediante setMaxLength(). Modificar el valor introducido por el usuario permite addFilter(). Se puede establecer el llamado empty-value mediante setEmptyValue().

addInteger (string|int $name, $label=null): TextInput

Agrega un campo para introducir un número entero (clase TextInput). Devuelve un integer, o null si el usuario no introduce nada.

$form->addInteger('year', 'Año:')
	->addRule($form::Range, 'El año debe estar en el rango de %d a %d.', [1900, 2023]);

El elemento se renderiza como <input type="number">. Usando el método setHtmlType() se puede cambiar el tipo a range para mostrarlo como un control deslizante, o a text, si prefiere un campo de texto estándar sin el comportamiento especial del tipo number.

addFloat (string|int $name, $label=null): TextInput

Agrega un campo para introducir un número decimal (clase TextInput). Devuelve un float, o null si el usuario no introduce nada.

$form->addFloat('level', 'Nivel:')
	->setDefaultValue(0)
	->addRule($form::Range, 'El nivel debe estar en el rango de %d a %d.', [0, 100]);

Nette y el navegador Chrome aceptan tanto la coma como el punto como separador decimal. Para que esta funcionalidad esté disponible también en Firefox, se recomienda establecer el atributo lang ya sea para el elemento dado o para toda la página, por ejemplo <html lang="es">.

addEmail (string|int $name, $label=null, int $maxLength=255): TextInput

Agrega un campo para introducir una dirección de correo electrónico (clase TextInput). Si el usuario no rellena el campo, devuelve una cadena vacía '', o mediante setNullable() se puede especificar que devuelva null.

$form->addEmail('email', 'E-mail:');

Verifica si el valor es una dirección de correo electrónico válida. No se verifica si el dominio realmente existe, solo se verifica la sintaxis. Valida automáticamente UTF-8, recorta los espacios iniciales y finales.

addPassword (string|int $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Agrega un campo para introducir una contraseña (clase TextInput).

$form->addPassword('password', 'Contraseña:')
	->setRequired()
	->addRule($form::MinLength, 'La contraseña debe tener al menos %d caracteres', 8)
	->addRule($form::Pattern, 'Debe contener un dígito', '.*[0-9].*');

Al volver a mostrar el formulario, el campo estará vacío. Valida automáticamente UTF-8, recorta los espacios iniciales y finales y elimina los saltos de línea que un atacante podría enviar.

addCheckbox (string|int $name, $caption=null): Checkbox

Agrega una casilla de verificación (clase Checkbox). Devuelve el valor true o false, dependiendo de si está marcada.

$form->addCheckbox('agree', 'Acepto los términos y condiciones')
	->setRequired('Es necesario aceptar los términos y condiciones');

addCheckboxList (string|int $name, $label=null, ?array $items=null): CheckboxList

Agrega casillas de verificación para seleccionar múltiples elementos (clase CheckboxList). Devuelve un array de claves de los elementos seleccionados. El método getSelectedItems() devuelve los valores en lugar de las claves.

$form->addCheckboxList('colors', 'Colores:', [
	'r' => 'rojo',
	'g' => 'verde',
	'b' => 'azul',
]);

El array de elementos ofrecidos se pasa como tercer parámetro o mediante el método setItems().

Mediante setDisabled(['r', 'g']) se pueden desactivar elementos individuales.

El elemento comprueba automáticamente que no haya habido falsificación y que los elementos seleccionados sean realmente uno de los ofrecidos y no hayan sido desactivados. Mediante el método getRawValue() se pueden obtener los elementos enviados sin esta importante comprobación.

Al establecer los elementos seleccionados por defecto, también comprueba que sean uno de los ofrecidos, de lo contrario lanza una excepción. Esta comprobación se puede desactivar mediante checkDefaultValue(false).

Si envía el formulario mediante el método GET, puede elegir un método de transmisión de datos más compacto que ahorra tamaño de la cadena de consulta. Se activa estableciendo el atributo HTML del formulario:

$form->setHtmlAttribute('data-nette-compact');

addRadioList (string|int $name, $label=null, ?array $items=null): RadioList

Agrega botones de opción (clase RadioList). Devuelve la clave del elemento seleccionado, o null si el usuario no seleccionó nada. El método getSelectedItem() devuelve el valor en lugar de la clave.

$sex = [
	'm' => 'hombre',
	'f' => 'mujer',
];
$form->addRadioList('gender', 'Género:', $sex);

El array de elementos ofrecidos se pasa como tercer parámetro o mediante el método setItems().

Mediante setDisabled(['m', 'f']) se pueden desactivar elementos individuales.

El elemento comprueba automáticamente que no haya habido falsificación y que el elemento seleccionado sea realmente uno de los ofrecidos y no haya sido desactivado. Mediante el método getRawValue() se puede obtener el elemento enviado sin esta importante comprobación.

Al establecer el elemento seleccionado por defecto, también comprueba que sea uno de los ofrecidos, de lo contrario lanza una excepción. Esta comprobación se puede desactivar mediante checkDefaultValue(false).

addSelect (string|int $name, $label=null, ?array $items=null, ?int $size=null): SelectBox

Agrega un cuadro de selección (clase SelectBox). Devuelve la clave del elemento seleccionado, o null si el usuario no seleccionó nada. El método getSelectedItem() devuelve el valor en lugar de la clave.

$countries = [
	'ES' => 'España',
	'MX' => 'México',
	'AR' => 'Argentina',
];

$form->addSelect('country', 'País:', $countries)
	->setDefaultValue('MX');

El array de elementos ofrecidos se pasa como tercer parámetro o mediante el método setItems(). Los elementos también pueden ser un array bidimensional:

$countries = [
	'Europa' => [
		'ES' => 'España',
		'FR' => 'Francia',
		'DE' => 'Alemania',
	],
	'CA' => 'Canadá',
	'MX' => 'México',
	'?'  => 'otro',
];

En los cuadros de selección, a menudo el primer elemento tiene un significado especial, sirve como llamada a la acción. Para agregar tal elemento, se utiliza el método setPrompt().

$form->addSelect('country', 'País:', $countries)
	->setPrompt('Seleccione un país');

Mediante setDisabled(['ES', 'FR']) se pueden desactivar elementos individuales.

addMultiSelect (string|int $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox

Agrega un cuadro de selección para elegir múltiples elementos (clase MultiSelectBox). Devuelve un array de claves de los elementos seleccionados. El método getSelectedItems() devuelve los valores en lugar de las claves.

$form->addMultiSelect('countries', 'Países:', $countries);

El array de elementos ofrecidos se pasa como tercer parámetro o mediante el método setItems(). Los elementos también pueden ser un array bidimensional.

Mediante setDisabled(['ES', 'FR']) se pueden desactivar elementos individuales.

addUpload (string|int $name, $label=null): UploadControl

Agrega un campo para subir un archivo (clase UploadControl). Devuelve un objeto FileUpload incluso si el usuario no envió ningún archivo, lo cual se puede verificar con el método FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'El avatar debe ser JPEG, PNG, GIF, WebP o AVIF.')
	->addRule($form::MaxFileSize, 'El tamaño máximo es 1 MB.', 1024 * 1024);

Si el archivo no se sube correctamente, el formulario no se envía con éxito y se muestra un error. Es decir, en caso de envío exitoso, no es necesario verificar el método FileUpload::isOk().

Nunca confíe en el nombre original del archivo devuelto por el método FileUpload::getName(), el cliente podría haber enviado un nombre de archivo malicioso con la intención de dañar o hackear su aplicación.

Las reglas MimeType e Image detectan el tipo requerido basándose en la firma del archivo y no verifican su integridad. Si la imagen está dañada se puede verificar, por ejemplo, intentando cargarla.

addMultiUpload (string|int $name, $label=null): UploadControl

Agrega un campo para subir múltiples archivos a la vez (clase UploadControl). Devuelve un array de objetos FileUpload. El método FileUpload::hasFile() en cada uno de ellos devolverá true.

$form->addMultiUpload('files', 'Archivos:')
	->addRule($form::MaxLength, 'Se pueden subir como máximo %d archivos', 10);

Si alguno de los archivos no se sube correctamente, el formulario no se envía con éxito y se muestra un error. Es decir, en caso de envío exitoso, no es necesario verificar el método FileUpload::isOk().

Nunca confíe en los nombres originales de los archivos devueltos por el método FileUpload::getName(), el cliente podría haber enviado un nombre de archivo malicioso con la intención de dañar o hackear su aplicación.

addDate (string|int $name, $label=null): DateTimeControl

Agrega un campo que permite al usuario introducir fácilmente una fecha compuesta por año, mes y día (clase DateTimeControl).

Como valor predeterminado, acepta objetos que implementan la interfaz DateTimeInterface, una cadena con la hora o un número que representa un timestamp UNIX. Lo mismo se aplica a los argumentos de las reglas Min, Max o Range, que definen la fecha mínima y máxima permitida.

$form->addDate('date', 'Fecha:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'La fecha debe tener al menos un mes de antigüedad.', new DateTime('-1 month'));

Por defecto, devuelve un objeto DateTimeImmutable, con el método setFormat() puede especificar el formato de texto o timestamp:

$form->addDate('date', 'Fecha:')
	->setFormat('Y-m-d');

addTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Agrega un campo que permite al usuario introducir fácilmente una hora compuesta por horas, minutos y opcionalmente segundos (clase DateTimeControl).

Como valor predeterminado, acepta objetos que implementan la interfaz DateTimeInterface, una cadena con la hora o un número que representa un timestamp UNIX. De estas entradas, solo se utiliza la información de la hora, la fecha se ignora. Lo mismo se aplica a los argumentos de las reglas Min, Max o Range, que definen la hora mínima y máxima permitida. Si el valor mínimo establecido es mayor que el máximo, se crea un rango de tiempo que cruza la medianoche.

$form->addTime('time', 'Hora:', withSeconds: true)
	->addRule($form::Range, 'La hora debe estar en el rango de %d a %d.', ['12:30', '13:30']);

Por defecto, devuelve un objeto DateTimeImmutable (con la fecha 1 de enero del año 1), con el método setFormat() puede especificar el formato de texto:

$form->addTime('time', 'Hora:')
	->setFormat('H:i');

addDateTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Agrega un campo que permite al usuario introducir fácilmente una fecha y hora compuesta por año, mes, día, horas, minutos y opcionalmente segundos (clase DateTimeControl).

$form->addDateTime('datetime', 'Fecha y hora:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'La fecha debe tener al menos un mes de antigüedad.', new DateTime('-1 month'));

Por defecto, devuelve un objeto DateTimeImmutable, con el método setFormat() puede especificar el formato de texto o timestamp:

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor (string|int $name, $label=null): ColorPicker

Agrega un campo para seleccionar un color (clase ColorPicker). El color es una cadena en formato #rrggbb. Si el usuario no realiza la selección, se devuelve el color negro #000000.

$form->addColor('color', 'Color:')
	->setDefaultValue('#3C8ED7');

addHidden (string|int $name, ?string $default=null): HiddenField

Agrega un campo oculto (clase HiddenField).

$form->addHidden('userid');

Mediante setNullable() se puede establecer que devuelva null en lugar de una cadena vacía. Modificar el valor enviado permite addFilter().

Aunque el elemento está oculto, es importante tener en cuenta que el valor aún puede ser modificado o falsificado por un atacante. Siempre verifique y valide minuciosamente todos los valores recibidos en el lado del servidor para prevenir riesgos de seguridad asociados con la manipulación de datos.

addSubmit (string|int $name, $caption=null): SubmitButton

Agrega un botón de envío (clase SubmitButton).

$form->addSubmit('submit', 'Enviar');

En el formulario es posible tener múltiples botones de envío:

$form->addSubmit('register', 'Registrar');
$form->addSubmit('cancel', 'Cancelar');

Para determinar en cuál de ellos se hizo clic, use:

if ($form['register']->isSubmittedBy()) {
  // ...
}

Si no desea validar todo el formulario al presionar un botón (por ejemplo, en los botones Cancelar o Vista previa), use setValidationScope().

addButton (string|int $name, $caption): Button

Agrega un botón (clase Button) que no tiene función de envío. Por lo tanto, se puede usar para alguna otra función, por ejemplo, llamar a una función JavaScript al hacer clic.

$form->addButton('raise', 'Aumentar salario')
	->setHtmlAttribute('onclick', 'raiseSalary()');

addImageButton (string|int $name, ?string $src=null, ?string $alt=null): ImageButton

Agrega un botón de envío en forma de imagen (clase ImageButton).

$form->addImageButton('submit', '/ruta/a/imagen.png');

Al usar múltiples botones de envío, se puede determinar en cuál se hizo clic mediante $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Agrega un subformulario (clase Container), o contenedor, al que se pueden agregar otros elementos de la misma manera que los agregamos al formulario. También funcionan los métodos setDefaults() o getValues().

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Su nombre:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Su nombre:');
$sub2->addEmail('email', 'Email:');

Los datos enviados se devuelven como una estructura multidimensional:

[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]

Resumen de configuración

En todos los elementos podemos llamar a los siguientes métodos (resumen completo en la documentación de la API):

`setDefaultValue($value)`	establece el valor predeterminado
`getValue()`	obtener el valor actual
`setOmitted()`	Omisión de valor
`setDisabled()`	Desactivación de elementos

Renderizado:

`setCaption($caption)`	cambia la etiqueta del elemento
`setTranslator($translator)`	establece el traductor
`setHtmlAttribute($name, $value)`	establece el atributo HTML del elemento
`setHtmlId($id)`	establece el atributo HTML `id`
`setHtmlType($type)`	establece el atributo HTML `type`
`setHtmlName($name)`	establece el atributo HTML `name`
`setOption($key, $value)`	configuración para renderizado

Validación:

`setRequired()`	elemento obligatorio
`addRule()`	establece la regla de validación
`addCondition()`, `addConditionOn()`	establece la condición de validación
`addError($message)`	entrega de mensaje de error

En los elementos addText(), addPassword(), addTextArea(), addEmail(), addInteger() se pueden llamar los siguientes métodos:

`setNullable()`	establece si getValue() devolverá `null` en lugar de una cadena vacía
`setEmptyValue($value)`	establece un valor especial que se considera una cadena vacía
`setMaxLength($length)`	establece el número máximo de caracteres permitidos
`addFilter($filter)`	modificación de entrada

Omisión de valor

Si el valor rellenado por el usuario no nos interesa, podemos omitirlo del resultado del método $form->getValues() o de los datos pasados a los handlers mediante setOmitted(). Esto es útil para diversas contraseñas de verificación, elementos antispam, etc.

$form->addPassword('passwordVerify', 'Contraseña para verificación:')
	->setRequired('Por favor, introduzca la contraseña de nuevo para verificar')
	->addRule($form::Equal, 'Las contraseñas no coinciden', $form['password'])
	->setOmitted();

Desactivación de elementos

Los elementos se pueden desactivar mediante setDisabled(). Tal elemento no puede ser editado por el usuario.

$form->addText('username', 'Nombre de usuario:')
	->setDisabled();

Los elementos deshabilitados no son enviados por el navegador al servidor, por lo tanto, tampoco los encontrará en los datos devueltos por la función $form->getValues(). Sin embargo, si establece setOmitted(false), Nette incluirá su valor predeterminado en estos datos.

Al llamar a setDisabled(), por razones de seguridad, se borra el valor del elemento. Si establece un valor predeterminado, es necesario hacerlo después de desactivarlo:

$form->addText('username', 'Nombre de usuario:')
	->setDisabled()
	->setDefaultValue($userName);

Una alternativa a los elementos deshabilitados son los elementos con el atributo HTML readonly, que el navegador sí envía al servidor. Aunque el elemento es solo de lectura, es importante tener en cuenta que su valor aún puede ser modificado o falsificado por un atacante.

Elementos personalizados

Además de la amplia gama de elementos de formulario incorporados, puede agregar elementos personalizados al formulario de esta manera:

$form->addComponent(new DateInput('Fecha:'), 'date');
// sintaxis alternativa: $form['date'] = new DateInput('Fecha:');

El formulario es descendiente de la clase Container y los elementos individuales son descendientes de Component.

Existe una forma de definir nuevos métodos de formulario que sirven para agregar elementos personalizados (por ejemplo, $form->addZip()). Se trata de los llamados extension methods. La desventaja es que el autocompletado en los editores no funcionará para ellos.

use Nette\Forms\Container;

// agregamos el método addZip(string $name, ?string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'Al menos 5 números', '[0-9]{5}');
});

// uso
$form->addZip('zip', 'Código postal:');

Elementos de bajo nivel

También se pueden usar elementos que escribimos solo en la plantilla y no los agregamos al formulario con alguno de los métodos $form->addXyz(). Por ejemplo, si mostramos registros de la base de datos y no sabemos de antemano cuántos habrá ni qué ID tendrán, y queremos mostrar una casilla de verificación o un botón de opción en cada fila, basta con codificarlo en la plantilla:

{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}

Y después de enviar, obtenemos el valor:

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

donde el primer parámetro es el tipo de elemento (DataFile para type=file, DataLine para entradas de una línea como text, password, email, etc. y DataText para todos los demás) y el segundo parámetro sel[] corresponde al atributo HTML name. Podemos combinar el tipo de elemento con el valor DataKeys, que conserva las claves de los elementos. Esto es especialmente útil para select, radioList y checkboxList.

Lo importante es que getHttpData() devuelve un valor sanitizado, en este caso siempre será un array de cadenas UTF-8 válidas, sin importar lo que un atacante intente pasar al servidor. Es análogo al trabajo directo con $_POST o $_GET, pero con la diferencia esencial de que siempre devuelve datos limpios, tal como está acostumbrado con los elementos estándar de los formularios Nette.