From 97ccb9304ef578057640645013f5fb7eeafa246f Mon Sep 17 00:00:00 2001 From: Boulder Sprinters Date: Mon, 21 May 2007 16:50:14 +0000 Subject: boulder-oracle-sprint: Merged to [5306] git-svn-id: http://code.djangoproject.com/svn/django/branches/boulder-oracle-sprint@5307 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/forms.txt | 7 ++-- docs/install.txt | 4 +- docs/model-api.txt | 52 +++++++++++++++----------- docs/newforms.txt | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++- docs/settings.txt | 2 +- docs/tutorial02.txt | 2 +- 6 files changed, 141 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/forms.txt b/docs/forms.txt index 329e84a1b1..f6cb55a3f6 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -567,6 +567,7 @@ check for the given property: * isValidANSIDate * isValidANSITime * isValidEmail + * isValidFloat * isValidImage * isValidImageURL * isValidPhone @@ -664,10 +665,10 @@ fails. If no message is passed in, a default message is used. Takes an integer argument and when called as a validator, checks that the field being validated is a power of the integer. -``IsValidFloat`` +``IsValidDecimal`` Takes a maximum number of digits and number of decimal places (in that - order) and validates whether the field is a float with less than the - maximum number of digits and decimal place. + order) and validates whether the field is a decimal with no more than the + maximum number of digits and decimal places. ``MatchesRegularExpression`` Takes a regular expression (a string) as a parameter and validates the diff --git a/docs/install.txt b/docs/install.txt index c68179cba9..153aa85859 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -11,8 +11,8 @@ Being a Python Web framework, Django requires Python. It works with any Python version 2.3 and higher. -Get Python at www.python.org. If you're running Linux or Mac OS X, you probably -already have it installed. +Get Python at http://www.python.org. If you're running Linux or Mac OS X, you +probably already have it installed. Install Apache and mod_python ============================= diff --git a/docs/model-api.txt b/docs/model-api.txt index 59d415a124..be5676b25e 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -184,6 +184,33 @@ A date and time field. Takes the same extra options as ``DateField``. The admin represents this as two ```` fields, with JavaScript shortcuts. +``DecimalField`` +~~~~~~~~~~~~~~ + +A fixed-precision decimal number, represented in Python by a ``Decimal`` instance. +Has two **required** arguments: + + ====================== =================================================== + Argument Description + ====================== =================================================== + ``max_digits`` The maximum number of digits allowed in the number. + + ``decimal_places`` The number of decimal places to store with the + number. + ====================== =================================================== + +For example, to store numbers up to 999 with a resolution of 2 decimal places, +you'd use:: + + models.DecimalField(..., max_digits=5, decimal_places=2) + +And to store numbers up to approximately one billion with a resolution of 10 +decimal places:: + + models.DecimalField(..., max_digits=19, decimal_places=10) + +The admin represents this as an ```` (a single-line input). + ``EmailField`` ~~~~~~~~~~~~~~ @@ -290,26 +317,7 @@ because the ``match`` applies to the base filename (``foo.gif`` and ``FloatField`` ~~~~~~~~~~~~~~ -A floating-point number. Has two **required** arguments: - - ====================== =================================================== - Argument Description - ====================== =================================================== - ``max_digits`` The maximum number of digits allowed in the number. - - ``decimal_places`` The number of decimal places to store with the - number. - ====================== =================================================== - -For example, to store numbers up to 999 with a resolution of 2 decimal places, -you'd use:: - - models.FloatField(..., max_digits=5, decimal_places=2) - -And to store numbers up to approximately one billion with a resolution of 10 -decimal places:: - - models.FloatField(..., max_digits=19, decimal_places=10) +A floating-point number represented in Python by a ``float`` instance. The admin represents this as an ```` (a single-line input). @@ -1777,8 +1785,8 @@ But this template code is good:: {{ object.name }} .. note:: - The string you return from ``get_absolute_url()`` must be use only ASCII - characters (required by the URI spec, `RFC 2396`_) that has been + The string you return from ``get_absolute_url()`` must contain only ASCII + characters (required by the URI spec, `RFC 2396`_) that have been URL-encoded, if necessary. Code and templates using ``get_absolute_url()`` should be able to use the result directly without needing to do any further processing. 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 }}
+ +
+ +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.as_table }}
+ +
+ +``form.as_ul`` and ``form.as_p`` are also available, as you may expect. + +Note that in the above two examples, we included the ``
``, ```` +````, ``
`` and ``
`` 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:: + +
+
+ {% for field in form %} +
{{ field.label }}
+
{{ field }}
+ {% if field.help_text %}
{{ field.help_text }}
{% endif %} + {% if field.errors %}
{{ field.errors }}
{% endif %} + {% endfor %} +
+ +
+ +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:: + +
+