Tratando POST no Web Server do ESP8266

Nesse post vamos continuar o assunto do post anterior (se você ainda não leu clique aqui) e, aproveitando o mesmo código, vamos implementar o tratamento POST de envio de formulário.

Para quem não conhece bem HTML e seus meandros, isso significa que vamos criar um formulário conforme a imagem abaixo e enviar os dados preenchidos para serem tratados por uma função e apresentados em uma outra tela.

Podemos ver no formulário que temos um campo de texto e um botão enviar. É um exemplo bem simples, mas mostra o potencial do ESP8266, utilizando a biblioteca WebServer.

Repare que diferente da página principal, esse formulário chamamos no endereço http://192.168.0.125/form

Lembra do código do post anterior que eu expliquei como o ESP8266 trata as URLs? Vejamos novamente:

Através da função server.on() dizemos que ao chamar a URL raiz, ou seja http://192.168.0.125/, o código executado é o da função handleRoot().

Pois bem, precisamos agora acrescentar um tratamento para a URL http://192.168.0.125/form, então vamos criar outra função server.on(), mas agora vamos definir também o método que a URL vai tratar.

O que significa o método da URL? Vamos dizer que existem formas diferentes de se interagir com as URLs. Não quero entrar nos detalhes do protocolo HTTP que regimenta essa parte, mas de forma resumida, quando chamamos uma URL, digitando no Navegador de Internet, estamos executando essencialmente um método chamado GET. Agora, quando utilizamos um formulário, temos a possibilidade de instruir o Navegador de Internet, via código, de fazer uma chamada pelo método POST.

Ambos métodos GET e POST operam de forma similar e aceitam passagem de parâmetros entre uma chamada e outra. Essa é a forma que o HTML envia dados de uma página para outra. Isso acontece pois o protocolo HTTP, que é o responsável por enviar HTML de um lado para outro, não guarda estado das coisas, não armazenando nada. Então as informações precisam ser enviadas e recebidas como se fossem um anexo de um e-mail (veremos como enviar e receber e-mail pelo ESP8266 em outro post).

Para nosso exemplo, vamos considerar que o método GET será tratado pela função formularioChamada() e que o POST será tratado pela função formularioEnviado(), então precisamos escrever o seguinte código:

Repare que utilizamos duas vezes a função server.on() para a mesma URL "/form", mas no segundo argumento diferenciamos as chamadas pelos métodos. Para isso utilizamos as macros HTTP_GET e HTTP_POST. E no terceiro parâmetro passamos a função que deve ser executada.

A função formularioChamada() se parece bastante com a handleRoot(), que apresenta a página inicial, mas dessa vez adicionamos uma Tag Form para montar e configurar um formulário com método POST de envio.

Os pontos importantes desse código são o método que foi configurado para  POST e o 'action' que foi configurado para '/form'. Para todos os efeitos a URL é a mesma, mas como o método é diferente, e quando o usuário clicar no botão Enviar, que é montado pela tag Input com o tipo Submit, a função que será chamada será a formularioEnviado(), pois configuramos isso mais acima, na função server.on().

Vamos ver agora alguns detalhes da função formularioEnviado(), que não vou colocar na integra aqui, pois utiliza os mesmos princípios das outras, mas o que muda é que adicionamos um tratamento para manipular os parâmetros que chegaram do envio do formulário.

O interessante da biblioteca ESP8266WebServer.h que utilizamos aqui é que ela traz vários métodos auxiliares para tratarmos parâmetros passados entre uma página HTML e outra. Vejamos alguns:

• String arg(String name); -- recupera o valor do campo pelo nome do parâmetro
• String arg(int i); -- recupera o valor do campo pelo índice do parâmetro
• String argName(int i); -- recupera o nome do campo pelo índice do parâmetro
• int args(); -- recupera a quantidade de parâmetros
• bool hasArg(String name); -- verifica se o parâmetro existe

No código acima temos:

1. 1) Chamada da função server.hasArg() com o nome do campo de texto para saber se existe esse parâmetro
2. 2) Chamada da função server.arg() para efetivamente recuperar o valor que foi digitado no campo de texto
3. 3) Repare que criamos outro formulário, mas dessa vez com o método GET, para adicionar um botão de 'Voltar', que ao ser clicado vai chamar a URL '/form', mas com o método GET, fazendo com que a função formularioChamada() seja evocada, apresentando novamente a tela anterior, ou seja, a tela do formulário. Tudo isso é regimentado pela configuração que fizemos na função server.on()

O resultado final deve se parecer com o da imagem abaixo. Eu digitei "teste de envio" na caixa de texto, e esse valor foi concatenado conforme vimos no código acima e apresentado no HTML de resposta ao form, ou seja, o HTML que trata o POST.

É isso aí pessoal! Experimentem outros tipos de campos do HTML, como checkboxes, listas de seleção etc, e também outros métodos de tratamentos dos campos, como o server.args(), que retorna a quantidade de campos enviados pelo formulário. Experimente esse método e veja que no nosso formulário existem 2 campos, pois o botão é considerado um dos parâmetros passados pelo POST de uma página para outra.

Baixe o código completo clicando aqui!

Até o próximo artigo da série!

Abraços,

Renato Aloi