From c6c25adf6d9f71ea11f61392f6f3d221f01e5216 Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss Date: Fri, 3 Apr 2009 18:30:54 +0000 Subject: Fixed a whole bunch of small docs typos, errors, and ommissions. Fixes #8358, #8396, #8724, #9043, #9128, #9247, #9267, #9267, #9375, #9409, #9414, #9416, #9446, #9454, #9464, #9503, #9518, #9533, #9657, #9658, #9683, #9733, #9771, #9835, #9836, #9837, #9897, #9906, #9912, #9945, #9986, #9992, #10055, #10084, #10091, #10145, #10245, #10257, #10309, #10358, #10359, #10424, #10426, #10508, #10531, #10551, #10635, #10637, #10656, #10658, #10690, #10699, #19528. Thanks to all the respective authors of those tickets. git-svn-id: http://code.djangoproject.com/svn/django/trunk@10371 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/forms/api.txt | 34 ++++++++++++++++++++++++ docs/ref/forms/fields.txt | 65 ++++++++++++---------------------------------- docs/ref/forms/widgets.txt | 9 ++++++- 3 files changed, 58 insertions(+), 50 deletions(-) (limited to 'docs/ref/forms') diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 96c0440fb3..7a2341f69b 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -129,6 +129,40 @@ what happens with unbound forms:: >>> f.errors {} +Dynamic initial values +---------------------- + +.. attribute:: Form.initial + +Use ``initial`` to declare the initial value of form fields at runtime. For +example, you might want to fill in a ``username`` field with the username of the +current session. + +To accomplish this, use the ``initial`` argument to a ``Form``. This argument, +if given, should be a dictionary mapping field names to initial values. Only +include the fields for which you're specifying an initial value; it's not +necessary to include every field in your form. For example:: + + >>> f = ContactForm(initial={'subject': 'Hi there!'}) + +These values are only displayed for unbound forms, and they're not used as +fallback values if a particular value isn't provided. + +Note that if a ``Field`` defines ``initial`` *and* you include ``initial`` when +instantiating the ``Form``, then the latter ``initial`` will have precedence. In +this example, ``initial`` is provided both at the field level and at the form +instance level, and the latter gets precedence:: + + >>> class CommentForm(forms.Form): + ... name = forms.CharField(initial='class') + ... url = forms.URLField() + ... comment = forms.CharField() + >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False) + >>> print f + Name: + Url: + Comment: + Accessing "clean" data ---------------------- diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index d1ff54908d..63ac707acf 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -127,6 +127,8 @@ We've specified ``auto_id=False`` to simplify the output:: The ``initial`` argument lets you specify the initial value to use when rendering this ``Field`` in an unbound ``Form``. +To specify dynamic initial data, see the :attr:`Form.initial` parameter. + The use-case for this is when you want to display an "empty" form in which a field is initialized to a particular value. For example:: @@ -234,7 +236,6 @@ fields. We've specified ``auto_id=False`` to simplify the output:: .. attribute:: Field.error_messages - The ``error_messages`` argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you want to override. For example, here is the default error message:: @@ -256,54 +257,6 @@ And here is a custom error message:: In the `built-in Field classes`_ section below, each ``Field`` defines the error message keys it uses. -Dynamic initial values ----------------------- - -The ``initial`` argument to ``Field`` (explained above) lets you hard-code the -initial value for a ``Field`` -- but what if you want to declare the initial -value at runtime? For example, you might want to fill in a ``username`` field -with the username of the current session. - -To accomplish this, use the ``initial`` argument to a ``Form``. This argument, -if given, should be a dictionary mapping field names to initial values. Only -include the fields for which you're specifying an initial value; it's not -necessary to include every field in your form. For example:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField() - ... url = forms.URLField() - ... comment = forms.CharField() - >>> f = CommentForm(initial={'name': 'your username'}, auto_id=False) - >>> print f - Name: - Url: - Comment: - >>> f = CommentForm(initial={'name': 'another username'}, auto_id=False) - >>> print f - Name: - Url: - Comment: - -Just like the ``initial`` parameter to ``Field``, these values are only -displayed for unbound forms, and they're not used as fallback values if a -particular value isn't provided. - -Finally, note that if a ``Field`` defines ``initial`` *and* you include -``initial`` when instantiating the ``Form``, then the latter ``initial`` will -have precedence. In this example, ``initial`` is provided both at the field -level and at the form instance level, and the latter gets precedence:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField(initial='class') - ... url = forms.URLField() - ... comment = forms.CharField() - >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False) - >>> print f - Name: - Url: - Comment: - - Built-in ``Field`` classes -------------------------- @@ -819,6 +772,20 @@ example:: def label_from_instance(self, obj): return "My Object #%i" % obj.id +.. attribute:: ModelChoiceField.empty_label + + By default the ``