..
.. META INFORMATION OF TRANSLATION
..
..   $TranslationStatus: Done, waiting for revision $
..   $OriginalRevision: 11298 $
..   $TranslationAuthors: Robson Mendonça $
..
.. INFO OF THIS FILE (DO NOT EDIT! UPDATED BY SUBVERSION)
..
..   $HeadURL: http://django-l10n-portuguese.googlecode.com/svn/branches/docs-1.0.X/topics/forms/index.txt $
..   $LastChangedRevision: 572 $
..   $LastChangedBy: robsonmwoc $
..   $LastChangedDate: 2009-09-03 12:50:34 -0300 (Thu, 03 Sep 2009) $
..

.. _topics-forms-index:

===========================
Trabalhando com formulários
===========================

.. admonition:: Sobre este documento

    Este documento fornece uma introdução as funcionalidades de manipulação de
    formulários do Django. Para uma visão mais detalhada da API de forumulários,
    veja :ref:`ref-forms-api`. Para documentação de tipos de campos disponíveis,
    veja :ref:`ref-forms-fields`.

.. highlightlang:: html+django

``django.forms`` é a biblioteca de manipulação de formulários.

Embora seja possível processar submissões de formulário somente usando a classe
:class:`~django.http.HttpRequest` do Django, usando a biblioteca de formulários
fica melhor para a realização de uma série de tarefas comunus relacionadas a
formulários. Usando-o, você pode:

    1. Mostrar um formulário HTML com widgets gerados automaticamente.
    2. Verificar os dados submetidos conforme um conjuto de regras de validação.
    3. Re-exibir um formulário no caso de haver erros de validação.
    4. Converter dados de formulários submetidos a tipos relevantes do Python.

Visão geral
===========

A biblioteca trabalha com os seguintes conceitos:

.. glossary::

    Widget
        Uma classe que corresponde a um widget de formulário HTML, e.g.
        ``<input type="text">`` ou ``<textarea>``. Este manipula a renderização
        do widget como HTML.

    Field
        Uma classe que é responsável por fazer validação, e.g. um ``EmailField``
        que assegura-se de que seu dado é um endereço de e-mail válido.

    Form
        Uma coleção de campos que sabem como validar e mostrar a si mesmo como
        HTML.

    Form Media
        Os recursos CSS e Javascript que são requeridos para renderizar um
        formulário.

A biblioteca é dissociada de outros componentes do Django, como a camada de
banco de dados., views e templates. Ele invoca somente do Django settings,
algumas funções helpers ``django.utils`` e hooks de internacionalização do
Django (mas você não é obrigado a usar internacionalização para usar esta
biblioteca).

Objetos Form
============

Um objeto Form encapsula uma sequencia de campos de formulário e uma coleção de
regras de validação que devem ser preenchidas para que o furmulário seja aceito.
Classes Form são criadas como subclasses de ``django.forms.Form`` e fazem uso
de um estilo declarativo, que se você irá familiarizar-se, pois ele é usado nos
models de banco de dados do Django.

Por exemplo, considere um formulário usado para implementar a funcionalidade
"contact me" num Web site pessoal:

.. code-block:: python

    from django import forms

    class ContactForm(forms.Form):
        subject = forms.CharField(max_length=100)
        message = forms.CharField()
        sender = forms.EmailField()
        cc_myself = forms.BooleanField(required=False)

Um formulário é composto de objetos ``Field``. Neste caso, nosso formulário tem
quatro campos: ``subject``, ``message``, ``sender`` e ``cc_myself``.
``CharField``, ``EmailField`` e ``BooleandField`` são somente três dos tipos
tipos de campos disponíveis; uma lista completa pode ser encontrada em
:ref:`ref-forms-fields`.

Se seu formulário será usado para adicionar ou editar um model do Django
diretamente, você pode usar um :ref:`ModelForm <topics-forms-modelforms>` para
evitar duplicações de suas descrições de model.

Usando um formulário num view
-----------------------------

O padrão para processar um formulário num view parece com isso:

.. code-block:: python

   def contact(request):
       if request.method == 'POST': # If the form has been submitted...
           form = ContactForm(request.POST) # Um form com os dados de POST
           if form.is_valid(): # All validation rules pass
               # Processa os dados no form.cleaned_data
               # ...
               return HttpResponseRedirect('/thanks/') # Redireciona depois do POST
       else:
           form = ContactForm() # Um formulário vazio

       return render_to_response('contact.html', {
           'form': form,
       })


