Formulários utilizados autônomos
********************************

.[perex]
Os Formulários Nette facilitam drasticamente a criação e o processamento de formulários web. Você pode usá-los em suas aplicações completamente por conta própria sem o resto da estrutura, o que demonstraremos neste capítulo.

Entretanto, se você utiliza o aplicativo Nette e apresentadores, há um guia para você: [formulários em apresentadores |in-presenter].


Primeiro Formulário .[#toc-first-form]
======================================

Tentaremos escrever um simples formulário de registro. Seu código será parecido com este ("código completo":https://gist.github.com/dg/370a7e3094d9ba9a9e913b8e2a2dc851):

```php
use Nette\Forms\Form;

$form = new Form;
$form->addText('name', 'Name:');
$form->addPassword('password', 'Password:');
$form->addSubmit('send', 'Sign up');
```

E vamos renderizá-lo:

```php
$form->render();
```

e o resultado deve ser parecido com este:

[* form-en.webp *]

O formulário é um objeto da classe `Nette\Forms\Form` (a classe `Nette\Application\UI\Form` é usada em apresentadores). Adicionamos o nome dos controles, a senha e o botão de envio a ele.

Agora vamos reavivar a forma. Perguntando `$form->isSuccess()`, descobriremos se o formulário foi enviado e se foi preenchido de forma válida. Se for o caso, despejaremos os dados. Após a definição do formulário, acrescentaremos:

```php
if ($form->isSuccess()) {
	echo 'O formulário foi preenchido e enviado corretamente';
	$data = $form->getValues();
	// $data->name contém nome
	// $data->password contém a senha
	var_dump($data);
}
```

O método `getValues()` retorna os dados enviados na forma de um objeto [ArrayHash |utils:arrays#ArrayHash]. Mostraremos como mudar isso [mais tarde |#Mapping to Classes]. A variável `$data` contém as chaves `name` e `password` com os dados inseridos pelo usuário.

Normalmente, enviamos os dados diretamente para processamento posterior, que pode ser, por exemplo, inserido no banco de dados. Entretanto, pode ocorrer um erro durante o processamento, por exemplo, o nome de usuário já está tomado. Neste caso, passamos o erro de volta ao formulário usando `addError()` e deixamos que ele seja redesenhado, com uma mensagem de erro:

```php
$form->addError('Sorry, username is already in use.');
```

Após o processamento do formulário, redirecionaremos para a página seguinte. Isto evita que o formulário seja reapresentado involuntariamente clicando no botão *refresh*, *back*, ou movendo o histórico do navegador.

Por padrão, o formulário é enviado usando o método POST para a mesma página. Ambos podem ser modificados:

```php
$form->setAction('/submit.php');
$form->setMethod('GET');
```

E isso é tudo :-) Temos uma forma funcional e perfeitamente [segura |#Vulnerability Protection].

Tente adicionar mais [controles de formulário |controls].


Acesso aos controles .[#toc-access-to-controls]
===============================================

A forma e seus controles individuais são chamados de componentes. Eles criam uma árvore de componentes, onde a raiz é a forma. Você pode acessar os controles individuais da seguinte forma:

```php
$input = $form->getComponent('name');
// sintaxe alternativa: $input = $form['name'];

$button = $form->getComponent('send');
// sintaxe alternativa: $button = $form['send'];
```

Os controles são removidos com o uso de controles não ajustados:

```php
unset($form['name']);
```


Regras de validação .[#toc-validation-rules]
============================================

A palavra *valido* foi usada aqui, mas o formulário ainda não tem regras de validação. Vamos corrigi-lo.

O nome será obrigatório, portanto o marcaremos com o método `setRequired()`, cujo argumento é o texto da mensagem de erro que será exibida se o usuário não a preencher. Se não for apresentado nenhum argumento, será utilizada a mensagem de erro padrão.

```php
$form->addText('name', 'Name:')
	->setRequired('Please enter a name.');
```

Tente enviar o formulário sem o nome preenchido e você verá que uma mensagem de erro é exibida e o navegador ou servidor irá rejeitá-lo até que você o preencha.

Ao mesmo tempo, você não poderá enganar o sistema digitando apenas espaços na entrada, por exemplo. De jeito nenhum. A Nette apara automaticamente os espaços em branco à esquerda e à direita. Experimente. É algo que você deve fazer sempre com cada entrada de linha, mas muitas vezes é esquecido. A Nette o faz automaticamente. (Você pode tentar enganar os formulários e enviar uma cadeia de várias linhas como o nome. Mesmo aqui, Nette não será enganado e as quebras de linha mudarão para espaços).

O formulário é sempre validado no lado do servidor, mas a validação JavaScript também é gerada, o que é rápido e o usuário sabe do erro imediatamente, sem ter que enviar o formulário para o servidor. Isto é tratado pelo script `netteForms.js`.
Acrescente-o à página:

```latte
<script src="https://unpkg.com/nette-forms@3"></script>
```

Se você olhar no código fonte da página com formulário, você pode notar que Nette insere os campos necessários em elementos com uma classe CSS `required`. Tente adicionar o seguinte estilo ao modelo, e a etiqueta "Name" (Nome) será vermelha. Elegantemente, marcamos os campos requeridos para os usuários:

```latte
<style>
.required label { color: maroon }
</style>
```

Regras de validação adicionais serão adicionadas pelo método `addRule()`. O primeiro parâmetro é a regra, o segundo é novamente o texto da mensagem de erro e o argumento da regra de validação opcional pode seguir. O que isso significa?

O formulário terá outra entrada opcional *idade* com a condição, que deve ser um número (`addInteger()`) e em certos limites (`$form::Range`). E aqui usaremos o terceiro argumento de `addRule()`, a própria faixa:

```php
$form->addInteger('age', 'Age:')
	->addRule($form::Range, 'You must be older 18 years and be under 120.', [18, 120]);
```

.[tip]
Se o usuário não preencher o campo, as regras de validação não serão verificadas, pois o campo é opcional.

Obviamente, há espaço para uma pequena refatoração. Na mensagem de erro e no terceiro parâmetro, os números são listados em duplicata, o que não é o ideal. Se estivéssemos criando um [formulário multilíngüe |rendering#translating] e a mensagem contendo números tivesse que ser traduzida para vários idiomas, seria mais difícil mudar os valores. Por este motivo, podem ser utilizados caracteres substitutos `%d`:

```php
	->addRule($form::Range, 'You must be older %d years and be under %d.', [18, 120]);
```

Vamos voltar ao campo *password*, torná-lo *requerido*, e verificar o comprimento mínimo da senha (`$form::MinLength`), novamente usando os caracteres substitutos na mensagem:

```php
$form->addPassword('password', 'Password:')
	->setRequired('Pick a password')
	->addRule($form::MinLength, 'Your password has to be at least %d long', 8);
```

Adicionaremos um campo `passwordVerify` ao formulário, onde o usuário digita a senha novamente, para verificação. Usando regras de validação, verificamos se as duas senhas são as mesmas (`$form::Equal`). E como argumento, fazemos uma referência à primeira senha usando [colchetes |#Access to Controls]:

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

Usando `setOmitted()`, marcamos um elemento cujo valor realmente não nos interessa e que existe apenas para validação. Seu valor não é passado para `$data`.

Temos um formulário totalmente funcional com validação em PHP e JavaScript. As capacidades de validação da Nette são muito mais amplas, você pode criar condições, exibir e ocultar partes de uma página de acordo com elas, etc. Você pode descobrir tudo no capítulo sobre [validação de formulários |validation].


Valores por default .[#toc-default-values]
==========================================

Muitas vezes definimos valores padrão para controles de formulários:

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

Muitas vezes é útil definir valores padrão para todos os controles ao mesmo tempo. Por exemplo, quando o formulário é usado para editar registros. Nós lemos o registro do banco de dados e o definimos como valores padrão:

```php
//$row = ['name' => 'John', 'age' => '33', /* ... */];
$form->setDefaults($row);
```

Ligue para `setDefaults()` após definir os controles.


Renderização do formulário .[#toc-rendering-the-form]
=====================================================

Por padrão, o formulário é apresentado como uma tabela. Os controles individuais seguem as diretrizes básicas de acessibilidade da web. Todas as etiquetas são geradas como `<label>` e estão associados às suas entradas, clicando na etiqueta move o cursor sobre a entrada.

Podemos definir quaisquer atributos HTML para cada elemento. Por exemplo, acrescente um espaço reservado:

```php
$form->addInteger('age', 'Age:')
	->setHtmlAttribute('placeholder', 'Please fill in the age');
```

Há realmente muitas maneiras de renderizar uma forma, por isso é um [capítulo |rendering] dedicado [à renderização |rendering].


Mapeamento para as classes .[#toc-mapping-to-classes]
=====================================================

Vamos voltar para o processamento de dados. O método `getValues()` devolveu os dados submetidos como um objeto `ArrayHash`. Como esta é uma classe genérica, algo como `stdClass`, nos faltará alguma conveniência ao trabalhar com ela, como preenchimento de código para propriedades em editores ou análise de código estático. Isto poderia ser resolvido tendo uma classe específica para cada formulário, cujas propriedades representam os controles individuais. Por exemplo, a classe

```php
class RegistrationFormData
{
	public string $name;
	public int $age;
	public string $password;
}
```

Como alternativa, você pode usar o construtor:

```php
class RegistrationFormData
{
	public function __construct(
		public string $name,
		public int $age,
		public string $password,
	) {
	}
}
```

As propriedades da classe de dados também podem ser enums e serão mapeadas automaticamente. .{data-version:3.2.4}

Como dizer à Nette para nos retornar dados como objetos desta classe? Mais fácil do que você pensa. Tudo que você precisa fazer é especificar o nome da classe ou objeto a ser hidratado como um parâmetro:

```php
$data = $form->getValues(RegistrationFormData::class);
$name = $data->name;
```

Um `'array'` também pode ser especificado como um parâmetro, e então os dados retornam como uma matriz.

Se as formas consistem em uma estrutura de vários níveis composta de recipientes, crie uma classe separada para cada um deles:

```php
$form = new Form;
$person = $form->addContainer('person');
$person->addText('firstName');
/* ... */

class PersonFormData
{
	public string $firstName;
	public string $lastName;
}

class RegistrationFormData
{
	public PersonFormData $person;
	public int $age;
	public string $password;
}
```

O mapeamento então sabe pelo tipo de propriedade `$person` que deve mapear o container para a classe `PersonFormData`. Se a propriedade contiver um conjunto de containers, forneça o tipo `array` e passe a classe a ser mapeada diretamente para o container:

```php
$person->setMappedType(PersonFormData::class);
```

Você pode gerar uma proposta para a classe de dados de um formulário usando o método `Nette\Forms\Blueprint::dataClass($form)`, que a imprimirá na página do navegador. Em seguida, basta clicar para selecionar e copiar o código em seu projeto. .{data-version:3.1.15}


Botões de submissão múltipla .[#toc-multiple-submit-buttons]
============================================================

Se o formulário tiver mais de um botão, geralmente precisamos distinguir qual deles foi pressionado. O método `isSubmittedBy()` do botão nos devolve esta informação:

```php
$form->addSubmit('save', 'Save');
$form->addSubmit('delete', 'Delete');

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

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

Não omitir o `$form->isSuccess()` para verificar a validade dos dados.

Quando um formulário é apresentado com a chave <kbd>Enter</kbd>, ele é tratado como se tivesse sido apresentado com o primeiro botão.


Proteção contra vulnerabilidades .[#toc-vulnerability-protection]
=================================================================

Nette Framework coloca um grande esforço para ser seguro e como os formulários são a entrada mais comum dos usuários, os formulários Nette são tão bons quanto impenetráveis.

Além de proteger os formulários contra ataques de vulnerabilidades conhecidas, como o [Cross-Site Scripting (XSS) |nette:glossary#cross-site-scripting-xss] e o [Cross-Site Request Forgery (CSRF |nette:glossary#cross-site-request-forgery-csrf] ), ele faz muitas pequenas tarefas de segurança que você não precisa mais pensar.

Por exemplo, ele filtra todos os caracteres de controle das entradas e verifica a validade da codificação UTF-8, para que os dados do formulário estejam sempre limpos. Para caixas de seleção e listas de rádio, ele verifica que os itens selecionados foram realmente dos oferecidos e que não houve falsificação. Já mencionamos que para entrada de texto de uma linha, ele remove caracteres de fim de linha que um atacante poderia enviar para lá. Para entradas de várias linhas, ele normaliza os caracteres de fim de linha. E assim por diante.

Nette corrige vulnerabilidades de segurança para você que a maioria dos programadores não tem idéia de que existem.

O referido ataque do CSRF é que um agressor atrai a vítima para visitar uma página que silenciosamente executa um pedido no navegador da vítima ao servidor onde a vítima está atualmente logada, e o servidor acredita que o pedido foi feito pela vítima à sua vontade. Portanto, a Nette impede que o formulário seja submetido via POST a partir de outro domínio. Se por algum motivo você quiser desligar a proteção e permitir que o formulário seja submetido a partir de outro domínio, use:

```php
$form->allowCrossOrigin(); // ATENÇÃO! Desliga a proteção!
```

Esta proteção utiliza um cookie SameSite chamado `_nss`. Portanto, crie um formulário antes de descarregar a primeira saída para que o cookie possa ser enviado.

A proteção de cookies do SameSite pode não ser 100% confiável, por isso é uma boa idéia ativar a proteção simbólica:

```php
$form->addProtection();
```

É fortemente recomendado aplicar esta proteção aos formulários em uma parte administrativa de seu pedido que altera dados sensíveis. A estrutura protege contra um ataque CSRF gerando e validando o token de autenticação que é armazenado em uma sessão (o argumento é a mensagem de erro mostrada se o token tiver expirado). É por isso que é necessário ter uma sessão iniciada antes de exibir o formulário. Na parte administrativa do site, a sessão normalmente já é iniciada, devido ao login do usuário.
Caso contrário, inicie a sessão com o método `Nette\Http\Session::start()`.

Portanto, temos uma rápida introdução aos formulários em Nette. Tente procurar no diretório de [exemplos |https://github.com/nette/forms/tree/master/examples] na distribuição para obter mais inspiração.