#

## Django documentation

# Forms, fields, and manipulators

Once you've got a chance to play with Django's admin interface, you'll probably wonder if the fantastic form validation framework it uses is available to user code. It is, and this document explains how the framework works.

> A note to the lazy

> If all you want to do is present forms for a user to create and/or update a given object, don't read any further. Instead, click thyself to the generic views documentation. The following exercises are for those interested in how Django's form framework works and those needing to do more than simple creation/updating.

We'll take a top-down approach to examining Django's form validation framework, because much of the time you won't need to use the lower-level APIs. Throughout this document, we'll be working with the following model, a "place" object:

    PLACE_TYPES = (
        (1, 'Bar'),
        (2, 'Restaurant'),
        (3, 'Movie Theater'),
        (4, 'Secret Hideout'),
    )

    class Place(meta.Model):
        name = meta.CharField(maxlength=100),
        address = meta.CharField(maxlength=100, blank=True),
        city = meta.CharField(maxlength=50, blank=True),
        state = meta.USStateField(),
        zip_code = meta.CharField(maxlength=5, blank=True),
        place_type = meta.IntegerField(choices=PLACE_TYPES)
        class META:
            admin = meta.Admin()

        def __repr__(self):
            return self.name

Defining the above class is enough to create an admin interface to a `place`, but what if you want to allow public users to submit places?

## Manipulators

The highest-level interface for object creation and modification is the Manipulator framework. A manipulator is a utility class tied to a given model that "knows" how to create or modify instances of that model and how to validate data for the object. Manipulators come in two flavors: `AddManipulators` and `ChangeManipulators`. Functionally they are quite similar, but the former knows how to create new instances of the model, while the later modifies existing instances. Both types of classes are automatically created when you define a new class:

    >>> from django.models.places import places
    >>> places.AddManipulator
    <class django.models.places.PlaceManipulatorAdd at 0x4c1540>
    >>> places.ChangeManipulator
    <class django.models.places.PlaceManipulatorChange at 0x4c1630>

### Using the `AddManipulator`

We'll start with the `AddManipulator`. Here's a very simple view that takes POSTed data from the browser and creates a new `Place` object:

    from django.core.exceptions import Http404
    from django.core.extensions import render_to_response
    from django.utils.httpwrappers import HttpResponse, HttpResponseRedirect
    from django.models.places import places
    from django.core import formfields

    def naive_create_place(request):
        """A naive approach to creating places; don't actually use this!"""
        # Create the AddManipulator.
        manipulator = places.AddManipulator()

        # Make a copy of the POSTed data so that do_html2python can
        # modify it in place (request.POST is immutable).
        new_data = request.POST.copy()

        # Convert the request data (which will all be strings) into the
        # appropriate Python types for those fields.
        manipulator.do_html2python(new_data)

        # Save the new object.
        new_place = manipulator.save(new_data)

        # It worked!
        return HttpResponse("Place created: %s" % new_place)

The `naive_create_place` example works, but as you probably can tell, this view has a number of problems:

> - No validation of any sort is performed. If, for example, the `name` field isn't given in `request.POST`, the save step will cause a database error because that field is required. Ugly.
> - Even if you do perform validation, there's still no way to give that information to the user is any sort of useful way.
> - You'll have to separately create a form (and view) that submits to this page, which is a pain and is redundant.

Let's dodge these problems momentarily to take a look at how you could create a view with a form that submits to this flawed creation view:

    def naive_create_place_form(request):
        """Simplistic place form view; don't actually use anything like this!"""
        # Create a FormWrapper object that the template can use. Ignore
        # the last two arguments to FormWrapper for now.
        form = formfields.FormWrapper(places.AddManipulator(), {}, {})
        return render_to_response('places/naive_create_form', {'form': form})

(This view, as well as all the following ones, has the same imports as in the first example above.)

