Controles de formularios

Visión general de los controles de formulario incorporados.

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

Añade un campo de texto de una sola línea (clase TextInput). Si el usuario no rellena el campo, devuelve una cadena vacía '', o utiliza setNullable() para cambiarlo y que devuelva null.

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

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

La longitud máxima puede limitarse mediante setMaxLength(). La función addFilter() permite cambiar el valor introducido por el usuario.

Utilizando setHtmlType(), puede cambiar el carácter del elemento de entrada a search, tel, url, range, month, week, o color. Para otros tipos como number, email, date, datetime-local, y time, hay métodos separados addInteger, addFloat, addEmail, addDate, addTime, y addDateTime, que vienen con validación del lado del servidor.

$form->addText('color', 'Elige color:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'valor no válido', '[0-9a-f]{6}');

Se puede establecer el llamado empty-value para el elemento, que es algo así como el valor por defecto, pero si el usuario no lo sobrescribe, devuelve cadena vacía o null.

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

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

Añade un campo de texto multilínea (clase TextArea). Si el usuario no rellena el campo, devuelve una cadena vacía '', o utiliza setNullable() para cambiarlo y que devuelva null.

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

Valida automáticamente UTF-8 y normaliza los saltos de línea a \n. A diferencia de un campo de entrada de una sola línea, no recorta los espacios en blanco.

La longitud máxima puede limitarse mediante setMaxLength(). La función addFilter() permite cambiar el valor introducido por el usuario. Puede establecer el llamado valor vacío utilizando setEmptyValue().

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

Añade un campo de entrada para números enteros (clase TextInput). Devuelve un entero o null si el usuario no introduce nada.

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

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

Adds a field for entering a decimal number (TextInput class). Returns either float or null, if the user does not specify anything.

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

Nette y Chrome aceptan tanto la coma como el punto como separador decimal. Para que Firefox también acepte una coma, es necesario establecer el idioma correspondiente en el atributo HTML lang, ya sea directamente en este elemento o en cualquier elemento padre, por ejemplo <html lang="cs">.

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

Añade un campo de dirección de correo electrónico con comprobación de validez (clase TextInput). Si el usuario no rellena el campo, devuelve una cadena vacía '', o utiliza setNullable() para cambiarlo y que devuelva null.

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

Verifica que el valor es una dirección de correo electrónico válida. No verifica que el dominio exista realmente, sólo se verifica la sintaxis. Valida automáticamente UTF-8, recorta los espacios en blanco a izquierda y derecha.

La longitud máxima puede limitarse utilizando setMaxLength(). La función addFilter() permite cambiar el valor introducido por el usuario. Puede establecer el llamado valor vacío utilizando setEmptyValue().

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

Añade campo de 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, 'La contraseña debe contener un número', '.*[0-9].*');

Al reenviar el formulario, la entrada estará en blanco. Valida automáticamente UTF-8, recorta los espacios en blanco a izquierda y derecha y elimina los saltos de línea que podría enviar un atacante.

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

Añade una casilla de verificación (clase Checkbox). El campo devuelve true o false, dependiendo de si está marcado.

$form->addCheckbox('agree', 'Estoy de acuerdo con las condiciones')
	->setRequired('Debe aceptar nuestros términos');

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

Añade una lista de casillas de verificación para seleccionar varios elementos (clase CheckboxList). Devuelve el array de claves de los elementos seleccionados. El método getSelectedItems() devuelve valores en lugar de claves.

$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Pasamos el array de elementos como tercer parámetro, o por el método setItems().

Puede utilizar setDisabled(['r', 'g']) para desactivar elementos individuales.

El elemento comprueba automáticamente que no ha habido falsificación y que los elementos seleccionados son realmente uno de los ofrecidos y no han sido desactivados. Se puede utilizar el método getRawValue() para recuperar los elementos enviados sin esta importante comprobación.

Cuando se establecen valores por defecto, también comprueba que son uno de los elementos ofrecidos, de lo contrario lanza una excepción. Esta comprobación puede desactivarse con checkDefaultValue(false).

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

Añade botones de radio (clase RadioList). Devuelve la clave del elemento seleccionado, o null si el usuario no seleccionó nada. El método getSelectedItem() devuelve un valor en lugar de una clave.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);

Pasamos el array de elementos como tercer parámetro, o por el método setItems().

Puede utilizar setDisabled(['m']) para desactivar elementos individuales.

El elemento comprueba automáticamente que no ha habido falsificación y que el elemento seleccionado es realmente uno de los ofrecidos y no ha sido desactivado. Se puede utilizar el método getRawValue() para recuperar el elemento presentado sin esta importante comprobación.

Cuando se establece el valor por defecto, también comprueba que es uno de los elementos ofrecidos, de lo contrario lanza una excepción. Esta comprobación puede desactivarse con checkDefaultValue(false).

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

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

$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

$form->addSelect('country', 'Country:', $countries)
	->setDefaultValue('SK');

