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