Formulários com SQLFORM no Web2py

Sem dúvida um dos elementos chave de qualquer aplicação web é o formulário. Ele permite o envio de dados entre o usuário e o app.

Este elemento possui um mecanismo simples mas que pode se desdobrar para atender quase qualquer necessidade do programador.

No caso do Web2py, o Livro tem uma seção específica sobre o assunto. Nele são apresentadas as diversas maneiras de se criar e configurar formulários utilizando as ferramentas que o framework oferece.

E o meu favorito é o SQLFORM. O SQLFORM é sensacional. Com ele você pode criar um formulário mais rápido que porta na cara de Testemunha de Jeová.

A seguir vou mostrar alguns exemplos do que o SQLFORM é capaz de fazer.

Vamos supor que nossa aplicação terá uma opção para que os usuários submetam seu nome e email de contato para receber atualizações do projeto.

Considere a seguinte tabela no modelo:  

db.define_table('contatos',
Field('nome', 'string'),
Field('email', 'string'),
Field('dtcadastro', 'date'),
Field('status', 'string', requires=IS_IN_SET(['Ativo', 'Inativo'])))

A tabela contatos deve ser preenchida com o nome do usuário, o email, a data do cadastro e o status Ativo ou Inativo.

Utilizando o SQLFORM é possível criar um formulário para esta tabela com os seguintes comandos.

No controlador default.py:

def contatos():
    form = SQLFORM(db.contatos)
    if form.process().accepted:
        response.flash = 'Contato cadastrado!'
    return dict(form=form)

E na view default/contatos.html:  

{{extend 'layout.html'}}
{{=form}}

O resultado deve ficar semelhante a este:

Este simples formulário já é totalmente funcional. Preenchendo os dados corretamente, o contato será inserido na tabela contatos que criamos no banco de dados.

Porém, este formulário não está exatamente aceitável para nossa aplicação.

Em primeiro lugar, como a aplicação está em português, não faz sentido que o botão que envie os dados do formulário apareça em inglês, certo?

Isso é fácil de resolver e uma das formas de fazer isso é definir manualmente o nome que o botão submit do formulário deve exibir.

Para isso, vamos alterar a seguinte linha do controlador:

form = SQLFORM(db.contatos, submit_button='Salvar')

E o resultado disso é: 

Outro detalhe que precisa ser corrigido é que o formulário atribui como label dos campos de texto o mesmo nome dos campos definidos na tabela do banco de dados automaticamente. Mas não podemos deixar o campo se chamar Dtcadastro. Então vamos alterar isto também de forma bem simples.

Na realidade, podemos personalizar o nome de cada um dos campos do formulário utilizando um dicionário onde a chave (key) é o nome do campo na tabela e o valor (value) é o nome que queremos exibir.

Neste caso, o que queremos é isso:

form = SQLFORM(db.contatos, submit_button='Salvar',
               labels={'dtcadastro':'Data de Cadastro'})

Veja como fica:

Pensando bem, este formulário ainda não está bom.

Na realidade, temos informações desnecessárias sendo exibidas.

Para o funcionamento correto da nossa aplicação, precisamos saber o nome e o email de contato do usuário, bem como a data em que o cadastro foi feito e se este contato tem status ativo ou inativo.

Porém nem todas essas informações precisam ser fornecidas pelo usuário.

Obviamente a data de cadastro é a data em que este formulário é submetido, ou seja, sempre a data atual. Não há necessidade de questionar isso para o usuário. De fato, permitir que o usuário defina a data de cadastro pode se tornar um problema, uma vez que não há garantia de que o usuário irá preencher a data correta.

Seguindo esta linha de raciocínio, no momento em que o cadastro do contato é realizado, o status dele será sempre ativo. Não existe motivo para cadastrar um contato inativo. Esta opção só será útil após o cadastro ser realizado. Portanto, também não é preciso solicitar que o usuário preencha esta informação.

O SQLFORM cria o formulário automaticamente com todos os campos definidos na tabela.

Em uma aplicação mais complexa, seria interessante definir na tabela apenas os campos que serão necessários no formulário e definir uma segunda tabela, com relacionamento de um para um, com os dados adicionais que são definidos no back-end.

No nosso exemplo, podemos definir que o SQLFORM crie o formulário apenas com alguns campos da tabela.

Veja o exemplo:

form = SQLFORM(db.contatos, submit_button='Salvar',
               fields=['nome', 'email'])

Observe que eu removi o argumento que alterava a label do campo Dtcadastro uma vez que este campo não fará mais parte do formulário.

Podemos definir quais campos da tabela farão parte do formulário utilizando o argumento fields que recebe uma lista de strings conforme exemplo acima.

O formulário ficou assim:

Bom. Agora que o formulário recebe apenas os dados relevantes do usuário, ainda precisamos definir como vamos inserir as informações que ficaram de fora.

Existem várias formas de fazer isso.

Neste exemplo, vamos criar uma função no modelo que será chamada imediatamente após os dados do formulário serem submetidos. Esta função será responsável por completar o cadastro do contato.

Desta forma, podemos reutilizar a função em outras situações.

Veja como ficou a função que defini no modelo:

from datetime import date

def completarCadastro(idContato):
    try:
        hoje = date.today()
        db(db.contatos.id == idContato).update(dtcadastro=hoje, status='Ativo')
        return True
    except:
        return False

Ou seja, a função recebe o id do contato e realiza um update neste registro na tabela do banco de dados para completar o cadastro com as informações padrão.

O controlador ficou assim:

def contatos():
    form = SQLFORM(db.contatos, submit_button='Salvar', 
               fields=['nome', 'email'])
    if form.process().accepted and completarCadastro(form.vars.id):
        response.flash = 'Contato cadastrado!'
    elif form.errors:
        response.flash = 'Erro ao cadastrar! Verifique os dados.'
    return dict(form=form)

A aplicação considera o cadastro bem-sucedido se o formulário for submetido sem erros E se a função que completa o cadastro retornar True.

Note que para este exemplo não incluí nenhuma validação nos campos.

Este assunto será abordado em um próximo post.

Tem Mais

Além de todas essas possibilidades que o SQLFORM do Web2py oferece, às vezes ainda precisamos ter um pouco mais de controle sobre a maneira como o formulário é exibido na view. 
Se você analisar o código fonte do formulário gerado pelo SQLFORM, irá notar que ele gera ids e classes para os elementos do formulário automaticamente, ou você mesmo pode definir utilizando o argumento _class, por exemplo.
Mas se tudo isso ainda não for suficiente para obter o resultado desejado na view, ainda é possível construir o formulário todo "na mão".

{{extend 'layout.html'}}

{{=form.custom.begin}}
<label for="Nome"><span class="formContatoNome">Nome</span></label>
    {{=form.custom.widget.nome}}
<br />

<label for="Email"><span class="formContatoEmail">Email</span></label>
    {{=form.custom.widget.email}}
<br />

<input id="formContatoBt" name="ok" type="submit" value="Salvar" />
  <br />

{{=form.custom.end}}

Utilizando o form.custom é possível definir manualmente cada aspecto do formulário sem precisar alterar nada do que foi definido no controle ou no modelo. Basta posicionar os campos de texto nos locais desejados da forma como mostrada no exemplo.

Por enquanto é isso.

Mais informações e detalhes sobre o maravilhoso SQLFORM você encontra no Livro.