Configuração Detalhada de Campos de Formulários no Django

No Django, é possível personalizar campos de formulários usando diversos parâmetros para ajustar sua aparência e funcionalidade. Contudo, em alguns casos, essas personalizações básicas podem ser insuficientes. Por exemplo, pode ser necessário aplicar estilos CSS específicos ou adicionar texto customizado ao lado de um campo. O Django permite acessar e modificar diretamente a composição de cada campo no template, proporcionando controle mais detalhado.

Acessando Campos de um Formulário no Template

No template, é possível acessar cada campo de um formulário pelo nome, usando a sintaxe form.nome_do_campo. Isso retorna o elemento HTML gerado pelo campo, sem incluir o label ou outros componentes adicionais. Cada campo possui valores associados que podem ser utilizados para personalização:

form.nome_do_campo.name: Nome do campo.
form.nome_do_campo.value: Valor atual do campo.
form.nome_do_campo.label: Texto do label associado ao campo.
form.nome_do_campo.id_for_label: ID gerado automaticamente, seguindo o padrão id_nome_do_campo.
form.nome_do_campo.auto_id: ID gerado automaticamente, semelhante ao anterior.
form.nome_do_campo.label_tag: Elemento <label> associado ao campo.
form.nome_do_campo.help_text: Texto de ajuda associado ao campo.
form.nome_do_campo.errors: Lista de erros de validação associados ao campo.
form.nome_do_campo.css_classes: Classes CSS associadas ao campo.
form.nome_do_campo.as_hidden: Gera a marcação HTML para um campo oculto (<input type="hidden">).
form.nome_do_campo.is_hidden: Retorna True se o campo for oculto, ou False caso contrário.
form.nome_do_campo.as_text: Gera a marcação HTML para um campo de texto (<input type="text">).
form.nome_do_campo.as_textarea: Gera a marcação HTML para uma área de texto (<textarea>).
form.nome_do_campo.as_widget: Retorna o widget associado ao campo.

Por exemplo, para obter o texto do label do campo age, basta usar form.age.label.

Exemplo de Uso

Considere a seguinte definição de formulário no arquivo forms.py:

from django import forms

class UserForm(forms.Form):
    name = forms.CharField()
    age = forms.IntegerField()

O formulário é passado para o template por meio de uma view no arquivo views.py:

from django.shortcuts import render
from django.http import HttpResponse
from .forms import UserForm

def index(request):
    userform = UserForm()
    if request.method == "POST":
        userform = UserForm(request.POST)
        if userform.is_valid():
            name = userform.cleaned_data["name"]
            return HttpResponse(f"<h2>Hello, {name}</h2>")
    return render(request, "index.html", {"form": userform})

No template index.html, os campos do formulário são renderizados e personalizados:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Django Forms</title>
  </head>
  <body>
    <form method="POST" novalidate>
      {% csrf_token %}
      <div>
        {% for field in form %}
        <div class="form-group">
          {{ field.label_tag }}
          <div>{{ field }}</div>
          <div class="error">{{ field.errors }}</div>
        </div>
        {% endfor %}
      </div>
      <p><input type="submit" value="Send" /></p>
    </form>
  </body>
</html>

No exemplo acima, a estrutura {% for field in form %} itera sobre os campos do formulário, permitindo personalizar como cada campo e seus atributos (como erros e labels) são exibidos. Erros de validação associados a um campo são renderizados com field.errors.

A imagem a seguir ilustra o formulário com erros retornados após o envio incorreto de dados:

Exemplo de Erros Retornados após Envio Incorreto de Formulário em Django

Tratando Vários Erros em um Campo

Se um único campo contiver vários erros de validação, é possível exibi-los individualmente usando uma estrutura de repetição:

{% for error in field.errors %}
    <div class="alert alert-danger">{{ error }}</div>
{% endfor %}

Documentação oficial:

Working with forms