The `formfields.FormWrapper` object is a wrapper that templates can easily deal with to create forms. Here's the `naive_create_form` template:

    {% extends "base" %}

    {% block content %}
    <h1>Create a place:</h1>

    <form method="post" action="../do_new/">
    <p><label for="id_name">Name:</label> {{ form.name }}</p>
    <p><label for="id_address">Address:</label> {{ form.address }}</p>
    <p><label for="id_city">City:</label> {{ form.city }}</p>
    <p><label for="id_state">State:</label> {{ form.state }}</p>
    <p><label for="id_zip_code">Zip:</label> {{ form.zip_code }}</p>
    <p><label for="id_place_type">Place type:</label> {{ form.place_type }}</p>
    <input type="submit" />
    </form>
    {% endblock %}

Before we get back to the problems with these naive set of views, let's go over some salient points of the above template:

    * Field "widgets" are handled for you: ``{{ form.field }}`` automatically
      creates the "right" type of widget for the form, as you can see with the
      ``place_type`` field above.

    * There isn't a way just to spit out the form. You'll still need to define
      how the form gets laid out. This is a feature: Every form should be
      designed differently. Django doesn't force you into any type of mold.
      If you must use tables, use tables. If you're a semantic purist, you can
      probably find better HTML than in the above template.

    * To avoid name conflicts, the ``id``s of form elements take the form
      "id_*fieldname*".

By creating a creation form we've solved problem number 3 above, but we still don't have any validation. Let's revise the validation issue by writing a new creation view that takes validation into account:

    def create_place_with_validation(request):
        manipulator = places.AddManipulator()
        new_data = request.POST.copy()

        # Check for validation errors
        errors = manipulator.get_validation_errors(new_data)
        if errors:
            return render_to_response('places/errors', {'errors': errors})
        else:
            manipulator.do_html2python(request.POST)
            new_place = manipulator.save(request.POST)
            return HttpResponse("Place created: %s" % new_place)

In this new version, errors will be found -- `manipulator.get_validation_errors` handles all the validation for you -- and those errors can be nicely presented on an error page (templated, of course):

    {% extends "base" %}

    {% block content %}

    <h1>Please go back and correct the following error{{ errors|pluralize }}:</h1>
    <ul>
        {% for e in errors.items %}
        <li>Field "{{ e.0 }}": {{ e.1|join:", " }}</li>
        {% endfor %}
    </ul>

    {% endblock %}

Still, this has its own problems:

> - There's still the issue of creating a separate (redundant) view for the submission form.
> - Errors, though nicely presented, are on a separate page, so the user will have to use the "back" button to fix errors. That's ridiculous and unusable.

The best way to deal with these issues is to collapse the two views -- the form and the submission -- into a single view. This view will be responsible for creating the form, validating POSTed data, and creating the new object (if the data is valid). An added bonus of this approach is that errors and the form will both be available on the same page, so errors with fields can be presented in context.

Philosophy::

Finally, for the HTTP purists in the audience (and the authorship), this nicely matches the "true" meanings of HTTP GET and HTTP POST: GET fetches the form, and POST creates the new object.

Below is the finished view:

    def create_place(request):
        manipulator = places.AddManipulator()

        if request.POST:
            # If data was POSTed, we're trying to create a new Place.
            new_data = request.POST.copy()

            # Check for errors.
            errors = manipulator.get_validation_errors(new_data)

            if not errors:
                # No errors. This means we can save the data!
                manipulator.do_html2python(new_data)
                new_place = manipulator.save(new_data)

                # Redirect to the object's "edit" page. Always use a redirect
                # after POST data, so that reloads don't accidently create
                # duplicate entires, and so users don't see the confusing
                # "Repost POST data?" alert box in their browsers.
                return HttpResponseRedirect("/places/edit/%i/" % new_place.id)
        else:
            # No POST, so we want a brand new form without any data or errors.
            errors = new_data = {}

        # Create the FormWrapper, template, context, response.
        form = formfields.FormWrapper(manipulator, new_data, errors)
        return render_to_response('places/create_form', {'form': form})