Existem três caminhos de código aqui:

    1. Se o form não foi submetido, uma instância **unbound** do ContactForm é
       criada e passada para o template.
    2. Se o form foi submetido, uma instância **bound** do form é criada usando
       o ``request.POST``. Se os dados submetidos forem válidos, ele é
       processado e o usuário é redirecionado para uma página de
       "agradecimento".
    3. Se o formulário foi submitetido mas é inválido, uma instância **bound**
       do form é passada ao template.

.. versionchanged:: 1.0
    O atributo ``cleanded_data`` foi chamado de ``clean_data`` em versões
    anteriores.

A distinção entre formulários **bound** e **unbound** é importante. Um
formulário unbound não tem qualquer dado associado a ele; quando o formlário for
renderizado para o usuário, ele estará vazio ou conterá valores padrão. Um
fomrulário bound possui dados submetidos, e por isso pode ser usado para dizer
se os dados são válidos. Se um formulário bound e inválido for renderizado ele
pode incluír mensagens de erros, dizendo ao usuário onde ele errou.

Veja :ref:`ref-forms-api-bound-unbound` para mais informações sobre diferenças
entre formulários bound e unbound.

Manipulando upload de arquivos com um form
------------------------------------------

Para ver como manipular upload de arquivos com seu formulário veja
:ref:`binding-uploaded-files` para mais informações.


Processando os dados de um formulário
--------------------------------------

Uma vez que ``is_valid()`` retorne ``True``, você pode processar a submissão do
formulário sabendo que ela está em conformidade com as regras de validação
definidas por seu formulário. Embora você possa acessar ``request.POST``
diretamente deste ponto, é melhor acessar ``form.cleaned_data``. Estes dados não
serão somente válidos, mas estarão convertidos em tipos relevantes do Python. No
exemplo acima, ``cc_myself`` será um valor booleano. Da mesma forma, campos como
``IntegerField`` e ``FloatField`` serão convertidos para int e float do Python
respectivamente.

Extendendo o exemplo acima, aqui temos como os dados do formulário podem ser
processados:

.. code-block:: python

    if form.is_valid():
        subject = form.cleaned_data['subject']
        message = form.cleaned_data['message']
        sender = form.cleaned_data['sender']
        cc_myself = form.cleaned_data['cc_myself']

        recipients = ['info@example.com']
        if cc_myself:
            recipients.append(sender)

        from django.core.mail import send_mail
        send_mail(subject, message, sender, recipients)
        return HttpResponseRedirect('/thanks/') # Redirect after POST

Para saber mais sobre como enviar e-mail do Django, veja :ref:`topics-email`.

Mostrando um formulário usando um template
------------------------------------------

O Forms é projetados para trabalhar com a linguagem de templates do Django. No
exemplo acima, nós passamos nossa instância do ``ContactForm`` para o template
usando a variável de contexto ``form``. Aqui temos um exemplo simples de
template:

    <form action="/contact/" method="POST">
    {{ form.as_p }}
    <input type="submit" value="Submit" />
    </form>

O form somente mostra seus próprios campos; ele não fornece tags ``<form>`` e
o botão submit.

O ``forms.as_p`` mostrará o formulário com cada campo e sua respectiva label
envolvidos por um parágrafo. Aqui temos uma saída para nosso template de
exemplo::

   <form action="/contact/" method="POST">
   <p><label for="id_subject">Subject:</label>
       <input id="id_subject" type="text" name="subject" maxlength="100" /></p>
   <p><label for="id_message">Message:</label>
       <input type="text" name="message" id="id_message" /></p>
   <p><label for="id_sender">Sender:</label>
       <input type="text" name="sender" id="id_sender" /></p>
   <p><label for="id_cc_myself">Cc myself:</label>
       <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>
   <input type="submit" value="Submit" />
   </form>

Note que cada campo de formulário tem um atributo ID setado para
``id_<field-name>``, que é referenciado por uma tag label. Isto é importante
para assegurar que os formulários sejam acessíveis para tecnologias assistivas
como leitores de tela. Você também pode :ref:`customizar a forma em que as
labels e ids são gerados <ref-forms-api-configuring-label>`.

Você pode também usar ``forms.as_table`` para gerar saídas como linhas de
tabela. (você precisará fornecer suas próprias tags ``<table>``) e
``forms.as_ul`` para mostrar em items de lista.

Personalizando o templates de formulário
----------------------------------------