Pasamos la matriz de elementos como tercer parámetro, o mediante el método setItems(). La matriz de elementos también puede ser bidimensional:

$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];

Para las cajas de selección, el primer elemento a menudo tiene un significado especial, sirve como una llamada a la acción. Utilice el método setPrompt() para añadir una entrada de este tipo.

$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');

Puede utilizar setDisabled(['CZ', 'SK']) para desactivar elementos individuales.

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

Añade una caja de selección multielección (clase MultiSelectBox). Devuelve el array de claves de los elementos seleccionados. El método getSelectedItems() devuelve valores en lugar de claves.

$form->addMultiSelect('countries', 'Countries:', $countries);

Pasamos la matriz de elementos como tercer parámetro, o mediante el método setItems(). La matriz de elementos también puede ser bidimensional.

Puede utilizar setDisabled(['CZ', 'SK']) para desactivar elementos individuales.

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

Añade el campo de subida de ficheros (clase UploadControl). Devuelve el objeto FileUpload, incluso si el usuario no ha subido un archivo, lo cual puede averiguarse mediante el método FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar must be JPEG, PNG, GIF or WebP')
	->addRule($form::MaxFileSize, 'Maximum size is 1 MB', 1024 * 1024);

Si el fichero no se ha subido correctamente, el formulario no se ha enviado correctamente y se muestra un error. Es decir, no es necesario comprobar el método FileUpload::isOk().

No confíe en el nombre de archivo original devuelto por el método FileUpload::getName(), un cliente podría enviar un nombre de archivo malicioso con la intención de corromper o hackear su aplicación.

Las reglas MimeType y Image detectan el tipo de archivo o imagen requerido por su firma. No se comprueba la integridad de todo el archivo. Puedes averiguar si una imagen no está corrupta, por ejemplo, intentando cargarla.

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

Añade un campo de carga múltiple de archivos (clase UploadControl). Devuelve un array de objetos FileUpload. El método FileUpload::hasFile() devolverá true para cada uno de ellos.

$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);

Si uno de los archivos no se carga correctamente, el formulario no se ha enviado correctamente y se muestra un error. Es decir, no es necesario comprobar el método FileUpload::isOk().

No confíe en los nombres de archivo originales devueltos por el método FileUpload::getName(), un cliente podría enviar un nombre de archivo malicioso con la intención de corromper o piratear su aplicación.

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

Añade un campo que permite al usuario introducir fácilmente una fecha consistente en año, mes y día (clase DateTimeControl).

Para el valor predeterminado, acepta objetos que implementen la regla DateTimeInterface, una cadena con la hora o un número que represente una marca de tiempo UNIX. Lo mismo ocurre con los argumentos de regla Min, Max, o Range, que definen la fecha mínima y máxima permitidas.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Por defecto, devuelve un objeto DateTimeImmutable. Mediante el método setFormat(), puede especificar un formato de texto o una marca de tiempo:

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

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

Añade un campo que permite al usuario introducir fácilmente la hora consistente en horas, minutos y, opcionalmente, segundos (clase DateTimeControl).

Por defecto, acepta objetos que implementen la clase DateTimeInterface, una cadena con la hora o un número que represente una marca de tiempo UNIX. Sólo se utiliza la información horaria de estas entradas; la fecha se ignora. Lo mismo ocurre con los argumentos de regla Min, Max o Range, que definen el tiempo mínimo y máximo permitido. Si el valor mínimo establecido es superior al máximo, se crea un intervalo de tiempo que abarca la medianoche.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

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

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

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

Añade un campo que permite al usuario introducir fácilmente tanto la fecha como la hora consistente en año, mes, día, horas, minutos y opcionalmente segundos (clase DateTimeControl).

Para el valor por defecto, acepta bien objetos que implementen el DateTimeInterface, una cadena con la hora, o un número que represente una marca de tiempo UNIX. Lo mismo se aplica a los argumentos de regla Min, Max, o Range, que definen la fecha mínima y máxima permitidas.

$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Por defecto, devuelve un objeto DateTimeImmutable. Mediante el método setFormat(), puede especificar un formato de texto o una marca de tiempo:

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

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

Añade un campo de selección de color (clase ColorPicker). El color es una cadena con el formato #rrggbb. Si el usuario no hace una selección, el color devuelto por defecto es el negro #000000.

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

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

Añade un campo oculto (clase HiddenField).

$form->addHidden('userid');

Utiliza setNullable() para cambiarlo y que devuelva null en lugar de una cadena vacía. La función addFilter() permite cambiar el valor enviado.

Aunque el elemento esté oculto, es importante darse cuenta de que su valor aún puede ser modificado o suplantado por un atacante. Verifica y valida siempre todos los valores recibidos en el servidor para evitar riesgos de seguridad asociados a la manipulación de datos.

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

Añade un botón de envío (clase SubmitButton).

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

Es posible tener más de un botón de envío en el formulario:

