================== Working with forms ================== .. currentmodule:: django.forms .. admonition:: About this document This document provides an introduction to the basics of web forms and how they are handled in Django. For a more detailed look at specific areas of the forms API, see :doc:`/ref/forms/api`, :doc:`/ref/forms/fields`, and :doc:`/ref/forms/validation`. Unless you're planning to build Web sites and applications that do nothing but publish content, and don't accept input from your visitors, you're going to need to understand and use forms. Django provides a range of tools and libraries to help you build forms to accept input from site visitors, and then process and respond to the input. HTML forms ========== In HTML, a form is a collection of elements inside ``
`` that allow a visitor to do things like enter text, select options, manipulate objects or controls, and so on, and then send that information back to the server. Some of these form interface elements - text input or checkboxes - are fairly simple and are built into HTML itself. Others are much more complex; an interface that pops up a date picker or allows you to move a slider or manipulate controls will typically use JavaScript and CSS as well as HTML form ```` elements to achieve these effects. As well as its ```` elements, a form must specify two things: * *where*: the URL to which the data corresponding to the user's input should be returned * *how*: the HTTP method the data should be returned by As an example, the login form for the Django admin contains several ```` elements: one of ``type="text"`` for the username, one of ``type="password"`` for the password, and one of ``type="submit"`` for the "Log in" button. It also contains some hidden text fields that the user doesn't see, which Django uses to determine what to do next. It also tells the browser that the form data should be sent to the URL specified in the `` This tells the browser to return the form data to the URL ``/your-name/``, using the ``POST`` method. It will display a text field, labeled "Your name:", and a button marked "OK". If the template context contains a ``current_name`` variable, that will be used to pre-fill the ``your_name`` field. You'll need a view that renders the template containing the HTML form, and that can supply the ``current_name`` field as appropriate. When the form is submitted, the ``POST`` request which is sent to the server will contain the form data. Now you'll also need a view corresponding to that ``/your-name/`` URL which will find the appropriate key/value pairs in the request, and then process them. This is a very simple form. In practice, a form might contain dozens or hundreds of fields, many of which might need to be pre-populated, and we might expect the user to work through the edit-submit cycle several times before concluding the operation. We might require some validation to occur in the browser, even before the form is submitted; we might want to use much more complex fields, that allow the user to do things like pick dates from a calendar and so on. At this point it's much easier to get Django to do most of this work for us. Building a form in Django ------------------------- The :class:`Form` class ^^^^^^^^^^^^^^^^^^^^^^^ We already know what we want our HTML form to look like. Our starting point for it in Django is this: .. snippet:: :filename: forms.py from django import forms class NameForm(forms.Form): your_name = forms.CharField(label='Your name', max_length=100) This defines a :class:`Form` class with a single field (``your_name``). We've applied a human-friendly label to the field, which will appear in the ``