Se o HTML padrão gerado não é de seu gosto, você pode personalizar completamente
a forma como o formulário é apresentado usando a linguagem de template do
Django. Extendendo o exemplo acima::

    <form action="/contact/" method="POST">
        <div class="fieldWrapper">
            {{ form.subject.errors }}
            <label for="id_subject">E-mail subject:</label>
            {{ form.subject }}
        </div>
        <div class="fieldWrapper">
            {{ form.message.errors }}
            <label for="id_message">Your message:</label>
            {{ form.message }}
        </div>
        <div class="fieldWrapper">
            {{ form.sender.errors }}
            <label for="id_sender">Your email address:</label>
            {{ form.sender }}
        </div>
        <div class="fieldWrapper">
            {{ form.cc_myself.errors }}
            <label for="id_cc_myself">CC yourself?</label>
            {{ form.cc_myself }}
        </div>
        <p><input type="submit" value="Send message" /></p>
    </form>

Cada campo de formulário nomeado pode ser mostrado ao template usando
``{{ form.nome_do_campo }}``, que produzirá o HTML necessário para mostrar o
widget de formulário. Usando ``{{ form.nome_do_campo.errors }}`` mostra uma
lista de erros de formulário, renderizado como uma lista não ordenada. Ele pode
parecer com isso::

   <ul class="errorlist">
       <li>Sender is required.</li>
   </ul>

The list has a CSS class of ``errorlist`` to allow you to style its appearance.
If you wish to further customize the display of errors you can do so by looping
over them::
A lista tem uma classe CSS ``errorlist`` para permitir que você mude sua
aparência. Se você desejar personalizar a exibição dos erros, você pode fazê-lo
iterando sobre eles::

    {% if form.subject.errors %}
        <ol>
        {% for error in form.subject.errors %}
            <li><strong>{{ error|escape }}</strong></li>
        {% endfor %}
        </ol>
    {% endif %}

Iterando sobre os campos de formulário
--------------------------------------

Se você estiver usando o mesmo HTML para cada um dos seus campos de formulário,
você pode reduzir a duplicidade de código iterando sobre os campos usando um
loop ``{% for %}``::

    <form action="/contact/" method="POST">
        {% for field in form %}
            <div class="fieldWrapper">
                {{ field.errors }}
                {{ field.label_tag }}: {{ field }}
            </div>
        {% endfor %}
        <p><input type="submit" value="Send message" /></p>
    </form>

Dentro deste loop, ``{{ field }}`` é uma instância de :class`BoundField`.
O ``BoundField`` também tem os seguintes atributos, que podem ser úteis nos seus
templates:

    ``{{ field.label }}``
        A label do campo, e.g. ``E-mail address``

    ``{{ field.label_tag }}``
        A label do campo envolvida por uma tag HTML ``<label>``,
        e.g. ``<label for="id_email">E-mail address</label>``

    ``{{ field.html_name }}``
        O nome do campo que será usado no nome do elemento campo input.
        Este ercebe o prefixo do formulário, se ele tiver sido definido

    ``{{ field.help_text }}``
        Qualquer texto de ajuda que deva ser associado com o campo.

    ``{{ field.errors }}``
        Gera um ``<ul class="errorlist">`` contendo qualquer erro de validação
        correspondendo a este campo. Você pode personalizar a apresentação dos
        erros com um loop ``{% for error in field.errors %}``. Neste caso, cada
        objeto no loop é uma string simples contendo a mensagem de erro.

Templates de formulário reusáveis
---------------------------------

Se seu site usa a mesma lógica de renderização para formulários em vários
lugares, você pode reduzir a duplicidade utilizando um loop de formulário num
template autônomo e usando a tag :ttag:`include` para reusá-lo noutros
templates::

    <form action="/contact/" method="POST">
        {% include "form_snippet.html" %}
        <p><input type="submit" value="Send message" /></p>
    </form>

    # No form_snippet.html:

    {% for field in form %}
        <div class="fieldWrapper">
            {{ field.errors }}
            {{ field.label_tag }}: {{ field }}
        </div>
    {% endfor %}

Se o objeto form passado a um template tem um nome diferente dentro do contexto,
você pode criar um alias usando a tag :ttag:`with`::

    <form action="/comments/add/" method="POST">
        {% with comment_form as form %}
            {% include "form_snippet.html" %}
        {% endwith %}
        <p><input type="submit" value="Submit comment" /></p>
    </form>

Se você se pegar fazendo isso frequentemente, você pode considerar criar uma
:ref:`inclusion tag<howto-custom-template-tags-inclusion-tags>` personalizada.

Tópicos adicionais
==================

Isto cobre o básido, mas os forms podem fazer muito mais:

.. toctree::
   :maxdepth: 1

   modelforms
   formsets
   media

.. seealso::

    A :ref:`referência de API do form <ref-forms-index>`.