queryset-refactor: Merged from trunk up to [6752].

git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@6753 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 37 insertions, 5 deletions

diff --git a/docs/newforms.txt b/docs/newforms.txt
index 593e9216d7..810982d788 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -753,6 +753,30 @@ For example::
     </ul>
     </form>
 
+Highlighting required fields in templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may wish to show a visitor which fields are required. Here is the above
+example modified to insert an asterix after the label of each required field::
+
+    <form method="post" action="">
+    <dl>
+    {% for field in form %}
+        <dt>{{ field.label_tag }}{{ field.label }}{% if field.field.required %}*{% endif %}</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>
+
+The ``{% if field.field.required %}*{% endif %}`` fragment is the relevant
+addition here. It adds the asterix only if the field is required. Note that we
+check ``field.field.required`` and not ``field.required``. In the template,
+``field`` is a ``newforms.forms.BoundField`` instance, which holds the actual
+``Field`` instance in its ``field`` attribute.
+
 Binding uploaded files to a form
 --------------------------------
 
@@ -1849,7 +1873,11 @@ In addition, each generated form field has attributes set as follows:
 
     * If the model field has ``choices`` set, then the form field's ``widget``
       will be set to ``Select``, with choices coming from the model field's
-      ``choices``.
+      ``choices``. The choices will normally include the blank choice which is
+      selected by default. If the field is required, this forces the user to
+      make a selection. The blank choice will not be included if the model
+      field has ``blank=False`` and an explicit ``default`` value (the
+      ``default`` value will be initially selected instead).
 
 Finally, note that you can override the form field used for a given model
 field. See "Overriding the default field types" below.
@@ -2095,10 +2123,14 @@ instance instead of a model class::
     # Instantiate the form.
     >>> f = AuthorForm()
 
-When a form created by ``form_for_instance()`` is created, the initial
-data values for the form fields are drawn from the instance. However,
-this data is not bound to the form. You will need to bind data to the
-form before the form can be saved.
+When a form created by ``form_for_instance()`` is created, the initial data
+values for the form fields are drawn from the instance. However, this data is
+not bound to the form. You will need to bind data to the form before the form
+can be saved.
+
+Unlike ``form_for_model()``, a choice field in form created by
+``form_for_instance()`` will not include the blank choice if the respective
+model field has ``blank=False``. The initial choice is drawn from the instance.
 
 When you call ``save()`` on a form created by ``form_for_instance()``,
 the database instance will be updated. As in ``form_for_model()``, ``save()``