Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Form topic documentation work #128

Closed
wants to merge 2 commits into from

2 participants

@audreyr

I revised the text in the 'Using a form in a view' section to make it more readable.

@audreyr

@aaugustin This is ready for review.

@audreyr

@aaugustin Added a second commit that is still part of the same 'Working with forms' topic documentation file. I revised the text to be friendlier without losing any content.

@aaugustin
Owner

I have merged the commits in Django, but since I've edited one of them, GitHub didn't notice.

The new version is much more readable, thanks!

@aaugustin aaugustin closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 45 additions and 33 deletions.
  1. +45 −33 docs/topics/forms/index.txt
View
78 docs/topics/forms/index.txt
@@ -104,48 +104,58 @@ The standard pattern for processing a form in a view looks like this:
})
-There are three code paths here:
-
-1. If the form has not been submitted, an unbound instance of ContactForm is
- created and passed to the template.
-2. If the form has been submitted, a bound instance of the form is created
- using ``request.POST``. If the submitted data is valid, it is processed
- and the user is re-directed to a "thanks" page.
-3. If the form has been submitted but is invalid, the bound form instance is
- passed on to the template.
-
-The distinction between **bound** and **unbound** forms is important. An unbound
-form does not have any data associated with it; when rendered to the user, it
-will be empty or will contain default values. A bound form does have submitted
-data, and hence can be used to tell if that data is valid. If an invalid bound
-form is rendered it can include inline error messages telling the user where
-they went wrong.
-
-See :ref:`ref-forms-api-bound-unbound` for further information on the
-differences between bound and unbound forms.
+There are three possible code paths here:
+
++------------------+---------------+-----------------------------------------+
+| Form submitted? | Data? | What occurs |
++==================+===============+=========================================+
+| Unsubmitted | None yet | Template gets passed unbound instance |
+| | | of ContactForm. |
++------------------+---------------+-----------------------------------------+
+| Submitted | Invalid data | Template gets passed bound instance |
+| | | of ContactForm. |
++------------------+---------------+-----------------------------------------+
+| Submitted | Valid data | Valid data is processed. Redirect to a |
+| | | "thanks" page. |
++------------------+---------------+-----------------------------------------+
+
+The distinction between :ref:`ref-forms-api-bound-unbound` is important:
+
+* An unbound form has no data associated with it. When rendered to the user,
+ it will be empty or will contain default values.
+
+* A bound form has submitted data, and hence can be used to tell if that data
+ is valid. If an invalid bound form is rendered, it can include inline error
+ messages telling the user what data to correct.
Handling file uploads with a form
---------------------------------
-To see how to handle file uploads with your form see
-:ref:`binding-uploaded-files` for more information.
+To see how to handle file uploads with your form, see
+:ref:`binding-uploaded-files`.
Processing the data from a form
-------------------------------
-Once ``is_valid()`` returns ``True``, you can process the form submission safe
-in the knowledge that it conforms to the validation rules defined by your form.
-While you could access ``request.POST`` directly at this point, it is better to
-access ``form.cleaned_data``. This data has not only been validated but will
-also be converted in to the relevant Python types for you. In the above example,
-``cc_myself`` will be a boolean value. Likewise, fields such as ``IntegerField``
-and ``FloatField`` convert values to a Python int and float respectively. Note
-that read-only fields are not available in ``form.cleaned_data`` (and setting
-a value in a custom ``clean()`` method won't have any effect) because these
+Once ``is_valid()`` returns ``True``, the successfully validated form data will
+be in the ``form.cleaned_data`` dictionary. This data will also converted nicely
+into Python types for you.
+
+.. note::
+
+ You can still access the unvalidated data directly from ``request.POST`` at
+ this point, but the validated data is better.
+
+In the above example, ``cc_myself`` will be a boolean value. Likewise, fields
+such as ``IntegerField`` and ``FloatField`` convert values to a Python int and
+float respectively.
+
+Read-only fields are not available in ``form.cleaned_data`` (and setting
+a value in a custom ``clean()`` method won't have any effect). These
fields are displayed as text rather than as input elements, and thus are not
posted back to the server.
-Extending the above example, here's how the form data could be processed:
+Extending the earlier example, here's how the form data could be processed:
.. code-block:: python
@@ -163,7 +173,9 @@ Extending the above example, here's how the form data could be processed:
send_mail(subject, message, sender, recipients)
return HttpResponseRedirect('/thanks/') # Redirect after POST
-For more on sending email from Django, see :doc:`/topics/email`.
+.. tip::
+
+ For more on sending email from Django, see :doc:`/topics/email`.
Displaying a form using a template
----------------------------------
@@ -294,7 +306,7 @@ templates:
The field's label wrapped in the appropriate HTML ``<label>`` tag,
e.g. ``<label for="id_email">Email address</label>``
-``{{ field.value }}``
+``{{ field.value }}``
The value of the field. e.g ``someone@example.com``
``{{ field.html_name }}``
Something went wrong with that request. Please try again.