Controles de formulário
***********************

.[perex]
Visão geral dos controles de formulário incorporados.


addText(string|int $name, $label=null): TextInput .[method]
===========================================================

Adiciona campo de texto de linha única (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Se o usuário não preencher o campo, retorna uma string vazia `''`, ou usa `setNullable()` para alterá-lo para retornar `null`.

```php
$form->addText('name', 'Name:')
	->setRequired()
	->setNullable();
```

Ela valida automaticamente UTF-8, apara os espaços em branco à esquerda e à direita e remove quebras de linha que poderiam ser enviadas por um atacante.

O comprimento máximo pode ser limitado usando `setMaxLength()`. O [addFilter() |validation#Modifying Input Values] permite alterar o valor inserido pelo usuário.

Use `setHtmlType()` para mudar o [caráter |https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types] do elemento de entrada para `search`, `tel`, `url`, `range`, `date`, `datetime-local`, `month`, `time`, `week`, `color`. Em vez dos tipos `number` e `email`, recomendamos usar [addInteger |#addInteger] e [addEmail |#addEmail], que fornecem validação do lado do servidor.

```php
$form->addText('color', 'Choose color:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');
```

O chamado valor vazio pode ser definido para o elemento, que é algo como o valor padrão, mas se o usuário não o sobrescrever, retorna uma string vazia ou `null`.

```php
$form->addText('phone', 'Phone:')
	->setHtmlType('tel')
	->setEmptyValue('+420');
```


addTextArea(string|int $name, $label=null): TextArea .[method]
==============================================================

Adiciona um campo de texto com várias linhas (classe [TextArea |api:Nette\Forms\Controls\TextArea]). Se o usuário não preencher o campo, ele retorna uma string vazia `''`, ou use `setNullable()` para alterá-lo para retornar `null`.

```php
$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);
```

Valida automaticamente o UTF-8 e normaliza as quebras de linha para `\n`. Ao contrário de um campo de entrada de linha única, ele não apara o espaço em branco.

O comprimento máximo pode ser limitado usando `setMaxLength()`. O [addFilter() |validation#Modifying Input Values] permite alterar o valor inserido pelo usuário. Você pode definir o chamado valor vazio usando `setEmptyValue()`.


addInteger(string|int $name, $label=null): TextInput .[method]
==============================================================

Adiciona campo de entrada para o número inteiro (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Retorna ou um número inteiro ou `null` se o usuário não inserir nada.

```php
$form->addInteger('level', 'Level:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Level must be between %d and %d.', [0, 100]);
```


addEmail(string|int $name, $label=null): TextInput .[method]
============================================================

Adiciona campo de endereço de e-mail com verificação de validade (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Se o usuário não preencher o campo, devolve uma string vazia `''`, ou usa `setNullable()` para alterá-lo para retornar `null`.

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

Verifica que o valor é um endereço de e-mail válido. Não verifica que o domínio realmente existe, apenas a sintaxe é verificada. Valida automaticamente o UTF-8, apara espaços em branco à esquerda e à direita.

O comprimento máximo pode ser limitado usando `setMaxLength()`. O [addFilter() |validation#Modifying Input Values] permite alterar o valor inserido pelo usuário. Você pode definir o chamado valor vazio usando `setEmptyValue()`.


addPassword(string|int $name, $label=null): TextInput .[method]
===============================================================

Adiciona o campo de senha (classe [TextInput |api:Nette\Forms\Controls\TextInput]).

```php
$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MinLength, 'Password has to be at least %d characters long', 8)
	->addRule($form::Pattern, 'Password must contain a number', '.*[0-9].*');
```

Quando você reenviar o formulário, a entrada estará em branco. Ela valida automaticamente o UTF-8, apara os espaços em branco à esquerda e à direita e remove quebras de linha que poderiam ser enviadas por um atacante.


addCheckbox(string|int $name, $caption=null): Checkbox .[method]
================================================================

Acrescenta uma caixa de seleção ( [caixa de seleção de |api:Nette\Forms\Controls\Checkbox] classe). O campo retorna ou `true` ou `false`, dependendo se está marcado.

```php
$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');
```


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

Adiciona lista de caixas de seleção para selecionar vários itens (classe [CheckboxList |api:Nette\Forms\Controls\CheckboxList]). Retorna a matriz de chaves dos itens selecionados. O método `getSelectedItems()` retorna valores em vez de chaves.

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

Passamos o conjunto de itens como o terceiro parâmetro, ou pelo método `setItems()`.

Você pode usar `setDisabled(['r', 'g'])` para desativar itens individuais.

O elemento verifica automaticamente que não houve falsificação e que os itens selecionados são realmente um dos oferecidos e não foram desativados. O método `getRawValue()` pode ser usado para recuperar os itens submetidos sem esta importante verificação.

Quando os valores padrão são definidos, ele também verifica se eles são um dos itens oferecidos, caso contrário, ele lança uma exceção. Esta verificação pode ser desativada com `checkDefaultValue(false)`.


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

Acrescenta botões de rádio (classe [RadioList |api:Nette\Forms\Controls\RadioList]). Devolve a chave do item selecionado, ou `null` caso o usuário não tenha selecionado nada. O método `getSelectedItem()` retorna um valor em vez de uma chave.

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

Passamos o conjunto de itens como o terceiro parâmetro, ou pelo método `setItems()`.

Você pode usar `setDisabled(['m'])` para desativar itens individuais.

O elemento verifica automaticamente que não houve falsificação e que o item selecionado é realmente um dos oferecidos e não foi desativado. O método `getRawValue()` pode ser usado para recuperar o item submetido sem esta importante verificação.

Quando o valor padrão é definido, ele também verifica se ele é um dos itens oferecidos, caso contrário, ele lança uma exceção. Esta verificação pode ser desativada com `checkDefaultValue(false)`.


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

Adiciona caixa de seleção (classe [SelectBox |api:Nette\Forms\Controls\SelectBox]). Devolve a chave do item selecionado, ou `null` caso o usuário não tenha selecionado nada. O método `getSelectedItem()` retorna um valor em vez de uma chave.

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

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

Passamos o conjunto de itens como o terceiro parâmetro, ou pelo método `setItems()`. A matriz de itens também pode ser bidimensional:

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

Para caixas seletas, o primeiro item muitas vezes tem um significado especial, serve como uma chamada para ação. Use o método `setPrompt()` para adicionar tal entrada.

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

Você pode usar `setDisabled(['CZ', 'SK'])` para desativar itens individuais.

O elemento verifica automaticamente que não houve falsificação e que o item selecionado é realmente um dos oferecidos e não foi desativado. O método `getRawValue()` pode ser usado para recuperar o item submetido sem esta importante verificação.

Quando o valor padrão é definido, ele também verifica se ele é um dos itens oferecidos, caso contrário, ele lança uma exceção. Esta verificação pode ser desativada com `checkDefaultValue(false)`.


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

Adiciona caixa de seleção de múltipla escolha (classe [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Devolve a matriz de chaves dos itens selecionados. O método `getSelectedItems()` retorna valores em vez de chaves.

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

Passamos o conjunto de itens como o terceiro parâmetro, ou pelo método `setItems()`. A matriz de itens também pode ser bidimensional.

Você pode usar `setDisabled(['CZ', 'SK'])` para desativar itens individuais.

O elemento verifica automaticamente que não houve falsificação e que os itens selecionados são realmente um dos oferecidos e não foram desativados. O método `getRawValue()` pode ser usado para recuperar os itens submetidos sem esta importante verificação.

Quando os valores padrão são definidos, ele também verifica se eles são um dos itens oferecidos, caso contrário, ele lança uma exceção. Esta verificação pode ser desativada com `checkDefaultValue(false)`.


addUpload(string|int $name, $label=null): UploadControl .[method]
=================================================================

Adiciona o campo upload do arquivo (classe [UploadControl |api:Nette\Forms\Controls\UploadControl]). Retorna o objeto [FileUpload |http:request#FileUpload], mesmo que o usuário não tenha feito upload de um arquivo, o que pode ser descoberto pelo método `FileUpload::hasFile()`.

```php
$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);
```

Se o arquivo não foi carregado corretamente, o formulário não foi enviado com sucesso e um erro é exibido. Ou seja, não é necessário verificar o método `FileUpload::isOk()`.

Não confie no nome do arquivo original devolvido pelo método `FileUpload::getName()`, um cliente poderia enviar um nome de arquivo malicioso com a intenção de corromper ou invadir seu aplicativo.

As regras `MimeType` e `Image` detectam o tipo de arquivo ou imagem exigida por sua assinatura. A integridade do arquivo inteiro não é verificada. Você pode descobrir se uma imagem não está corrompida, por exemplo, ao tentar [carregá-la |http:request#toImage].


addMultiUpload(string|int $name, $label=null): UploadControl .[method]
======================================================================

Adiciona o campo de carregamento de múltiplos arquivos (classe [UploadControl |api:Nette\Forms\Controls\UploadControl]). Retorna um array de objetos [FileUpload |http:request#FileUpload]. O método `FileUpload::hasFile()` retornará `true` para cada um deles.

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

Se um dos arquivos não for carregado corretamente, o formulário não foi enviado com sucesso e um erro é exibido. Ou seja, não é necessário verificar o método `FileUpload::isOk()`.

Não confie nos nomes originais dos arquivos devolvidos pelo método `FileUpload::getName()`, um cliente poderia enviar um nome de arquivo malicioso com a intenção de corromper ou invadir sua aplicação.

As regras `MimeType` e `Image` detectam o tipo de arquivo ou imagem exigida por sua assinatura. A integridade do arquivo inteiro não é verificada. Você pode descobrir se uma imagem não está corrompida, por exemplo, ao tentar [carregá-la |http:request#toImage].


addHidden(string|int $name, string $default=null): HiddenField .[method]
========================================================================

Adiciona campo oculto (classe [HiddenField |api:Nette\Forms\Controls\HiddenField]).

```php
$form->addHidden('userid');
```

Use `setNullable()` para mudá-lo para retornar `null` ao invés de um fio vazio. O [addFilter() |validation#Modifying Input Values] permite que você altere o valor submetido.


addSubmit(string|int $name, $caption=null): SubmitButton .[method]
==================================================================

Adiciona botão submeter (classe [SubmitButton |api:Nette\Forms\Controls\SubmitButton]).

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

É possível ter mais de um botão de envio no formulário:

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

Para descobrir qual deles foi clicado, use:

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

Se você não quiser validar o formulário quando um botão de envio for pressionado (como *Cancelar* ou *Pré-visualizar* botões), você pode desligá-lo com [setValidationScope() |validation#Disabling Validation].


addButton(string|int $name, $caption): Button .[method]
=======================================================

Adiciona botão ( [Botão de |api:Nette\Forms\Controls\Button] classe) sem função de submissão. É útil para vincular outras funcionalidades à identificação, por exemplo, uma ação JavaScript.

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


addImageButton(string|int $name, string $src=null, string $alt=null): ImageButton .[method]
===========================================================================================

Adiciona botão submeter em forma de uma imagem (classe [ImageButton |api:Nette\Forms\Controls\ImageButton]).

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

Ao usar vários botões de envio, você pode descobrir qual deles foi clicado com `$form['submit']->isSubmittedBy()`.


addContainer(string|int $name): Container .[method]
===================================================

Adiciona um subforma ( [Container |api:Nette\Forms\Container] classe), ou um recipiente, que pode ser tratado da mesma forma que um formulário. Isso significa que você pode usar métodos como `setDefaults()` ou `getValues()`.

```php
$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Your name:');
$sub1->addEmail('email', 'Email:');

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

Os dados enviados são então devolvidos como uma estrutura multidimensional:

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


Visão geral das configurações .[#toc-overview-of-settings]
==========================================================

Para todos os elementos, podemos chamar os seguintes métodos (ver [documentação API |https://api.nette.org/forms/master/Nette/Forms/Controls.html] para uma visão geral completa):

.[table-form-methods language-php]
| `setDefaultValue($value)` | define o valor padrão
| `getValue()` | obter valor atual
| `setOmitted()` | [valores omitidos |#omitted values]
| `setDisabled()` | [desabilitando entradas |#disabling inputs]

Renderização:
.[table-form-methods language-php]
| `setCaption($caption)`| altere o título do item
| `setTranslator($translator)` | define o [tradutor |rendering#translating]
| `setHtmlAttribute($name, $value)` | define o [atributo HTML |rendering#HTML attributes] do elemento
| `setHtmlId($id)` | define o atributo HTML `id`
| `setHtmlType($type)` | define o atributo HTML `type`
| `setHtmlName($name)`| define o atributo HTML `name`
| `setOption($key, $value)` | define [os dados de renderização |rendering#Options]

Validação:
.[table-form-methods language-php]
| `setRequired()` | [campo obrigatório |validation]
| `addRule()` | estabelecer [regra de validação |validation#Rules]
| `addCondition()`, `addConditionOn()` | estabelecer [condição de validação |validation#Conditions]
| `addError($message)`| [passando mensagem de erro |validation#processing-errors]

Os seguintes métodos podem ser chamados para o `addText()`, `addPassword()`, `addTextArea()`, `addEmail()`, `addInteger()` itens:

.[table-form-methods language-php]
| `setNullable()`| define se getValue() retorna `null` em vez de string vazia
| `setEmptyValue($value)` | define o valor especial que é tratado como cadeia vazia
| `setMaxLength($length)`| define o número máximo de caracteres permitidos
| `addFilter($filter)`| [modificando os valores de entrada |validation#Modifying Input Values]


Valores omitidos .[#toc-omitted-values]
---------------------------------------

Se você não estiver interessado no valor inserido pelo usuário, podemos usar `setOmitted()` para omiti-lo do resultado fornecido pelo método `$form->getValues​()` ou passado para os manipuladores. Isto é adequado para várias senhas de verificação, campos antispam, etc.

```php
$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::Equal, 'Password mismatch', $form['password'])
	->setOmitted();
```


Desativação de entradas .[#toc-disabling-inputs]
------------------------------------------------

A fim de desativar uma entrada, você pode ligar para `setDisabled()`. Tal campo não pode ser editado pelo usuário.

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

Note que o navegador não envia os campos desativados para o servidor, portanto você não os encontrará nem mesmo nos dados devolvidos pela função `$form->getValues()`.

Se você estiver definindo um valor padrão para um campo, você deve fazê-lo somente após desativá-lo:

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


Controles personalizados .[#toc-custom-controls]
================================================

Além de uma ampla gama de controles embutidos no formulário, você pode adicionar controles personalizados ao formulário da seguinte forma:

```php
$form->addComponent(new DateInput('Date:'), 'date');
// sintaxe alternativa: $form['date'] = novo DateInput('Date:');
```

.[note]
A forma é um descendente da classe [Container | component-model:#Container] e os elementos são descendentes de [Componente | component-model:#Component].

Há uma maneira de definir novos métodos de formulário para adicionar elementos personalizados (por exemplo, `$form->addZip()`). Estes são os chamados métodos de extensão. O lado negativo é que as dicas de código nos editores não funcionarão para eles.

```php
use Nette\Forms\Container;

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

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


Campos de baixo nível .[#toc-low-level-fields]
==============================================

Para adicionar um item ao formulário, você não precisa ligar para `$form->addXyz()`. Os itens do formulário podem ser introduzidos exclusivamente em modelos. Isto é útil se você, por exemplo, precisar gerar itens dinâmicos:

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

Após a apresentação, você pode recuperar os valores:

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

No primeiro parâmetro, você especifica o tipo de elemento (`DataFile` para `type=file`, `DataLine` para entradas de uma linha como `text`, `password` ou `email` e `DataText` para o resto). O segundo parâmetro corresponde ao atributo HTML `name`. Se você precisar preservar chaves, você pode combinar o primeiro parâmetro com `DataKeys`. Isto é útil para `select`, `radioList` ou `checkboxList`.

O `getHttpData()` retorna entrada higienizada. Neste caso, será sempre um conjunto de cordas UTF-8 válidas, não importando o que o atacante tenha enviado pelo formulário. É uma alternativa ao trabalho com `$_POST` ou `$_GET` diretamente, se você quiser receber dados seguros.