innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

Removed trailing whitespace. 

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8201 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Gary Wilson Jr 2008-08-03 19:04:32 +00:00
parent cca261325a
commit 71b2e01ec2
1 changed files with 70 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
docs/forms.txt
View File

@ -39,7 +39,7 @@ The library deals with these concepts:
* **Media** -- A definition of the CSS and JavaScript resources that are * **Media** -- A definition of the CSS and JavaScript resources that are
required to render a form. required to render a form.
The library is decoupled from the other Django components, such as the database The library is decoupled from the other Django components, such as the database
layer, views and templates. It relies only on Django settings, a couple of layer, views and templates. It relies only on Django settings, a couple of
``django.utils`` helper functions and Django's internationalization hooks (but ``django.utils`` helper functions and Django's internationalization hooks (but
@ -1198,7 +1198,7 @@ given length.
Takes one extra argument, ``choices``, which is an iterable (e.g., a list or Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
tuple) of 2-tuples to use as choices for this field. This argument accepts tuple) of 2-tuples to use as choices for this field. This argument accepts
the same formats as the ``choices`` argument to a model field. See the the same formats as the ``choices`` argument to a model field. See the
`model API documentation on choices`_ for more details. `model API documentation on choices`_ for more details.
.. _model API documentation on choices: ../model-api#choices .. _model API documentation on choices: ../model-api#choices
@ -1324,33 +1324,33 @@ extra arguments:
============== ========== =============================================== ============== ========== ===============================================
Argument Required? Description Argument Required? Description
============== ========== =============================================== ============== ========== ===============================================
``path`` Yes The absolute path to the directory whose ``path`` Yes The absolute path to the directory whose
contents you want listed. This directory must contents you want listed. This directory must
exist. exist.
``recursive`` No If ``False`` (the default) only the direct ``recursive`` No If ``False`` (the default) only the direct
contents of ``path`` will be offered as choices. contents of ``path`` will be offered as choices.
If ``True``, the directory will be descended If ``True``, the directory will be descended
into recursively and all descendants will be into recursively and all descendants will be
listed as choices. listed as choices.
``match`` No A regular expression pattern; only files with ``match`` No A regular expression pattern; only files with
names matching this expression will be allowed names matching this expression will be allowed
as choices. as choices.
============== ========== =============================================== ============== ========== ===============================================
``FloatField`` ``FloatField``
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
* Default widget: ``TextInput`` * Default widget: ``TextInput``
* Empty value: ``None`` * Empty value: ``None``
* Normalizes to: A Python float. * Normalizes to: A Python float.
* Validates that the given value is an float. Leading and trailing * Validates that the given value is an float. Leading and trailing
whitespace is allowed, as in Python's ``float()`` function. whitespace is allowed, as in Python's ``float()`` function.
* Error message keys: ``required``, ``invalid``, ``max_value``, * Error message keys: ``required``, ``invalid``, ``max_value``,
``min_value`` ``min_value``
Takes two optional arguments for validation, ``max_value`` and ``min_value``. Takes two optional arguments for validation, ``max_value`` and ``min_value``.
These control the range of values permitted in the field. These control the range of values permitted in the field.
``ImageField`` ``ImageField``
@ -1410,7 +1410,7 @@ These control the range of values permitted in the field.
Takes one extra argument, ``choices``, which is an iterable (e.g., a list or Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
tuple) of 2-tuples to use as choices for this field. This argument accepts tuple) of 2-tuples to use as choices for this field. This argument accepts
the same formats as the ``choices`` argument to a model field. See the the same formats as the ``choices`` argument to a model field. See the
`model API documentation on choices`_ for more details. `model API documentation on choices`_ for more details.
``NullBooleanField`` ``NullBooleanField``
@ -1837,17 +1837,17 @@ They've been deprecated, but you can still `view the documentation`_.
Media Media
===== =====
Rendering an attractive and easy-to-use web form requires more than just Rendering an attractive and easy-to-use web form requires more than just
HTML - it also requires CSS stylesheets, and if you want to use fancy HTML - it also requires CSS stylesheets, and if you want to use fancy
"Web2.0" widgets, you may also need to include some JavaScript on each "Web2.0" widgets, you may also need to include some JavaScript on each
page. The exact combination of CSS and JavaScript that is required for page. The exact combination of CSS and JavaScript that is required for
any given page will depend upon the widgets that are in use on that page. any given page will depend upon the widgets that are in use on that page.
This is where Django media definitions come in. Django allows you to This is where Django media definitions come in. Django allows you to
associate different media files with the forms and widgets that require associate different media files with the forms and widgets that require
that media. For example, if you want to use a calendar to render DateFields, that media. For example, if you want to use a calendar to render DateFields,
you can define a custom Calendar widget. This widget can then be associated you can define a custom Calendar widget. This widget can then be associated
with the CSS and JavaScript that is required to render the calendar. When with the CSS and JavaScript that is required to render the calendar. When
the Calendar widget is used on a form, Django is able to identify the CSS and the Calendar widget is used on a form, Django is able to identify the CSS and
JavaScript files that are required, and provide the list of file names JavaScript files that are required, and provide the list of file names
in a form suitable for easy inclusion on your web page. in a form suitable for easy inclusion on your web page.
@ -1858,9 +1858,9 @@ in a form suitable for easy inclusion on your web page.
for calendars, filtered selections, and so on. These widgets define for calendars, filtered selections, and so on. These widgets define
media requirements, and the Django Admin uses the custom widgets media requirements, and the Django Admin uses the custom widgets
in place of the Django defaults. The Admin templates will only include in place of the Django defaults. The Admin templates will only include
those media files that are required to render the widgets on any those media files that are required to render the widgets on any
given page. given page.
If you like the widgets that the Django Admin application uses, If you like the widgets that the Django Admin application uses,
feel free to use them in your own application! They're all stored feel free to use them in your own application! They're all stored
in ``django.contrib.admin.widgets``. in ``django.contrib.admin.widgets``.
@ -1868,18 +1868,18 @@ in a form suitable for easy inclusion on your web page.
.. admonition:: Which JavaScript toolkit? .. admonition:: Which JavaScript toolkit?
Many JavaScript toolkits exist, and many of them include widgets (such Many JavaScript toolkits exist, and many of them include widgets (such
as calendar widgets) that can be used to enhance your application. as calendar widgets) that can be used to enhance your application.
Django has deliberately avoided blessing any one JavaScript toolkit. Django has deliberately avoided blessing any one JavaScript toolkit.
Each toolkit has its own relative strengths and weaknesses - use Each toolkit has its own relative strengths and weaknesses - use
whichever toolkit suits your requirements. Django is able to integrate whichever toolkit suits your requirements. Django is able to integrate
with any JavaScript toolkit. with any JavaScript toolkit.
Media as a static definition Media as a static definition
---------------------------- ----------------------------
The easiest way to define media is as a static definition. Using this method, The easiest way to define media is as a static definition. Using this method,
the media declaration is an inner class. The properties of the inner class the media declaration is an inner class. The properties of the inner class
define the media requirements. define the media requirements.
Here's a simple example:: Here's a simple example::
@ -1891,12 +1891,12 @@ Here's a simple example::
js = ('animations.js', 'actions.js') js = ('animations.js', 'actions.js')
This code defines a ``CalendarWidget``, which will be based on ``TextInput``. This code defines a ``CalendarWidget``, which will be based on ``TextInput``.
Every time the CalendarWidget is used on a form, that form will be directed Every time the CalendarWidget is used on a form, that form will be directed
to include the CSS file ``pretty.css``, and the JavaScript files to include the CSS file ``pretty.css``, and the JavaScript files
``animations.js`` and ``actions.js``. ``animations.js`` and ``actions.js``.
This static media definition is converted at runtime into a widget property This static media definition is converted at runtime into a widget property
named ``media``. The media for a CalendarWidget instance can be retrieved named ``media``. The media for a CalendarWidget instance can be retrieved
through this property:: through this property::
>>> w = CalendarWidget() >>> w = CalendarWidget()
@ -1910,16 +1910,16 @@ Here's a list of all possible ``Media`` options. There are no required options.
``css`` ``css``
~~~~~~~ ~~~~~~~
A dictionary describing the CSS files required for various forms of output A dictionary describing the CSS files required for various forms of output
media. media.
The values in the dictionary should be a tuple/list of file names. See The values in the dictionary should be a tuple/list of file names. See
`the section on media paths`_ for details of how to specify paths to media `the section on media paths`_ for details of how to specify paths to media
files. files.
.. _the section on media paths: `Paths in media definitions`_ .. _the section on media paths: `Paths in media definitions`_
The keys in the dictionary are the output media types. These are the same The keys in the dictionary are the output media types. These are the same
types accepted by CSS files in media declarations: 'all', 'aural', 'braille', types accepted by CSS files in media declarations: 'all', 'aural', 'braille',
'embossed', 'handheld', 'print', 'projection', 'screen', 'tty' and 'tv'. If 'embossed', 'handheld', 'print', 'projection', 'screen', 'tty' and 'tv'. If
you need to have different stylesheets for different media types, provide you need to have different stylesheets for different media types, provide
@ -1932,9 +1932,9 @@ provide two CSS options -- one for the screen, and one for print::
'print': ('newspaper.css',) 'print': ('newspaper.css',)
} }
If a group of CSS files are appropriate for multiple output media types, If a group of CSS files are appropriate for multiple output media types,
the dictionary key can be a comma separated list of output media types. the dictionary key can be a comma separated list of output media types.
In the following example, TV's and projectors will have the same media In the following example, TV's and projectors will have the same media
requirements:: requirements::
class Media: class Media:
@ -1943,29 +1943,29 @@ requirements::
'tv,projector': ('lo_res.css',), 'tv,projector': ('lo_res.css',),
'print': ('newspaper.css',) 'print': ('newspaper.css',)
} }
If this last CSS definition were to be rendered, it would become the following HTML:: If this last CSS definition were to be rendered, it would become the following HTML::
<link href="http://media.example.com/pretty.css" type="text/css" media="screen" rel="stylesheet" /> <link href="http://media.example.com/pretty.css" type="text/css" media="screen" rel="stylesheet" />
<link href="http://media.example.com/lo_res.css" type="text/css" media="tv,projector" rel="stylesheet" /> <link href="http://media.example.com/lo_res.css" type="text/css" media="tv,projector" rel="stylesheet" />
<link href="http://media.example.com/newspaper.css" type="text/css" media="print" rel="stylesheet" /> <link href="http://media.example.com/newspaper.css" type="text/css" media="print" rel="stylesheet" />
``js`` ``js``
~~~~~~ ~~~~~~
A tuple describing the required JavaScript files. See A tuple describing the required JavaScript files. See
`the section on media paths`_ for details of how to specify paths to media `the section on media paths`_ for details of how to specify paths to media
files. files.
``extend`` ``extend``
~~~~~~~~~~ ~~~~~~~~~~
A boolean defining inheritance behavior for media declarations. A boolean defining inheritance behavior for media declarations.
By default, any object using a static media definition will inherit all the By default, any object using a static media definition will inherit all the
media associated with the parent widget. This occurs regardless of how the media associated with the parent widget. This occurs regardless of how the
parent defines its media requirements. For example, if we were to extend our parent defines its media requirements. For example, if we were to extend our
basic Calendar widget from the example above:: basic Calendar widget from the example above::
class FancyCalendarWidget(CalendarWidget): class FancyCalendarWidget(CalendarWidget):
class Media: class Media:
@ -1982,13 +1982,13 @@ basic Calendar widget from the example above::
<script type="text/javascript" src="http://media.example.com/actions.js"></script> <script type="text/javascript" src="http://media.example.com/actions.js"></script>
<script type="text/javascript" src="http://media.example.com/whizbang.js"></script> <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>
The FancyCalendar widget inherits all the media from it's parent widget. If The FancyCalendar widget inherits all the media from it's parent widget. If
you don't want media to be inherited in this way, add an ``extend=False`` you don't want media to be inherited in this way, add an ``extend=False``
declaration to the media declaration:: declaration to the media declaration::
class FancyCalendar(Calendar): class FancyCalendar(Calendar):
class Media: class Media:
extend = False extend = False
css = { css = {
'all': ('fancy.css',) 'all': ('fancy.css',)
} }
@ -1999,19 +1999,19 @@ declaration to the media declaration::
<link href="http://media.example.com/fancy.css" type="text/css" media="all" rel="stylesheet" /> <link href="http://media.example.com/fancy.css" type="text/css" media="all" rel="stylesheet" />
<script type="text/javascript" src="http://media.example.com/whizbang.js"></script> <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>
If you require even more control over media inheritance, define your media If you require even more control over media inheritance, define your media
using a `dynamic property`_. Dynamic properties give you complete control over using a `dynamic property`_. Dynamic properties give you complete control over
which media files are inherited, and which are not. which media files are inherited, and which are not.
.. _dynamic property: `Media as a dynamic property`_ .. _dynamic property: `Media as a dynamic property`_
Media as a dynamic property Media as a dynamic property
--------------------------- ---------------------------
If you need to perform some more sophisticated manipulation of media If you need to perform some more sophisticated manipulation of media
requirements, you can define the media property directly. This is done requirements, you can define the media property directly. This is done
by defining a model property that returns an instance of ``forms.Media``. by defining a model property that returns an instance of ``forms.Media``.
The constructor for ``forms.Media`` accepts ``css`` and ``js`` keyword The constructor for ``forms.Media`` accepts ``css`` and ``js`` keyword
arguments in the same format as that used in a static media definition. arguments in the same format as that used in a static media definition.
For example, the static media definition for our Calendar Widget could For example, the static media definition for our Calendar Widget could
@ -2029,7 +2029,7 @@ return values for dynamic media properties.
Paths in media definitions Paths in media definitions
-------------------------- --------------------------
Paths used to specify media can be either relative or absolute. If a path Paths used to specify media can be either relative or absolute. If a path
starts with '/', 'http://' or 'https://', it will be interpreted as an absolute starts with '/', 'http://' or 'https://', it will be interpreted as an absolute
path, and left as-is. All other paths will be prepended with the value of path, and left as-is. All other paths will be prepended with the value of
``settings.MEDIA_URL``. For example, if the MEDIA_URL for your site was ``settings.MEDIA_URL``. For example, if the MEDIA_URL for your site was
@ -2053,15 +2053,15 @@ Media objects
When you interrogate the media attribute of a widget or form, the value that When you interrogate the media attribute of a widget or form, the value that
is returned is a ``forms.Media`` object. As we have already seen, the string is returned is a ``forms.Media`` object. As we have already seen, the string
representation of a Media object is the HTML required to include media representation of a Media object is the HTML required to include media
in the ``<head>`` block of your HTML page. in the ``<head>`` block of your HTML page.
However, Media objects have some other interesting properties. However, Media objects have some other interesting properties.
Media subsets Media subsets
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
If you only want media of a particular type, you can use the subscript operator If you only want media of a particular type, you can use the subscript operator
to filter out a medium of interest. For example:: to filter out a medium of interest. For example::
>>> w = CalendarWidget() >>> w = CalendarWidget()
@ -2073,7 +2073,7 @@ to filter out a medium of interest. For example::
>>> print w.media['css'] >>> print w.media['css']
<link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" /> <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
When you use the subscript operator, the value that is returned is a new When you use the subscript operator, the value that is returned is a new
Media object -- but one that only contains the media of interest. Media object -- but one that only contains the media of interest.
Combining media objects Combining media objects
@ -2100,7 +2100,7 @@ the resulting Media object contains the union of the media from both files::
<script type="text/javascript" src="http://media.example.com/animations.js"></script> <script type="text/javascript" src="http://media.example.com/animations.js"></script>
<script type="text/javascript" src="http://media.example.com/actions.js"></script> <script type="text/javascript" src="http://media.example.com/actions.js"></script>
<script type="text/javascript" src="http://media.example.com/whizbang.js"></script> <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>
Media on Forms Media on Forms
-------------- --------------
@ -2109,8 +2109,8 @@ can also define media. The rules for media definitions on forms are the
same as the rules for widgets: declarations can be static or dynamic; same as the rules for widgets: declarations can be static or dynamic;
path and inheritance rules for those declarations are exactly the same. path and inheritance rules for those declarations are exactly the same.
Regardless of whether you define a media declaration, *all* Form objects Regardless of whether you define a media declaration, *all* Form objects
have a media property. The default value for this property is the result have a media property. The default value for this property is the result
of adding the media definitions for all widgets that are part of the form:: of adding the media definitions for all widgets that are part of the form::
class ContactForm(forms.Form): class ContactForm(forms.Form):
@ -2124,7 +2124,7 @@ of adding the media definitions for all widgets that are part of the form::
<script type="text/javascript" src="http://media.example.com/actions.js"></script> <script type="text/javascript" src="http://media.example.com/actions.js"></script>
<script type="text/javascript" src="http://media.example.com/whizbang.js"></script> <script type="text/javascript" src="http://media.example.com/whizbang.js"></script>
If you want to associate additional media with a form -- for example, CSS for form If you want to associate additional media with a form -- for example, CSS for form
layout -- simply add a media declaration to the form:: layout -- simply add a media declaration to the form::
class ContactForm(forms.Form): class ContactForm(forms.Form):
@ -2135,7 +2135,7 @@ layout -- simply add a media declaration to the form::
css = { css = {
'all': ('layout.css',) 'all': ('layout.css',)
} }
>>> f = ContactForm() >>> f = ContactForm()
>>> f.media >>> f.media
<link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" /> <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" />
@ -2192,7 +2192,7 @@ example::
... {'title': u'Django is now open source', ... {'title': u'Django is now open source',
... 'pub_date': datetime.date.today()}, ... 'pub_date': datetime.date.today()},
... ]) ... ])
>>> for form in formset.forms: >>> for form in formset.forms:
... print form.as_table() ... print form.as_table()
<tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Django is now open source" id="id_form-0-title" /></td></tr> <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Django is now open source" id="id_form-0-title" /></td></tr>
@ -2281,11 +2281,11 @@ A formset has a ``clean`` method similar to the one on a ``Form`` class. This
is where you define your own validation that deals at the formset level:: is where you define your own validation that deals at the formset level::
>>> from django.forms.formsets import BaseFormSet >>> from django.forms.formsets import BaseFormSet
>>> class BaseArticleFormSet(BaseFormSet): >>> class BaseArticleFormSet(BaseFormSet):
... def clean(self): ... def clean(self):
... raise forms.ValidationError, u'An error occured.' ... raise forms.ValidationError, u'An error occured.'
>>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet) >>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet)
>>> formset = ArticleFormSet({}) >>> formset = ArticleFormSet({})
>>> formset.is_valid() >>> formset.is_valid()
@ -2348,7 +2348,7 @@ happen when the user changes these values::
... 'form-2-pub_date': u'2008-05-01', ... 'form-2-pub_date': u'2008-05-01',
... 'form-2-ORDER': u'0', ... 'form-2-ORDER': u'0',
... } ... }
>>> formset = ArticleFormSet(data, initial=[ >>> formset = ArticleFormSet(data, initial=[
... {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)}, ... {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)}, ... {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
@ -2403,7 +2403,7 @@ delete fields you can access them with ``deleted_forms``::
... 'form-2-pub_date': u'', ... 'form-2-pub_date': u'',
... 'form-2-DELETE': u'', ... 'form-2-DELETE': u'',
... } ... }
>>> formset = ArticleFormSet(data, initial=[ >>> formset = ArticleFormSet(data, initial=[
... {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)}, ... {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
... {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)}, ... {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},