and here's the `create_form` template:

    {% extends "base" %}

    {% block content %}
    <h1>Create a place:</h1>

    {% if form.has_errors %}
    <h2>Please correct the following error{{ errors|pluralize }}:</h2>
    {% endif %}

    <form method="post" action=".">
    <p>
        <label for="id_name">Name:</label> {{ form.name }}
        {% if form.name.errors %}*** {{ form.name.errors|join:", " }}{% endif %}
    </p>
    <p>
        <label for="id_address">Address:</label> {{ form.address }}
        {% if form.address.errors %}*** {{ form.address.errors|join:", " }}{% endif %}
    </p>
    <p>
        <label for="id_city">City:</label> {{ form.city }}
        {% if form.city.errors %}*** {{ form.city.errors|join:", " }}{% endif %}
    </p>
    <p>
        <label for="id_state">State:</label> {{ form.state }}
        {% if form.state.errors %}*** {{ form.state.errors|join:", " }}{% endif %}
    </p>
    <p>
        <label for="id_zip_code">Zip:</label> {{ form.zip_code }}
        {% if form.zip_code.errors %}*** {{ form.zip_code.errors|join:", " }}{% endif %}
    </p>
    <p>
        <label for="id_place_type">Place type:</label> {{ form.place_type }}
        {% if form.place_type.errors %}*** {{ form.place_type.errors|join:", " }}{% endif %}
    </p>
    <input type="submit" />
    </form>
    {% endblock %}

The second two arguments to `FormWrapper` (`new_data` and `errors`) deserve some mention.

The first is any "default" data to be used as values for the fields. Pulling the data from `request.POST`, as is done above, makes sure that if there are errors, the values the user put in aren't lost. If you try the above example, you'll see this in action.

The second argument is the error list retrieved from `manipulator.get_validation_errors`. When passed into the `FormWrapper`, this gives each field an `errors` item (which is a list of error messages associated with the field) as well as a `html_error_list` item, which is a `<ul>` of error messages. The above template uses these error items to display a simple error message next to each field.

### Using the `ChangeManipulator`

The above has covered using the `AddManipulator` to create a new object. What about editing an existing one? It's shockingly similar to creating a new one:

    def edit_place(request, place_id):
        # Get the place in question from the database and create a
        # ChangeManipulator at the same time.
        try:
            manipulator = places.ChangeManipulator(place_id)
        except places.PlaceDoesNotExist:
            raise Http404

        # Grab the Place object in question for future use.
        place = manipulator.original_object

        if request.POST:
            new_data = request.POST.copy()
            errors = manipulator.get_validation_errors(new_data)
            if not errors:
                manipulator.do_html2python(new_data)
                manipulator.save(new_data)

                # Do a post-after-redirect so that reload works, etc.
                return HttpResponseRedirect("/places/edit/%i/" % place.id)
        else:
            errors = {}
            # This makes sure the form accurate represents the fields of the place.
            new_data = place.__dict__

        form = formfields.FormWrapper(manipulator, new_data, errors)
        return render_to_response('places/edit_form', {'form': form, 'place': place})

The only real differences are:

> - We create a `ChangeManipulator` instead of an `AddManipulator`. The argument to a `ChangeManipulator` is the ID of the object to be changed. As you can see, the initializer will raise an `ObjectDoesNotExist` exception if the ID is invalid.
> - `ChangeManipulator.original_object` stores the instance of the object being edited.
> - We set `new_data` to the original object's `__dict__`. This makes sure the form fields contain the current values of the object. `FormWrapper` does not modify `new_data` in any way, and templates cannot, so this is perfectly safe.
> - The above example uses a different template, so create and edit can be "skinned" differently if needed, but the form chunk itself is completely identical to the one in the create form above.

The astute programmer will notice the add and create functions are nearly identical and could in fact be collapsed into a single view. This is left as an exercise for said programmer.

(However, the even-more-astute programmer will take heed of the note at the top of this document and check out the generic views documentation if all she wishes to do is this type of simple create/update.)

## Custom forms and manipulators

All the above is fine and dandy if you just want to use the automatically created manipulators. But the coolness doesn't end there: You can easily create your own custom manipulators for handling custom forms.

Custom manipulators are pretty simple. Here's a manipulator that you might use for a "contact" form on a website:

    from django.core import formfields

    urgency_choices = (
        (1, "Extremely urgent"),
        (2, "Urgent"),
        (3, "Normal"),
        (4, "Unimportant"),
    )

    class ContactManipulator(formfields.Manipulator):
        def __init__(self):
            self.fields = (
                formfields.EmailField(field_name="from", is_required=True),
                formfields.TextField(field_name="subject", length=30, maxlength=200, is_required=True),
                formfields.SelectField(field_name="urgency", choices=urgency_choices),
                formfields.LargeTextField(field_name="contents", is_required=True),
            )

