Django Forms§

Validate user input and return Python objects

Defining Forms

Forms are composed of fields, which have a widget.

          from django.utils.translation import gettext_lazy as _
from django import forms

class ContactForm(forms.Form):

    name = forms.CharField(label=_("Your Name"),
        max_length=255,
        widget=forms.TextInput,
    )

    email = forms.EmailField(label=_("Email address"))

        

Instantiating a Form

Unbound forms don't have data associated with them, but they can be rendered:

          form = ContactForm()

        

Bound forms have specific data associated, which can be validated:

          form = ContactForm(data=request.POST, files=request.FILES)

        

Accessing Fields

Two ways to access fields on a Form instance

form.fields['name'] returns the Field object
form['name'] returns a BoundField
BoundField wraps a field and value for HTML output

Validating the Form

Only bound forms can be validated
Calling form.is_valid() triggers validation if needed
Validated, cleaned data is stored in form.cleaned_data
Calling form.full_clean() performs the full cycle

Field Validation

Three phases for Fields: To Python, Validation, and Cleaning
If validation raises an Error, cleaning is skipped
Validators are callables that can raise a ValidationError
Django includes generic ones for some common tasks
Examples: URL, Min/Max Value, Min/Max Length, URL, Regex, email

Field Cleaning

.clean_fieldname() method is called after validators
Input has already been converted to Python objects
Methods can raise ValidationErrors
Methods must return the cleaned value

Rendering Forms

Three primary "whole-form" output modes:

form.as_p(), form.as_ul(), form.as_table()

          <tr><th><label for="id_name">Name:</label></th>
  <td><input id="id_name" type="text" name="name" maxlength="255" /></td></tr>
<tr><th><label for="id_email">Email:</label></th>
  <td><input id="id_email" type="text" name="email" maxlength="Email address" /></td></tr>
<tr><th><label for="id_confirm_email">Confirm email:</label></th>
  <td><input id="id_confirm_email" type="text" name="confirm_email" maxlength="Confirm" /></td></tr>

        

Controlling Form Output

          {% for field in form %}
{{ field.label_tag }}: {{ field }}
{{ field.errors }}
{% endfor %}
{{ form.non_field_errors }}

        

Additional rendering properties:

field.label
field.label_tag
field.auto_id
field.help_text