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.

Utilice setHtmlType() para cambiar el carácter del elemento de entrada a search, tel, url, range, date, datetime-local, month, time, week, color. En lugar de los tipos number y email, recomendamos utilizar addInteger y addEmail, que proporcionan 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('level', 'Nivel:')
	->setDefaultValue(0)
	->addRule($form::Range, 'El nivel debe estar entre %d y %d.', [0, 100]);

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.

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).

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.

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).

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.

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.

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.

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):

Renderización:

Validación:

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

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

Para desactivar una entrada, puede llamar a setDisabled(). Un campo de este tipo no puede ser editado por el usuario.

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

Tenga en cuenta que el navegador no envía los campos deshabilitados al servidor en absoluto, por lo que ni siquiera los encontrará en los datos devueltos por la función $form->getValues().

Si establece un valor predeterminado para un campo, debe hacerlo sólo después de desactivarlo:

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

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.