$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');

Para saber cuál de ellos fue pulsado, utilice:

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

Si no desea validar el formulario cuando se pulsa un botón de envío (como los botones Cancelar o Preview), puede desactivarlo con setValidationScope().

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

Añade un botón (clase Button) sin función de envío. Es útil para vincular otra funcionalidad a id, por ejemplo una acción JavaScript.

$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

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

$form->addImageButton('submit', '/path/to/image');

Cuando se utilizan varios botones de envío, puede averiguar cuál fue pulsado con $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Añade un subformulario (clase Container), o un contenedor, que puede ser tratado de la misma manera que un formulario. Esto significa que puede utilizar métodos como setDefaults() o getValues().

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

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

Los datos enviados se devuelven como una estructura multidimensional:

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

Visión general de la configuración

Para todos los elementos podemos llamar a los siguientes métodos (véase la documentación de la API para una visión completa):

`setDefaultValue($value)`	establece el valor por defecto
`getValue()`	obtiene el valor actual
`setOmitted()`	omitir valores
`setDisabled()`	desactivar entradas

Renderización:

`setCaption($caption)`	cambia el título 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)`	establece los datos de renderizado

Validación:

`setRequired()`	Campo obligatorio
`addRule()`	Establecer regla de validación
`addCondition()`, `addConditionOn()`	Establecer condición de validación
`addError($message)`	Pasar mensaje de error

Los siguientes métodos pueden ser llamados para los elementos addText(), addPassword(), addTextArea(), addEmail(), addInteger():

`setNullable()`	establece si getValue() devuelve `null` en lugar de una cadena vacía
`setEmptyValue($value)`	establece el valor especial que se trata como cadena vacía
`setMaxLength($length)`	establece el número máximo de caracteres permitidos
`addFilter($filter)`	Modificación de los valores de entrada

Valores omitidos

Si no nos interesa el valor introducido por el usuario, podemos utilizar setOmitted() para omitirlo del resultado proporcionado por el método $form->getValues() o pasado a los manejadores. Esto es adecuado para varias contraseñas de verificación, campos antispam, etc.

$form->addPassword('passwordVerify', 'Contraseña de nuevo:')
	->setRequired('Rellena tu contraseña de nuevo para comprobar si hay algún error tipográfico')
	->addRule($form::Equal, 'Contraseña incorrecta', $form['password'])
	->setOmitted();

Desactivar entradas

Las entradas pueden desactivarse utilizando setDisabled(). Una entrada desactivada no puede ser editada por el usuario.

$form->addText('username', 'User name:')
	->setDisabled();

Las entradas deshabilitadas no son enviadas al servidor por el navegador, por lo que no las encontrará en los datos devueltos por la función $form->getValues(). Sin embargo, si configuras setOmitted(false), Nette incluirá su valor por defecto en estos datos.

Cuando se llama a setDisabled(), el valor de la entrada se borra por razones de seguridad. Si establece un valor por defecto, es necesario hacerlo después de su desactivación:

$form->addText('username', 'User name:')
	->setDisabled()
	->setDefaultValue($userName);

Una alternativa a las entradas deshabilitadas son los campos con el atributo HTML readonly, que el navegador envía al servidor. Aunque el campo sólo es legible, es importante darse cuenta de que su valor aún puede ser modificado o suplantado por un atacante.

Controles personalizados

Además de la amplia gama de controles de formulario incorporados, puede añadir controles personalizados al formulario como se indica a continuación:

$form->addComponent(new DateInput('Date:'), 'date');
// alternative syntax: $form['date'] = new DateInput('Date:');

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

Existe una forma de definir nuevos métodos de formulario para añadir elementos personalizados (por ejemplo $form->addZip()). Estos son los llamados métodos de extensión. El inconveniente es que las sugerencias de código en los editores no funcionarán para ellos.

use Nette\Forms\Container;

// adds method 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, 'At least 5 numbers', '[0-9]{5}');
});

// usage
$form->addZip('zip', 'ZIP code:');

Campos de bajo nivel

Para añadir un elemento al formulario, no es necesario llamar a $form->addXyz(). En su lugar, los elementos del formulario pueden introducirse exclusivamente en las plantillas. Esto es útil si, por ejemplo, necesita generar elementos dinámicos:

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

Tras el envío, puede recuperar los valores:

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

En el primer parámetro, se especifica el tipo de elemento (DataFile para type=file, DataLine para entradas de una línea como text, password o email y DataText para el resto). El segundo parámetro coincide con el atributo HTML name. Si necesita conservar las claves, puede combinar el primer parámetro con DataKeys. Esto es útil para select, radioList o checkboxList.

getHttpData() devuelve la entrada desinfectada. En este caso, siempre será un array de cadenas UTF-8 válidas, sin importar el atacante enviado por el formulario. Es una alternativa a trabajar con $_POST o $_GET directamente si quieres recibir datos seguros.