A menos que você planeje construir websites e aplicações que não façam outra coisa além de publicar conteúdo, e não aceita entrada de seus visitantes, você irá precisar entender e usar formulários.
\nO Django fornece uma gama de ferramentas e bibliotecas para auxiliar a construção de formulários para entrada de dados vindos dos seus visitantes, e então os processa e responde àquela entrada.
\nEm HTML, um formulário é uma coleção de elementos dentro de <form>...</form> que permitem que os visitantes façam coisas como escrever um texto, selecionar opções, manipular objetos ou controle e assim por diante, e então enviar esta informação de volta ao servidor.
Alguns destes elementos da interface do formulário - entrada de texto ou “checkboxes”- são bem simples e fazem parte do próprio HTML. Outros são bem mais complexos; uma interface que faz saltar um seletor de datas ou permite mover uma barra ou manipular controles irá usa geralmente javascript e CSS bem como elementos <input> de formulários HTML para tornar possíveis estes efeitos.
Assim como seus elementos <input>, um formulário precisa especificar duas coisas:
onde: a URL para a qual o dado correspondente à entrada do usuário deve ser enviado.
como: o método HTTP pelo qual o dado deve ser retornado
Como um exemplo, o formulário de autenticação do admin do Django contém vários elementos do tipo <input>: um type="text" para o nome do usuário, um de type="password" para a senha, e um type="submit" par ao botão “Log in”. Ele também contém alguns objetos escondidos do tipo texto que o usuário não vê, o qual o Django usa para determinar o que fazer depois.
Ele também dia ao navegador web que os dados do formulário devem ser enviados para a URL especificada no atributo <action> do <form> - /admin/ - e isso deve ser enviado usando o mecanismo HTTP especificado pelo atributo method - post.
Quando o elemento <input type="submit" value="Log in"> e disparado, os dados são retornados para /admin/.
GET e POSTLink para este cabeçalho#GET e POST são os únicos métodos HTTP a se usar enquanto lida com formulários.
O formulário de autenticação do Django é retornado usando o método POST, no qual o navegador web empacota os dados do formulário, codifica-os para transmissão, envia para o servidor, e então recebe de volta sua resposta.
O GET, em contraste, empacota os dados enviados em uma string, e usa isso para compor a URL. A URL contém o endereço para onde o dado deve ser enviado, bem como as chaves dos dados e valore. Você pode ver isso em ação se você fizer uma busca na documentação do Django, a qual irá produzir uma URL na forma de https://docs.djangoproject.com/search/?q=forms&release=1.
GET e POST são tipicamente usados para propósitos distintos.
Qualquer requisição que pode ser usada para alterar o estado do sistema - por exemplo, uma requisição que faz alterações no banco de dados - deve usar POST. O GET deve ser usado somente para requisições que não afetam o estado do sistema.
O GET também não é adequado para formulários com senhas, porque a senha apareceria na URL, e portanto, também no histórico do navegador web e logs do servidor, tudo em texto puro. Nem mesmo seria adequado para grandes quantidade de dados, ou para dados binários, como uma imagem. Uma aplicação web que usa as requisições to tipo GET para formulários de administração é um risco de segurança: pode ser fácil para um ataque imitar uma requisição de um formulário para ter acesso a partes sensíveis do sistema. O POST juntamente com outras proteções como a proteção CSRF do Django oferece mais controle sobre o acesso.
Por outro lado, o GET é adequado para coisas como um formulário web de busca, porque a URL que represente uma requisição do tipo GET pode ser facilmente adicionado a lista de favoritos, comparilhada ou reenviada.
Lidar com formulários é uma coisa complexa. Considere o admin do Django, onde inúmeros itens de dados de diferentes tipos precisam ser preparados para serem visualizados em um formulário, renderizados como HTML, editado usando uma interface conveniente, retornados ao servidor, validados e limpos, e então salvos ou passados adiante para mais processamento.
\nA funcionalidade de formulários do Django pode simplificar e automatizar uma boa parte deste trabalho, e pode também fazer isso de maneira mais segura que a maioria dos programadores poderiam ser capazes de fazer no código que escrevem.
\nO Django lida com três partes distintas do trabalho envolvendo formulários:
\nPreparando e reestruturando os dados para torná-los prontos para rederização
criando formulários HTML para os dados
recebendo e processando formulário enviado e os dados vindos do cliente
É possível escrever código que faz tudo isso manualmente, mas o Django pode tomar conta de tudo isso pra você.
\nDescrevemos brevemente os formulários HTML, mas um <form> HTML é apenas uma parte do maquinário requerido.
Dentro do contexto de uma aplicação web, um ‘formulário’ talvez se refira ao <form> HTML, ou a Form do Django que o produz, ou ao dado estruturado retornado quando este é enviado, ou ao conjunto funcional de todas essas partes.
Form do DjangoLink para este cabeçalho#No coração deste sistema de componentes está a classe Form do Django. Mais ou menos como o modelo do Django descreve a estrutura lógica de um objeto, seu comportamento, e a maneira como suas partes são apresentadas para nós, uma classe Form descreve um formulário e determina como este funciona e aparece.
De maneira similar que a classe de modelo mapeia os campos para o banco de dados, uma classe de formulário mapeia para os elementos <input> do formulário HTML. (Uma ModelForm mapeia os campos de uma classe de modelo para elementos <input> do formulário HTML através da Form; o admin do Django é baseado nisso.)
Os campos dos formulários são eles próprios classes; eles manipulam dados do formulário e fazem validações quando o formulário é enviado. A DateField e a FileField lidam com tipos de dados muito diferentes e tem que fazer coisas diferentes com isso.
Um campo de formulário, para o usuário, é representado como um “widget” HTML - um pedaço do maquinário de interface do usuário. Cada campo tem uma classe de Widget padrão, mas isso pode ser sobrescrito quando requerido.
\nQuando renderizar um objeto no Django, em geral:
\npegamos o objeto na “view” (lido no banco de dados, por exemplo)
o passamos para o “context” do template
expandimos para a marcação HTML usando variáveis de template
Mostrar um formulário em um template envolve quase o mesmo trabalho que mostrar qualquer outro tipo de objeto, mas existem algumas diferenças chave.
\nNo caso de uma instância de modelo que não contém nenhum dado, é raramente útil ou talvez nunca seja útil para fazer nada com isso no template. Por outro lado, faz todo o sentido, mostrar um formulário vazio - que é o que fazemos quando queremos que o usuário o preencha.
\nEntão quando lidamos com uma instância de modelo em uma “view”, nós tipicamente a recuperamos do banco de dados. Quando lidamos com um formulário, nós tipicamente o instanciamos na “view”.
\nQuando nós instanciamos um formulário, nós podemos optar por deixá-lo vazio ou o pré-preenchemos, por exemplo com:
\ndados vindos de uma instância de modelo salva previamente (como no caso dos formulários do admin para edição)
dados que tenhamos coletado de outras fontes
dados recebidos de uma prévia submissão de formulário
O último destes casos é o mais interessante, porque é o que torna possível para um usuário não somente ler um site web, mas enviar informação de volta a ele.
\nSuponha queira criar um formulário simples no seu site web, de modo a obter o nome do usuário. Você precisaria de algo como isso aqui no seu template:
\n<form action="/your-name/" method="post">\n <label for="your_name">Your name: </label>\n <input id="your_name" type="text" name="your_name" value="{{ current_name }}">\n <input type="submit" value="OK">\n</form>\nIsso diz ao navegador web para retornar os dados do form para a URL /your-name/, usando o métodos POST. Ele irá mostrar um campo, chamado “Your name:”, e um botão com um “OK”. Se o “context” do template contiver uma variável chamada current_name, esta será usada para pré-preencher o campo your_name.
Você irá precisar uma “view” que renderiza o template contendo o formulário HTML, e que pode fornecer o campo current_name apropriadamente.
Quando o formulário é submetido, a requisição do tipo POST a qual é enviada ao servidor irá conter os dados do formulário.
Agora você irá também precisar de uma “view” que corresponda aquela URL /your-name/ a qual irá encontrar o par chave/valor apropriado na requisição e então processá-lo.
Este é um formulário muito simples. Na prática, um formulário pode conter dezenas ou centenas de campos, muitos dos quais talvez precisem ser pré-preenchidos, e talvez nós esperamos que o usuário trabalhe através do ciclo de edição e submissão muitas vezes antes de concluir a operação.
\nNós podemos requerer que alguma validação ocorra no navegador web, mesmo antes do formulário ser submetido; nós podemos querer usar campos bem mais complexos, que possibilite ao usuário selecionar uma data de um calendário e assim por diante.
\nNeste ponto é muito mais fácil ter o Django fazendo a maior parte deste trabalho para nós.
\nFormLink para este cabeçalho#Nós já sabemos como queremos que o nosso formulário HTML se pareça. Nosso ponto de início para isso no Django é este:
\nforms.pyfrom django import forms\n\nclass NameForm(forms.Form):\n your_name = forms.CharField(label='Your name', max_length=100)\nEste código define uma classe Form com um único campo (your_name). Nós aplicamos uma etiqueta ao campo mais legível a seres humanos, a qual irá aparecer na <label> quando for renderizado (embora neste caso o label que especificamos é o mesmo que seria gerado automaticamente se o tivéssemos omitido).
O tamanho máximo do conteúdo do campo é definido pelo max_length. Isso faz duas coisas. Define a maxlength="100" no <input> HTML (então o navegador web impedirá que o usuário entre com um número de caracteres maio que aquele definido). Isso também significa que quando o Django receber o form de volta do navegador, o Django validará o comprimento do dado.
Uma instância da Form tem um método is_valid(), o qual executa rotinas de validações para todos os campos. Quando este método é chamado, se todos os campos contiverem dados válidos, ele irá:
retornar True
colocar os dados do formulário no atributo cleaned_data do formulário.
O formulário, quando renderizado pela primeira vez, se parecerá com:
\n<label for="your_name">Your name: </label>\n<input id="your_name" type="text" name="your_name" maxlength="100" required />\nRepare que não estão incluídas as tags <form>, ou o botão de submit. Teremos que fornecê-los nós mesmos no template.
Os dados de formulários enviados para um site Django são processados por uma “view”, geralmente a mesma “view” que publica o formulário. Isso nos permiti reutilizar parte da mesma lógica.
\nPara lidar com o formulário precisamos instanciá-lo na “view” da URL onde queremos que seja publicado:
\nviews.pyfrom django.http import HttpResponseRedirect\nfrom django.shortcuts import render\n\nfrom .forms import NameForm\n\ndef get_name(request):\n # if this is a POST request we need to process the form data\n if request.method == 'POST':\n # create a form instance and populate it with data from the request:\n form = NameForm(request.POST)\n # check whether it's valid:\n if form.is_valid():\n # process the data in form.cleaned_data as required\n # ...\n # redirect to a new URL:\n return HttpResponseRedirect('/thanks/')\n\n # if a GET (or any other method) we'll create a blank form\n else:\n form = NameForm()\n\n return render(request, 'name.html', {'form': form})\nSe chegarmos a essa “view” com uma requisição do tipo GET, ela irá criar uma instância vazia de formulário e colocá-lo no “context” do template para renderizá-lo. Isso é o que esperamos que aconteça quando visitarmos a URL pela primeira vez.
Se o formulário for submetido usando uma requisição do tipo POST, a “view” irá mais uma vez criar uma instância do formulário e preenchê-la com dados vindos da requisição form = NameForm(request.POST). Isso é chamado “carregar dados no formulário” (ele é agora um “bound form”).
Chamamos o método is_valid()``do formulário; se não é ``True, nós retornamos ao template com o formulário. Desta vez o formulário não está mais vazio (unbound) então o formulário HTML será preenchido com os dados previamente submetidos, onde podem ser editados e corrigidos quando necessário.
Se is_valid() é True, seremos capazes de encontrar todos os dados do formulário no atributo cleaned_data. Podemos usar estes dados para atualizar o banco de dados ou fazer outro processamento antes de enviar um redirecionamento HTTP para o navegador dizendo onde ir a seguir.
Nós não precisamos fazer muito no nosso template name.html. O exemplo mais simples é:
<form action="/your-name/" method="post">\n {% csrf_token %}\n {{ form }}\n <input type="submit" value="Submit" />\n</form>\nTodos os campos dos formulário e seus atributos serão desempacotados dentro da marcação HTML vindos do {{ form }} através da linguagem de templates do Django.
Nós agora temos um formulário web funcional, descrito pela Form do Django, processado pela “view”, e renderizado como um <form> HTML.
Isso é tudo o que você precisa para iniciar, mas o framework de formulários lhe dá muito mais. Uma vez que tenha entendido o básico dos processos descritos acima, você deve estar preparado para entender outras características do sistema de formulários e pronto par aprender um pouco mais sobre maquinário por de trás disso.
\nForm do DjangoLink para este cabeçalho#All form classes are created as subclasses of either django.forms.Form\nor django.forms.ModelForm. You can think of ModelForm as a\nsubclass of Form. Form and ModelForm actually inherit common\nfunctionality from a (private) BaseForm class, but this implementation\ndetail is rarely important.
The distinction between Bound and unbound forms is important:
\nAn unbound form has no data associated with it. When rendered to the user,\nit will be empty or will contain default values.
A bound form has submitted data, and hence can be used to tell if that data\nis valid. If an invalid bound form is rendered, it can include inline error\nmessages telling the user what data to correct.
The form’s is_bound attribute will tell you whether a form has\ndata bound to it or not.
Consider a more useful form than our minimal example above, which we could use\nto implement “contact me” functionality on a personal website:
\nforms.pyfrom django import forms\n\nclass ContactForm(forms.Form):\n subject = forms.CharField(max_length=100)\n message = forms.CharField(widget=forms.Textarea)\n sender = forms.EmailField()\n cc_myself = forms.BooleanField(required=False)\nOur earlier form used a single field, your_name, a CharField. In\nthis case, our form has four fields: subject, message, sender and\ncc_myself. CharField, EmailField and\nBooleanField are just three of the available field types; a full list\ncan be found in Form fields.
Each form field has a corresponding Widget class,\nwhich in turn corresponds to an HTML form widget such as <input\ntype="text">.
In most cases, the field will have a sensible default widget. For example, by\ndefault, a CharField will have a TextInput widget, that\nproduces an <input type="text"> in the HTML. If you needed <textarea>\ninstead, you’d specify the appropriate widget when defining your form field,\nas we have done for the message field.
Whatever the data submitted with a form, once it has been successfully\nvalidated by calling is_valid() (and is_valid() has returned True),\nthe validated form data will be in the form.cleaned_data dictionary. This\ndata will have been nicely converted into Python types for you.
In the contact form example above, cc_myself will be a boolean value.\nLikewise, fields such as IntegerField and FloatField convert\nvalues to a Python int and float respectively.
Here’s how the form data could be processed in the view that handles this form:
\nviews.pyfrom django.core.mail import send_mail\n\nif form.is_valid():\n subject = form.cleaned_data['subject']\n message = form.cleaned_data['message']\n sender = form.cleaned_data['sender']\n cc_myself = form.cleaned_data['cc_myself']\n\n recipients = ['info@example.com']\n if cc_myself:\n recipients.append(sender)\n\n send_mail(subject, message, sender, recipients)\n return HttpResponseRedirect('/thanks/')\nSome field types need some extra handling. For example, files that are uploaded\nusing a form need to be handled differently (they can be retrieved from\nrequest.FILES, rather than request.POST). For details of how to handle\nfile uploads with your form, see Binding uploaded files to a form.
All you need to do to get your form into a template is to place the form\ninstance into the template context. So if your form is called form in the\ncontext, {{ form }} will render its <label> and <input> elements\nappropriately.
There are other output options though for the <label>/<input> pairs:
{{ form.as_table }} will render them as table cells wrapped in <tr>\ntags
{{ form.as_p }} will render them wrapped in <p> tags
{{ form.as_ul }} will render them wrapped in <li> tags
Note that you’ll have to provide the surrounding <table> or <ul>\nelements yourself.
Here’s the output of {{ form.as_p }} for our ContactForm instance:
<p><label for="id_subject">Subject:</label>\n <input id="id_subject" type="text" name="subject" maxlength="100" required /></p>\n<p><label for="id_message">Message:</label>\n <textarea name="message" id="id_message" required></textarea></p>\n<p><label for="id_sender">Sender:</label>\n <input type="email" name="sender" id="id_sender" required /></p>\n<p><label for="id_cc_myself">Cc myself:</label>\n <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>\nNote that each form field has an ID attribute set to id_<field-name>, which\nis referenced by the accompanying label tag. This is important in ensuring that\nforms are accessible to assistive technology such as screen reader software.\nYou can also customize the way in which labels and ids are generated.
See Outputting forms as HTML for more on this.
\nWe don’t have to let Django unpack the form’s fields; we can do it manually if\nwe like (allowing us to reorder the fields, for example). Each field is\navailable as an attribute of the form using {{ form.name_of_field }}, and\nin a Django template, will be rendered appropriately. For example:
{{ form.non_field_errors }}\n<div class="fieldWrapper">\n {{ form.subject.errors }}\n <label for="{{ form.subject.id_for_label }}">Email subject:</label>\n {{ form.subject }}\n</div>\n<div class="fieldWrapper">\n {{ form.message.errors }}\n <label for="{{ form.message.id_for_label }}">Your message:</label>\n {{ form.message }}\n</div>\n<div class="fieldWrapper">\n {{ form.sender.errors }}\n <label for="{{ form.sender.id_for_label }}">Your email address:</label>\n {{ form.sender }}\n</div>\n<div class="fieldWrapper">\n {{ form.cc_myself.errors }}\n <label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>\n {{ form.cc_myself }}\n</div>\nComplete <label> elements can also be generated using the\nlabel_tag(). For example:
<div class="fieldWrapper">\n {{ form.subject.errors }}\n {{ form.subject.label_tag }}\n {{ form.subject }}\n</div>\nOf course, the price of this flexibility is more work. Until now we haven’t had\nto worry about how to display form errors, because that’s taken care of for us.\nIn this example we have had to make sure we take care of any errors for each\nfield and any errors for the form as a whole. Note {{ form.non_field_errors\n}} at the top of the form and the template lookup for errors on each field.
Using {{ form.name_of_field.errors }} displays a list of form errors,\nrendered as an unordered list. This might look like:
<ul class="errorlist">\n <li>Sender is required.</li>\n</ul>\nThe list has a CSS class of errorlist to allow you to style its appearance.\nIf you wish to further customize the display of errors you can do so by looping\nover them:
{% if form.subject.errors %}\n <ol>\n {% for error in form.subject.errors %}\n <li><strong>{{ error|escape }}</strong></li>\n {% endfor %}\n </ol>\n{% endif %}\nNon-field errors (and/or hidden field errors that are rendered at the top of\nthe form when using helpers like form.as_p()) will be rendered with an\nadditional class of nonfield to help distinguish them from field-specific\nerrors. For example, {{ form.non_field_errors }} would look like:
<ul class="errorlist nonfield">\n <li>Generic validation error</li>\n</ul>\nSee The Forms API for more on errors, styling, and working with form\nattributes in templates.
\nIf you’re using the same HTML for each of your form fields, you can reduce\nduplicate code by looping through each field in turn using a {% for %}\nloop:
{% for field in form %}\n <div class="fieldWrapper">\n {{ field.errors }}\n {{ field.label_tag }} {{ field }}\n {% if field.help_text %}\n <p class="help">{{ field.help_text|safe }}</p>\n {% endif %}\n </div>\n{% endfor %}\nUseful attributes on {{ field }} include:
{{ field.label }}The label of the field, e.g. Email address.
{{ field.label_tag }}The field’s label wrapped in the appropriate HTML <label> tag. This\nincludes the form’s label_suffix. For example,\nthe default label_suffix is a colon:
<label for="id_email">Email address:</label>\n{{ field.id_for_label }}The ID that will be used for this field (id_email in the example\nabove). If you are constructing the label manually, you may want to use\nthis in lieu of label_tag. It’s also useful, for example, if you have\nsome inline JavaScript and want to avoid hardcoding the field’s ID.
{{ field.value }}The value of the field. e.g someone@example.com.
{{ field.html_name }}The name of the field that will be used in the input element’s name\nfield. This takes the form prefix into account, if it has been set.
\n{{ field.help_text }}Any help text that has been associated with the field.
\n{{ field.errors }}Outputs a <ul class="errorlist"> containing any validation errors\ncorresponding to this field. You can customize the presentation of\nthe errors with a {% for error in field.errors %} loop. In this\ncase, each object in the loop is a simple string containing the error\nmessage.
{{ field.is_hidden }}This attribute is True if the form field is a hidden field and\nFalse otherwise. It’s not particularly useful as a template\nvariable, but could be useful in conditional tests such as:
{% if field.is_hidden %}\n {# Do something special #}\n{% endif %}\n{{ field.field }}The Field instance from the form class that\nthis BoundField wraps. You can use it to access\nField attributes, e.g.\n{{ char_field.field.max_length }}.
If your site uses the same rendering logic for forms in multiple places, you\ncan reduce duplication by saving the form’s loop in a standalone template and\nusing the include tag to reuse it in other templates:
# In your form template:\n{% include "form_snippet.html" %}\n\n# In form_snippet.html:\n{% for field in form %}\n <div class="fieldWrapper">\n {{ field.errors }}\n {{ field.label_tag }} {{ field }}\n </div>\n{% endfor %}\nIf the form object passed to a template has a different name within the\ncontext, you can alias it using the with argument of the include\ntag:
{% include "form_snippet.html" with form=comment_form %}\nIf you find yourself doing this often, you might consider creating a custom\ninclusion tag.
\nThis covers the basics, but forms can do a whole lot more:
\nMedia class)\n