Nette Documentation Preview

syntax 
Elementos de Formulário
***********************

.[perex]
Visão geral dos elementos de formulário padrão.


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

Adiciona um 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 usando `setNullable()` pode-se especificar que retorne `null`.

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

Valida automaticamente UTF-8, remove espaços à esquerda e à direita e remove quebras de linha que um invasor poderia enviar.

O comprimento máximo pode ser limitado usando `setMaxLength()`. Modificar o valor inserido pelo usuário é possível com [addFilter() |validation#Modificação da entrada].

Usando `setHtmlType()`, é possível alterar o caractere visual do campo de texto para tipos como `search`, `tel` ou `url`, veja a [especificação|https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types]. Lembre-se que a alteração do tipo é apenas visual e não substitui a função de validação. Para o tipo `url`, é apropriado adicionar uma [regra URL |validation#Entradas de texto] de validação específica.

.[note]
Para outros tipos de entrada, como `number`, `range`, `email`, `date`, `datetime-local`, `time` e `color`, use métodos especializados como [#addInteger], [#addFloat], [#addEmail] [#addDate], [#addTime], [#addDateTime] e [#addColor], que garantem a validação do lado do servidor. Os tipos `month` e `week` ainda não são totalmente suportados em todos os navegadores.

Ao elemento pode ser definido o chamado empty-value, que é algo como um valor padrão, mas se o usuário não o alterar, o elemento retorna uma string vazia ou `null`.

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


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

Adiciona um campo para inserir texto multilinha (classe [TextArea |api:Nette\Forms\Controls\TextArea]). Se o usuário não preencher o campo, retorna uma string vazia `''`, ou usando `setNullable()` pode-se especificar que retorne `null`.

```php
$form->addTextArea('note', 'Nota:')
	->addRule($form::MaxLength, 'A nota é muito longa', 10000);
```

Valida automaticamente UTF-8 e normaliza os separadores de linha para `\n`. Ao contrário do campo de entrada de linha única, não ocorre remoção de espaços.

O comprimento máximo pode ser limitado usando `setMaxLength()`. Modificar o valor inserido pelo usuário é possível com [addFilter() |validation#Modificação da entrada]. É possível definir o chamado empty-value usando `setEmptyValue()`.


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

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

```php
$form->addInteger('year', 'Ano:')
	->addRule($form::Range, 'O ano deve estar no intervalo de %d a %d.', [1900, 2023]);
```

O elemento é renderizado como `<input type="number">`. Usando o método `setHtmlType()`, é possível alterar o tipo para `range` para exibição na forma de um controle deslizante, ou para `text`, se preferir um campo de texto padrão sem o comportamento especial do tipo `number`.


addFloat(string|int $name, $label=null): TextInput .[method]{data-version:3.1.12}
=================================================================================

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

```php
$form->addFloat('level', 'Nível:')
	->setDefaultValue(0)
	->addRule($form::Range, 'O nível deve estar no intervalo de %d a %d.', [0, 100]);
```

O elemento é renderizado como `<input type="number">`. Usando o método `setHtmlType()`, é possível alterar o tipo para `range` para exibição na forma de um controle deslizante, ou para `text`, se preferir um campo de texto padrão sem o comportamento especial do tipo `number`.

Nette e o navegador Chrome aceitam tanto vírgula quanto ponto como separador decimal. Para que essa funcionalidade esteja disponível também no Firefox, é recomendado definir o atributo `lang` para o elemento específico ou para a página inteira, por exemplo, `<html lang="pt-BR">`.


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

Adiciona um campo para inserir um endereço de e-mail (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Se o usuário não preencher o campo, retorna uma string vazia `''`, ou usando `setNullable()` pode-se especificar que retorne `null`.

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

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

O comprimento máximo pode ser limitado usando `setMaxLength()`. Modificar o valor inserido pelo usuário é possível com [addFilter() |validation#Modificação da entrada]. É possível definir o chamado empty-value usando `setEmptyValue()`.


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

Adiciona um campo para inserir uma senha (classe [TextInput |api:Nette\Forms\Controls\TextInput]).

```php
$form->addPassword('password', 'Senha:')
	->setRequired()
	->addRule($form::MinLength, 'A senha deve ter pelo menos %d caracteres', 8)
	->addRule($form::Pattern, 'Deve conter um dígito', '.*[0-9].*');
```

Ao reexibir o formulário, o campo estará vazio. Valida automaticamente UTF-8, remove espaços à esquerda e à direita e remove quebras de linha que um invasor poderia enviar.


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

Adiciona uma caixa de seleção (classe [Checkbox |api:Nette\Forms\Controls\Checkbox]). Retorna o valor `true` ou `false`, dependendo se está marcada.

```php
$form->addCheckbox('agree', 'Concordo com os termos')
	->setRequired('É necessário concordar com os termos');
```


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

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

```php
$form->addCheckboxList('colors', 'Cores:', [
	'r' => 'vermelho',
	'g' => 'verde',
	'b' => 'azul',
]);
```

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método `setItems()`.

Usando `setDisabled(['r', 'g'])`, é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se os itens selecionados estão realmente entre os oferecidos e não foram desativados. O método `getRawValue()` permite obter os itens enviados sem essa importante verificação.

Ao definir os itens selecionados padrão, também verifica se eles estão entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando `checkDefaultValue(false)`.

Se você enviar o formulário pelo método `GET`, pode escolher um método de transmissão de dados mais compacto, que economiza o tamanho da query string. Ele é ativado definindo o atributo HTML do formulário:

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


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

Adiciona botões de opção (classe [RadioList |api:Nette\Forms\Controls\RadioList]). Retorna a chave do item selecionado, ou `null` se o usuário não selecionou nada. O método `getSelectedItem()` retorna o valor em vez da chave.

```php
$sex = [
	'm' => 'masculino',
	'f' => 'feminino',
];
$form->addRadioList('gender', 'Sexo:', $sex);
```

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método `setItems()`.

Usando `setDisabled(['m', 'f'])`, é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se o item selecionado está realmente entre os oferecidos e não foi desativado. O método `getRawValue()` permite obter o item enviado sem essa importante verificação.

Ao definir o item selecionado padrão, também verifica se ele está entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando `checkDefaultValue(false)`.


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

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

```php
$countries = [
	'BR' => 'Brasil',
	'PT' => 'Portugal',
	'GB' => 'Reino Unido',
];

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

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método `setItems()`. Os itens também podem ser um array bidimensional:

```php
$countries = [
	'Europa' => [
		'CZ' => 'República Tcheca',
		'SK' => 'Eslováquia',
		'GB' => 'Reino Unido',
	],
	'CA' => 'Canadá',
	'US' => 'EUA',
	'?'  => 'outro',
];
```

Nas caixas de seleção, o primeiro item geralmente tem um significado especial, servindo como um prompt para ação. Para adicionar tal item, use o método `setPrompt()`.

```php
$form->addSelect('country', 'País:', $countries)
	->setPrompt('Escolha um país');
```

Usando `setDisabled(['CZ', 'SK'])`, é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se o item selecionado está realmente entre os oferecidos e não foi desativado. O método `getRawValue()` permite obter o item enviado sem essa importante verificação.

Ao definir o item selecionado padrão, também verifica se ele está entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando `checkDefaultValue(false)`.


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

Adiciona uma caixa de seleção para escolher vários itens (classe [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Retorna um array das chaves dos itens selecionados. O método `getSelectedItems()` retorna os valores em vez das chaves.

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

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método `setItems()`. Os itens também podem ser um array bidimensional.

Usando `setDisabled(['CZ', 'SK'])`, é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se os itens selecionados estão realmente entre os oferecidos e não foram desativados. O método `getRawValue()` permite obter os itens enviados sem essa importante verificação.

Ao definir os itens selecionados padrão, também verifica se eles estão entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando `checkDefaultValue(false)`.


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

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

```php
$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'O avatar deve ser JPEG, PNG, GIF, WebP ou AVIF.')
	->addRule($form::MaxFileSize, 'O tamanho máximo é 1 MB.', 1024 * 1024 /* 1 MB em bytes */);
```

Se o arquivo não for carregado corretamente, o formulário não é enviado com sucesso e um erro é exibido. Ou seja, em caso de envio bem-sucedido, não é necessário verificar o método `FileUpload::isOk()`.

Nunca confie no nome original do arquivo retornado pelo método `FileUpload::getName()`, o cliente pode ter enviado um nome de arquivo malicioso com a intenção de danificar ou hackear sua aplicação.

As regras `MimeType` e `Image` detectam o tipo necessário com base na assinatura do arquivo e não verificam sua integridade. Se a imagem está danificada pode ser verificado, por exemplo, tentando [carregá-la |http:request#toImage].


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

Adiciona um campo para upload de vários arquivos de uma vez (classe [UploadControl |api:Nette\Forms\Controls\UploadControl]). Retorna um array de objetos [FileUpload |http:request#FileUpload]. O método `FileUpload::hasFile()` em cada um deles retornará `true`.

```php
$form->addMultiUpload('files', 'Arquivos:')
	->addRule($form::MaxLength, 'No máximo %d arquivos podem ser enviados', 10);
```

Se algum arquivo não for carregado corretamente, o formulário não é enviado com sucesso e um erro é exibido. Ou seja, em caso de envio bem-sucedido, não é necessário verificar o método `FileUpload::isOk()`.

Nunca confie nos nomes originais dos arquivos retornados pelo método `FileUpload::getName()`, o cliente pode ter enviado um nome de arquivo malicioso com a intenção de danificar ou hackear sua aplicação.

As regras `MimeType` e `Image` detectam o tipo necessário com base na assinatura do arquivo e não verificam sua integridade. Se a imagem está danificada pode ser verificado, por exemplo, tentando [carregá-la |http:request#toImage].


addDate(string|int $name, $label=null): DateTimeControl .[method]{data-version:3.1.14}
======================================================================================

Adiciona um campo que permite ao usuário inserir facilmente uma data composta por ano, mês e dia (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Como valor padrão, aceita objetos que implementam a interface `DateTimeInterface`, uma string com a hora, ou um número representando um timestamp UNIX. O mesmo se aplica aos argumentos das regras `Min`, `Max` ou `Range`, que definem a data mínima e máxima permitida.

```php
$form->addDate('date', 'Data:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'A data deve ter pelo menos um mês.', new DateTime('-1 month'));
```

Por padrão, retorna um objeto `DateTimeImmutable`, com o método `setFormat()` você pode especificar o [formato de texto|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] ou timestamp:

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


addTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}
===============================================================================================================

Adiciona um campo que permite ao usuário inserir facilmente uma hora composta por horas, minutos e opcionalmente segundos (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Como valor padrão, aceita objetos que implementam a interface `DateTimeInterface`, uma string com a hora, ou um número representando um timestamp UNIX. Desses inputs, apenas a informação de tempo é utilizada, a data é ignorada. O mesmo se aplica aos argumentos das regras `Min`, `Max` ou `Range`, que definem a hora mínima e máxima permitida. Se o valor mínimo definido for maior que o máximo, cria-se um intervalo de tempo que ultrapassa a meia-noite.

```php
$form->addTime('time', 'Hora:', withSeconds: true)
	->addRule($form::Range, 'A hora deve estar no intervalo de %d a %d.', ['12:30', '13:30']);
```

Por padrão, retorna um objeto `DateTimeImmutable` (com a data de 1º de janeiro do ano 1), com o método `setFormat()` você pode especificar o [formato de texto|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters]:

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


addDateTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}
===================================================================================================================

Adiciona um campo que permite ao usuário inserir facilmente data e hora compostas por ano, mês, dia, horas, minutos e opcionalmente segundos (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Como valor padrão, aceita objetos que implementam a interface `DateTimeInterface`, uma string com a hora, ou um número representando um timestamp UNIX. O mesmo se aplica aos argumentos das regras `Min`, `Max` ou `Range`, que definem a data mínima e máxima permitida.

```php
$form->addDateTime('datetime', 'Data e hora:')
	->setDefaultValue(new \DateTime)
	->addRule($form::Min, 'A data deve ter pelo menos um mês.', new \DateTime('-1 month'));
```

Por padrão, retorna um objeto `DateTimeImmutable`, com o método `setFormat()` você pode especificar o [formato de texto|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] ou timestamp:

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


addColor(string|int $name, $label=null): ColorPicker .[method]{data-version:3.1.14}
===================================================================================

Adiciona um campo para seleção de cor (classe [ColorPicker |api:Nette\Forms\Controls\ColorPicker]). A cor é uma string no formato `#rrggbb`. Se o usuário não fizer a escolha, retorna a cor preta `#000000`.

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


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

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

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

Usando `setNullable()`, pode-se definir que retorne `null` em vez de uma string vazia. Modificar o valor enviado é possível com [addFilter() |validation#Modificação da entrada].

Embora o elemento esteja oculto, é **importante notar** que o valor ainda pode ser modificado ou falsificado por um invasor. Sempre verifique e valide cuidadosamente todos os valores recebidos no lado do servidor para evitar riscos de segurança associados à manipulação de dados.


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

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

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

No formulário, é possível ter vários botões de envio:

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

Para descobrir qual deles foi clicado, use:

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

Se você não quiser validar o formulário inteiro ao pressionar o botão (por exemplo, para botões *Cancelar* ou *Visualizar*), use [setValidationScope() |validation#Desativação da validação].


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

Adiciona um botão (classe [Button |api:Nette\Forms\Controls\Button]) que não tem função de envio. Pode ser usado para alguma outra função, por exemplo, chamar uma função JavaScript ao clicar.

```php
$form->addButton('raise', 'Aumentar salário')
	->setHtmlAttribute('onclick', 'raiseSalary()');
```


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

Adiciona um botão de envio na 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, é possível descobrir qual foi clicado usando `$form['submit']->isSubmittedBy()`.


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

Adiciona um subformulário (classe [Container|api:Nette\Forms\Container]), ou seja, um contêiner, ao qual é possível adicionar outros elementos da mesma forma que os adicionamos ao formulário. Os métodos `setDefaults()` ou `getValues()` também funcionam.

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

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

Os dados enviados retornam como uma estrutura multidimensional:

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


Visão geral das configurações
=============================

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

.[table-form-methods language-php]
| `setDefaultValue($value)`	| define o valor padrão
| `getValue()` 				| obtém o valor atual
| `setOmitted()` 			| [#Omissão de valor]
| `setDisabled()` 			| [#Desativação de elementos]

Renderização:
.[table-form-methods language-php]
| `setCaption($caption)`	| altera o rótulo do elemento
| `setTranslator($translator)` | define o [tradutor |rendering#Tradução]
| `setHtmlAttribute($name, $value)` | define o [atributo HTML |rendering#Atributos HTML] 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)` | [configurações para renderização |rendering#Options]

Validação:
.[table-form-methods language-php]
| `setRequired()` 			| [elemento obrigatório |validation]
| `addRule()` 				| define a [regra de validação |validation#Regras]
| `addCondition()`, `addConditionOn()` | define a [condição de validação |validation#Condições]
| `addError($message)`		| [passagem de mensagem de erro |validation#Erros durante o processamento]

Para os elementos `addText()`, `addPassword()`, `addTextArea()`, `addEmail()`, `addInteger()`, podem ser chamados os seguintes métodos:

.[table-form-methods language-php]
| `setNullable()` 			| define se getValue() retorna `null` em vez de string vazia
| `setEmptyValue($value)`	| define um valor especial que é considerado uma string vazia
| `setMaxLength($length)`	| define o número máximo de caracteres permitidos
| `addFilter($filter)`		| [modificação da entrada |validation#Modificação da entrada]


Omissão de valor
================

Se o valor preenchido pelo usuário não nos interessa, podemos omiti-lo do resultado do método `$form->getValues()` ou dos dados passados para os handlers usando `setOmitted()`. Isso é útil para várias senhas de verificação, elementos antispam, etc.

```php
$form->addPassword('passwordVerify', 'Senha para verificação:')
	->setRequired('Por favor, digite a senha novamente para verificação')
	->addRule($form::Equal, 'As senhas não coincidem', $form['password'])
	->setOmitted();
```


Desativação de elementos
========================

Elementos podem ser desativados usando `setDisabled()`. Tal elemento não pode ser editado pelo usuário.

```php
$form->addText('username', 'Nome de usuário:')
	->setDisabled();
```

Elementos desativados não são enviados pelo navegador para o servidor, portanto, você não os encontrará nos dados retornados pela função `$form->getValues()`. No entanto, se você definir `setOmitted(false)`, o Nette incluirá seu valor padrão nesses dados.

Ao chamar `setDisabled()`, por razões de segurança, **o valor do elemento é apagado**. Se você estiver definindo um valor padrão, é necessário fazê-lo após desativá-lo:

```php
$form->addText('username', 'Nome de usuário:')
	->setDisabled()
	->setDefaultValue($userName);
```

Uma alternativa aos elementos desativados são elementos com o atributo HTML `readonly`, que o navegador envia para o servidor. Embora o elemento seja apenas para leitura, é **importante notar** que seu valor ainda pode ser modificado ou falsificado por um invasor.


Elementos personalizados
========================

Além da ampla gama de elementos de formulário embutidos, você pode adicionar elementos personalizados ao formulário desta forma:

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

.[note]
O formulário é um descendente da classe [Container |component-model:#Container] e os elementos individuais são descendentes de [Component |component-model:#Component].

Existe uma maneira de definir novos métodos de formulário para adicionar elementos personalizados (por exemplo, `$form->addZip()`). São os chamados métodos de extensão. A desvantagem é que a sugestão nos editores não funcionará para eles.

```php
use Nette\Forms\Container;

// adicionamos o 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, 'Pelo menos 5 números', '[0-9]{5}');
});

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


Elementos de baixo nível
========================

Também é possível usar elementos que escrevemos apenas no template e não os adicionamos ao formulário com algum dos métodos `$form->addXyz()`. Por exemplo, ao listar registros do banco de dados sem saber antecipadamente quantos serão e quais serão seus IDs, e queremos exibir uma caixa de seleção ou botão de opção para cada linha, basta codificá-lo no template:

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

E após o envio, obtemos o valor:

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

onde o primeiro parâmetro é o tipo do elemento (`DataFile` para `type=file`, `DataLine` para entradas de linha única como `text`, `password`, `email`, etc. e `DataText` para todos os outros) e o segundo parâmetro `sel[]` corresponde ao atributo HTML name. O tipo do elemento pode ser combinado com o valor `DataKeys`, que preserva as chaves dos elementos. Isso é especialmente útil para `select`, `radioList` e `checkboxList`.

O essencial é que `getHttpData()` retorna um valor sanitizado, neste caso, será sempre um array de strings UTF-8 válidas, independentemente do que um invasor tente enviar ao servidor. É análogo ao trabalho direto com `$_POST` ou `$_GET`, mas com a diferença essencial de que sempre retorna dados limpos, como você está acostumado com os elementos padrão dos formulários Nette.

Elementos de Formulário

Visão geral dos elementos de formulário padrão.

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

Adiciona um campo de texto de linha única (classe TextInput). Se o usuário não preencher o campo, retorna uma string vazia '', ou usando setNullable() pode-se especificar que retorne null.

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

Valida automaticamente UTF-8, remove espaços à esquerda e à direita e remove quebras de linha que um invasor poderia enviar.

O comprimento máximo pode ser limitado usando setMaxLength(). Modificar o valor inserido pelo usuário é possível com addFilter().

Usando setHtmlType(), é possível alterar o caractere visual do campo de texto para tipos como search, tel ou url, veja a especificação. Lembre-se que a alteração do tipo é apenas visual e não substitui a função de validação. Para o tipo url, é apropriado adicionar uma regra URL de validação específica.

Para outros tipos de entrada, como number, range, email, date, datetime-local, time e color, use métodos especializados como addInteger, addFloat, addEmail addDate, addTime, addDateTime e addColor, que garantem a validação do lado do servidor. Os tipos month e week ainda não são totalmente suportados em todos os navegadores.

Ao elemento pode ser definido o chamado empty-value, que é algo como um valor padrão, mas se o usuário não o alterar, o elemento retorna uma string vazia ou null.

$form->addText('phone', 'Telefone:')
	->setHtmlType('tel')
	->setEmptyValue('+55');

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

Adiciona um campo para inserir texto multilinha (classe TextArea). Se o usuário não preencher o campo, retorna uma string vazia '', ou usando setNullable() pode-se especificar que retorne null.

$form->addTextArea('note', 'Nota:')
	->addRule($form::MaxLength, 'A nota é muito longa', 10000);

Valida automaticamente UTF-8 e normaliza os separadores de linha para \n. Ao contrário do campo de entrada de linha única, não ocorre remoção de espaços.

O comprimento máximo pode ser limitado usando setMaxLength(). Modificar o valor inserido pelo usuário é possível com addFilter(). É possível definir o chamado empty-value usando setEmptyValue().

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

Adiciona um campo para inserir um número inteiro (classe TextInput). Retorna um inteiro ou null se o usuário não inserir nada.

$form->addInteger('year', 'Ano:')
	->addRule($form::Range, 'O ano deve estar no intervalo de %d a %d.', [1900, 2023]);

O elemento é renderizado como <input type="number">. Usando o método setHtmlType(), é possível alterar o tipo para range para exibição na forma de um controle deslizante, ou para text, se preferir um campo de texto padrão sem o comportamento especial do tipo number.

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

Adiciona um campo para inserir um número decimal (classe TextInput). Retorna um float ou null se o usuário não inserir nada.

$form->addFloat('level', 'Nível:')
	->setDefaultValue(0)
	->addRule($form::Range, 'O nível deve estar no intervalo de %d a %d.', [0, 100]);

O elemento é renderizado como <input type="number">. Usando o método setHtmlType(), é possível alterar o tipo para range para exibição na forma de um controle deslizante, ou para text, se preferir um campo de texto padrão sem o comportamento especial do tipo number.

Nette e o navegador Chrome aceitam tanto vírgula quanto ponto como separador decimal. Para que essa funcionalidade esteja disponível também no Firefox, é recomendado definir o atributo lang para o elemento específico ou para a página inteira, por exemplo, <html lang="pt-BR">.

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

Adiciona um campo para inserir um endereço de e-mail (classe TextInput). Se o usuário não preencher o campo, retorna uma string vazia '', ou usando setNullable() pode-se especificar que retorne null.

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

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

O comprimento máximo pode ser limitado usando setMaxLength(). Modificar o valor inserido pelo usuário é possível com addFilter(). É possível definir o chamado empty-value usando setEmptyValue().

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

Adiciona um campo para inserir uma senha (classe TextInput).

$form->addPassword('password', 'Senha:')
	->setRequired()
	->addRule($form::MinLength, 'A senha deve ter pelo menos %d caracteres', 8)
	->addRule($form::Pattern, 'Deve conter um dígito', '.*[0-9].*');

Ao reexibir o formulário, o campo estará vazio. Valida automaticamente UTF-8, remove espaços à esquerda e à direita e remove quebras de linha que um invasor poderia enviar.

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

Adiciona uma caixa de seleção (classe Checkbox). Retorna o valor true ou false, dependendo se está marcada.

$form->addCheckbox('agree', 'Concordo com os termos')
	->setRequired('É necessário concordar com os termos');

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

Adiciona caixas de seleção para escolher vários itens (classe CheckboxList). Retorna um array das chaves dos itens selecionados. O método getSelectedItems() retorna os valores em vez das chaves.

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

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método setItems().

Usando setDisabled(['r', 'g']), é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se os itens selecionados estão realmente entre os oferecidos e não foram desativados. O método getRawValue() permite obter os itens enviados sem essa importante verificação.

Ao definir os itens selecionados padrão, também verifica se eles estão entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando checkDefaultValue(false).

Se você enviar o formulário pelo método GET, pode escolher um método de transmissão de dados mais compacto, que economiza o tamanho da query string. Ele é ativado definindo o atributo HTML do formulário:

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

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

Adiciona botões de opção (classe RadioList). Retorna a chave do item selecionado, ou null se o usuário não selecionou nada. O método getSelectedItem() retorna o valor em vez da chave.

$sex = [
	'm' => 'masculino',
	'f' => 'feminino',
];
$form->addRadioList('gender', 'Sexo:', $sex);

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método setItems().

Usando setDisabled(['m', 'f']), é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se o item selecionado está realmente entre os oferecidos e não foi desativado. O método getRawValue() permite obter o item enviado sem essa importante verificação.

Ao definir o item selecionado padrão, também verifica se ele está entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando checkDefaultValue(false).

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

Adiciona uma caixa de seleção (classe SelectBox). Retorna a chave do item selecionado, ou null se o usuário não selecionou nada. O método getSelectedItem() retorna o valor em vez da chave.

$countries = [
	'BR' => 'Brasil',
	'PT' => 'Portugal',
	'GB' => 'Reino Unido',
];

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

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método setItems(). Os itens também podem ser um array bidimensional:

$countries = [
	'Europa' => [
		'CZ' => 'República Tcheca',
		'SK' => 'Eslováquia',
		'GB' => 'Reino Unido',
	],
	'CA' => 'Canadá',
	'US' => 'EUA',
	'?'  => 'outro',
];

Nas caixas de seleção, o primeiro item geralmente tem um significado especial, servindo como um prompt para ação. Para adicionar tal item, use o método setPrompt().

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

Usando setDisabled(['CZ', 'SK']), é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se o item selecionado está realmente entre os oferecidos e não foi desativado. O método getRawValue() permite obter o item enviado sem essa importante verificação.

Ao definir o item selecionado padrão, também verifica se ele está entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando checkDefaultValue(false).

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

Adiciona uma caixa de seleção para escolher vários itens (classe MultiSelectBox). Retorna um array das chaves dos itens selecionados. O método getSelectedItems() retorna os valores em vez das chaves.

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

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método setItems(). Os itens também podem ser um array bidimensional.

Usando setDisabled(['CZ', 'SK']), é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se os itens selecionados estão realmente entre os oferecidos e não foram desativados. O método getRawValue() permite obter os itens enviados sem essa importante verificação.

Ao definir os itens selecionados padrão, também verifica se eles estão entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando checkDefaultValue(false).

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

Adiciona um campo para upload de arquivo (classe UploadControl). Retorna um objeto FileUpload, mesmo que o usuário não tenha enviado nenhum arquivo, o que pode ser verificado pelo método FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'O avatar deve ser JPEG, PNG, GIF, WebP ou AVIF.')
	->addRule($form::MaxFileSize, 'O tamanho máximo é 1 MB.', 1024 * 1024 /* 1 MB em bytes */);

Se o arquivo não for carregado corretamente, o formulário não é enviado com sucesso e um erro é exibido. Ou seja, em caso de envio bem-sucedido, não é necessário verificar o método FileUpload::isOk().

Nunca confie no nome original do arquivo retornado pelo método FileUpload::getName(), o cliente pode ter enviado um nome de arquivo malicioso com a intenção de danificar ou hackear sua aplicação.

As regras MimeType e Image detectam o tipo necessário com base na assinatura do arquivo e não verificam sua integridade. Se a imagem está danificada pode ser verificado, por exemplo, tentando carregá-la.

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

Adiciona um campo para upload de vários arquivos de uma vez (classe UploadControl). Retorna um array de objetos FileUpload. O método FileUpload::hasFile() em cada um deles retornará true.

$form->addMultiUpload('files', 'Arquivos:')
	->addRule($form::MaxLength, 'No máximo %d arquivos podem ser enviados', 10);

Se algum arquivo não for carregado corretamente, o formulário não é enviado com sucesso e um erro é exibido. Ou seja, em caso de envio bem-sucedido, não é necessário verificar o método FileUpload::isOk().

Nunca confie nos nomes originais dos arquivos retornados pelo método FileUpload::getName(), o cliente pode ter enviado um nome de arquivo malicioso com a intenção de danificar ou hackear sua aplicação.

As regras MimeType e Image detectam o tipo necessário com base na assinatura do arquivo e não verificam sua integridade. Se a imagem está danificada pode ser verificado, por exemplo, tentando carregá-la.

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

Adiciona um campo que permite ao usuário inserir facilmente uma data composta por ano, mês e dia (classe DateTimeControl).

Como valor padrão, aceita objetos que implementam a interface DateTimeInterface, uma string com a hora, ou um número representando um timestamp UNIX. O mesmo se aplica aos argumentos das regras Min, Max ou Range, que definem a data mínima e máxima permitida.

$form->addDate('date', 'Data:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'A data deve ter pelo menos um mês.', new DateTime('-1 month'));

Por padrão, retorna um objeto DateTimeImmutable, com o método setFormat() você pode especificar o formato de texto ou timestamp:

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

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

Adiciona um campo que permite ao usuário inserir facilmente uma hora composta por horas, minutos e opcionalmente segundos (classe DateTimeControl).

Como valor padrão, aceita objetos que implementam a interface DateTimeInterface, uma string com a hora, ou um número representando um timestamp UNIX. Desses inputs, apenas a informação de tempo é utilizada, a data é ignorada. O mesmo se aplica aos argumentos das regras Min, Max ou Range, que definem a hora mínima e máxima permitida. Se o valor mínimo definido for maior que o máximo, cria-se um intervalo de tempo que ultrapassa a meia-noite.

$form->addTime('time', 'Hora:', withSeconds: true)
	->addRule($form::Range, 'A hora deve estar no intervalo de %d a %d.', ['12:30', '13:30']);

Por padrão, retorna um objeto DateTimeImmutable (com a data de 1º de janeiro do ano 1), com o método setFormat() você pode especificar o formato de texto:

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

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

Adiciona um campo que permite ao usuário inserir facilmente data e hora compostas por ano, mês, dia, horas, minutos e opcionalmente segundos (classe DateTimeControl).

Como valor padrão, aceita objetos que implementam a interface DateTimeInterface, uma string com a hora, ou um número representando um timestamp UNIX. O mesmo se aplica aos argumentos das regras Min, Max ou Range, que definem a data mínima e máxima permitida.

$form->addDateTime('datetime', 'Data e hora:')
	->setDefaultValue(new \DateTime)
	->addRule($form::Min, 'A data deve ter pelo menos um mês.', new \DateTime('-1 month'));

Por padrão, retorna um objeto DateTimeImmutable, com o método setFormat() você pode especificar o formato de texto ou timestamp:

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

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

Adiciona um campo para seleção de cor (classe ColorPicker). A cor é uma string no formato #rrggbb. Se o usuário não fizer a escolha, retorna a cor preta #000000.

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

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

Adiciona um campo oculto (classe HiddenField).

$form->addHidden('userid');

Usando setNullable(), pode-se definir que retorne null em vez de uma string vazia. Modificar o valor enviado é possível com addFilter().

Embora o elemento esteja oculto, é importante notar que o valor ainda pode ser modificado ou falsificado por um invasor. Sempre verifique e valide cuidadosamente todos os valores recebidos no lado do servidor para evitar riscos de segurança associados à manipulação de dados.

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

Adiciona um botão de envio (classe SubmitButton).

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

No formulário, é possível ter vários botões de envio:

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

Para descobrir qual deles foi clicado, use:

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

Se você não quiser validar o formulário inteiro ao pressionar o botão (por exemplo, para botões Cancelar ou Visualizar), use setValidationScope().

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

Adiciona um botão (classe Button) que não tem função de envio. Pode ser usado para alguma outra função, por exemplo, chamar uma função JavaScript ao clicar.

$form->addButton('raise', 'Aumentar salário')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

Adiciona um botão de envio na forma de uma imagem (classe ImageButton).

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

Ao usar vários botões de envio, é possível descobrir qual foi clicado usando $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Adiciona um subformulário (classe Container), ou seja, um contêiner, ao qual é possível adicionar outros elementos da mesma forma que os adicionamos ao formulário. Os métodos setDefaults() ou getValues() também funcionam.

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

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

Os dados enviados retornam como uma estrutura multidimensional:

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

Visão geral das configurações

Para todos os elementos, podemos chamar os seguintes métodos (visão geral completa na documentação da API):

setDefaultValue($value) define o valor padrão
getValue() obtém o valor atual
setOmitted() Omissão de valor
setDisabled() Desativação de elementos

Renderização:

setCaption($caption) altera o rótulo do elemento
setTranslator($translator) define o tradutor
setHtmlAttribute($name, $value) define o atributo HTML 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) configurações para renderização

Validação:

setRequired() elemento obrigatório
addRule() define a regra de validação
addCondition(), addConditionOn() define a condição de validação
addError($message) passagem de mensagem de erro

Para os elementos addText(), addPassword(), addTextArea(), addEmail(), addInteger(), podem ser chamados os seguintes métodos:

setNullable() define se getValue() retorna null em vez de string vazia
setEmptyValue($value) define um valor especial que é considerado uma string vazia
setMaxLength($length) define o número máximo de caracteres permitidos
addFilter($filter) modificação da entrada

Omissão de valor

Se o valor preenchido pelo usuário não nos interessa, podemos omiti-lo do resultado do método $form->getValues() ou dos dados passados para os handlers usando setOmitted(). Isso é útil para várias senhas de verificação, elementos antispam, etc.

$form->addPassword('passwordVerify', 'Senha para verificação:')
	->setRequired('Por favor, digite a senha novamente para verificação')
	->addRule($form::Equal, 'As senhas não coincidem', $form['password'])
	->setOmitted();

Desativação de elementos

Elementos podem ser desativados usando setDisabled(). Tal elemento não pode ser editado pelo usuário.

$form->addText('username', 'Nome de usuário:')
	->setDisabled();

Elementos desativados não são enviados pelo navegador para o servidor, portanto, você não os encontrará nos dados retornados pela função $form->getValues(). No entanto, se você definir setOmitted(false), o Nette incluirá seu valor padrão nesses dados.

Ao chamar setDisabled(), por razões de segurança, o valor do elemento é apagado. Se você estiver definindo um valor padrão, é necessário fazê-lo após desativá-lo:

$form->addText('username', 'Nome de usuário:')
	->setDisabled()
	->setDefaultValue($userName);

Uma alternativa aos elementos desativados são elementos com o atributo HTML readonly, que o navegador envia para o servidor. Embora o elemento seja apenas para leitura, é importante notar que seu valor ainda pode ser modificado ou falsificado por um invasor.

Elementos personalizados

Além da ampla gama de elementos de formulário embutidos, você pode adicionar elementos personalizados ao formulário desta forma:

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

O formulário é um descendente da classe Container e os elementos individuais são descendentes de Component.

Existe uma maneira de definir novos métodos de formulário para adicionar elementos personalizados (por exemplo, $form->addZip()). São os chamados métodos de extensão. A desvantagem é que a sugestão nos editores não funcionará para eles.

use Nette\Forms\Container;

// adicionamos o 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, 'Pelo menos 5 números', '[0-9]{5}');
});

// uso
$form->addZip('zip', 'CEP:');

Elementos de baixo nível

Também é possível usar elementos que escrevemos apenas no template e não os adicionamos ao formulário com algum dos métodos $form->addXyz(). Por exemplo, ao listar registros do banco de dados sem saber antecipadamente quantos serão e quais serão seus IDs, e queremos exibir uma caixa de seleção ou botão de opção para cada linha, basta codificá-lo no template:

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

E após o envio, obtemos o valor:

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

onde o primeiro parâmetro é o tipo do elemento (DataFile para type=file, DataLine para entradas de linha única como text, password, email, etc. e DataText para todos os outros) e o segundo parâmetro sel[] corresponde ao atributo HTML name. O tipo do elemento pode ser combinado com o valor DataKeys, que preserva as chaves dos elementos. Isso é especialmente útil para select, radioList e checkboxList.

O essencial é que getHttpData() retorna um valor sanitizado, neste caso, será sempre um array de strings UTF-8 válidas, independentemente do que um invasor tente enviar ao servidor. É análogo ao trabalho direto com $_POST ou $_GET, mas com a diferença essencial de que sempre retorna dados limpos, como você está acostumado com os elementos padrão dos formulários Nette.