diff options
Diffstat (limited to 'docs/newforms.txt')
-rw-r--r-- | docs/newforms.txt | 104 |
1 files changed, 103 insertions, 1 deletions
diff --git a/docs/newforms.txt b/docs/newforms.txt index ed43670960..7ec4e9560c 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -602,6 +602,102 @@ when printed:: >>> str(f['subject'].errors) '' +Using forms in views and templates +---------------------------------- + +Let's put this all together and use the ``ContactForm`` example in a Django +view and template. This example view displays the contact form by default and +validates/processes it if accessed via a POST request:: + + def contact(request): + if request.method == 'POST': + form = ContactForm(request.POST) + if form.is_valid(): + # Do form processing here... + return HttpResponseRedirect('/url/on_success/') + else: + form = ContactForm() + return render_to_response('contact.html', {'form': form}) + +Simple template output +~~~~~~~~~~~~~~~~~~~~~~ + +The template, ``contact.html``, is responsible for displaying the form as HTML. +To do this, we can use the techniques outlined in the "Outputting forms as HTML" +section above. + +The simplest way to display a form's HTML is to use the variable on its own, +like this:: + + <form method="post"> + <table>{{ form }}</table> + <input type="submit" /> + </form> + +The above template code will display the form as an HTML table, using the +``form.as_table()`` method explained previously. This works because Django's +template system displays an object's ``__str__()`` value, and the ``Form`` +class' ``__str__()`` method calls its ``as_table()`` method. + +The following is equivalent but a bit more explicit:: + + <form method="post"> + <table>{{ form.as_table }}</table> + <input type="submit" /> + </form> + +``form.as_ul`` and ``form.as_p`` are also available, as you may expect. + +Note that in the above two examples, we included the ``<form>``, ``<table>`` +``<input type="submit" />``, ``</table>`` and ``</form>`` tags. The form +convenience methods (``as_table()``, ``as_ul()`` and ``as_p()``) do not include +that HTML. + +Complex template output +~~~~~~~~~~~~~~~~~~~~~~~ + +As we've stressed several times, the ``as_table()``, ``as_ul()`` and ``as_p()`` +methods are just shortcuts for the common case. You can also work with the +individual fields for complete template control over the form's design. + +The easiest way is to iterate over the form's fields, with +``{% for field in form %}``. For example:: + + <form method="post"> + <dl> + {% for field in form %} + <dt>{{ field.label }}</dt> + <dd>{{ field }}</dd> + {% if field.help_text %}<dd>{{ field.help_text }}</dd>{% endif %} + {% if field.errors %}<dd class="myerrors">{{ field.errors }}</dd>{% endif %} + {% endfor %} + </dl> + <input type="submit" /> + </form> + +This iteration technique is useful if you want to apply the same HTML +formatting to each field, or if you don't know the names of the form fields +ahead of time. Note that the fields will be listed in the order in which +they're defined in the ``Form`` class. + +Alternatively, you can arrange the form's fields explicitly, by name. Do that +by accessing ``{{ form.fieldname }}``, where ``fieldname`` is the field's name. +For example:: + + <form method="post"> + <ul class="myformclass"> + <li>{{ form.sender.label }} {{ form.sender.label }}</li> + <li class="helptext">{{ form.sender.help_text }}</li> + {% if form.sender.errors %}<ul class="errorlist">{{ form.sender.errors }}</dd>{% endif %} + + <li>{{ form.subject.label }} {{ form.subject.label }}</li> + <li class="helptext">{{ form.subject.help_text }}</li> + {% if form.subject.errors %}<ul class="errorlist">{{ form.subject.errors }}</dd>{% endif %} + + ... + </ul> + </form> + Subclassing forms ----------------- @@ -1157,10 +1253,11 @@ the full list of conversions: ``CommaSeparatedIntegerField`` ``CharField`` ``DateField`` ``DateField`` ``DateTimeField`` ``DateTimeField`` + ``DecimalField`` ``DecimalField`` ``EmailField`` ``EmailField`` ``FileField`` ``CharField`` ``FilePathField`` ``CharField`` - ``FloatField`` ``CharField`` + ``FloatField`` ``FloatField`` ``ForeignKey`` ``ModelChoiceField`` (see below) ``ImageField`` ``CharField`` ``IntegerField`` ``IntegerField`` @@ -1185,6 +1282,11 @@ the full list of conversions: ``XMLField`` ``CharField`` with ``widget=Textarea`` =============================== ======================================== + +.. note:: + The ``FloatField`` form field and ``DecimalField`` model and form fields + are new in the development version. + As you might expect, the ``ForeignKey`` and ``ManyToManyField`` model field types are special cases: |