A certain similarity to Django's models should be apparent. The only required method of a custom manipulator is `__init__` which must define the fields present in the manipulator. See the `django.core.formfields` module for all the form fields provided by Django.

You use this custom manipulator exactly as you would use an auto-generated one. Here's a simple function that might drive the above form:

    def contact_form(request):
        manipulator = ContactManipulator()
        if request.POST:
            new_data = request.POST.copy()
            errors = manipulator.get_validation_errors(new_data)
            if not errors:
                manipulator.do_html2python(new_data)

                # Send e-mail using new_data here...

                return HttpResponseRedirect("/contact/thankyou/")
        else:
            errors = new_data = {}
        form = formfields.FormWrapper(manipulator, new_data, errors)
        return render_to_response('contact_form', {'form': form})

## Validators

One useful feature of manipulators is the automatic validation. Validation is done using a simple validation API: A validator is a callable that raises a `ValidationError` if there's something wrong with the data. `django.core.validators` defines a host of validator functions, but defining your own couldn't be easier:

    from django.core import validators, formfields

    class ContactManipulator(formfields.Manipulator):
        def __init__(self):
            self.fields = (
                # ... snip fields as above ...
                formfields.EmailField(field_name="to", validator_list=[self.isValidToAddress])
            )

        def isValidToAddress(self, field_data, all_data):
            if not field_data.endswith("@example.com"):
                raise ValidationError("You can only send messages to example.com e-mail addresses.")

Above, we've added a "to" field to the contact form, but required that the "to" address end with "@example.com" by adding the `isValidToAddress` validator to the field's `validator_list`.

The arguments to a validator function take a little explanation. `field_data` is the value of the field in question, and `all_data` is a dictionary of all the data being validated. Note that at the point validators are called all data will still be strings (as `do_html2python` hasn't been called yet).

Also, because consistency in user interfaces is important, we strongly urge you to put punctuation at the end of your validation messages.

## Comments

### Wiktor Sadowski July 24, 2005 at 9:06 p.m.

While I agree with : "every form needs to be designed differently" , providing a simple,default form renderer/template would be nice. As a start point.
Wiktor

### M.M. July 25, 2005 at 7:20 a.m.

Where is the best place to store custom manipulators?

in /apps/
or in /views/

in one file with ..., or in separate?

### Greg Hawkins August 5, 2005 at 9:27 a.m.

Perhaps it should be pointed out that to expose a datetime in a form you need two fields: form.{field}_date and form.{field}_time?

I discovered this only be looking at the admin pages' source.

### John August 24, 2005 at 2:05 p.m.

The create_form example may have a typo.

{{ errors|pluralize }} did not work for me.
{{ form.error_dict|pluralize }} worked fine.

### John August 29, 2005 at 12:38 p.m.

Seriously, where does one put custom manipulators?

### Garth T Kidd August 29, 2005 at 4:46 p.m.

The best place to put them when you're starting is in the same module as the view method that invokes them. Later on you might break them out. Or, you might not.

### S Pierce September 13, 2005 at 7:44 a.m.

It would be very helpful to have a complete example of a custom ChangeManipulator. The generic ChangeManipulator is passed the object id. If you are writing a custom one, you are responsible for the object id I assume in the same way that the generic one does. However, you don't explain what that responsibility is or how you are to use the object id submitted to your custom change manipulator.

### lorca September 22, 2005 at 10:48 a.m.

i want to create a template with these two items, all in one page, and they must be related with a foreign key

Person:
name
email
description
...

phones:
person = ForeignKey(Person)
number
description

Is there any way I can do this?

## Post a comment

Note: Please only use the comments for questions/critcisms/suggestions on the docs; if you experience errors please file a ticket, ask in the IRC channel, or post to the django-users list. Comments will be periodically reviewed, integrated into the documentation proper, and removed.

Your name:

Comment: