Changeset 8201
- Timestamp:
- 08/03/08 14:04:32 (5 months ago)
- Files:
-
- django/trunk/docs/forms.txt (modified) (31 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
django/trunk/docs/forms.txt
r8110 r8201 40 40 * **Media** -- A definition of the CSS and JavaScript resources that are 41 41 required to render a form. 42 42 43 43 The library is decoupled from the other Django components, such as the database 44 44 layer, views and templates. It relies only on Django settings, a couple of … … 1199 1199 Takes one extra argument, ``choices``, which is an iterable (e.g., a list or 1200 1200 tuple) of 2-tuples to use as choices for this field. This argument accepts 1201 the same formats as the ``choices`` argument to a model field. See the 1201 the same formats as the ``choices`` argument to a model field. See the 1202 1202 `model API documentation on choices`_ for more details. 1203 1203 … … 1325 1325 Argument Required? Description 1326 1326 ============== ========== =============================================== 1327 ``path`` Yes The absolute path to the directory whose 1328 contents you want listed. This directory must 1327 ``path`` Yes The absolute path to the directory whose 1328 contents you want listed. This directory must 1329 1329 exist. 1330 1330 1331 1331 ``recursive`` No If ``False`` (the default) only the direct 1332 1332 contents of ``path`` will be offered as choices. … … 1334 1334 into recursively and all descendants will be 1335 1335 listed as choices. 1336 1336 1337 1337 ``match`` No A regular expression pattern; only files with 1338 1338 names matching this expression will be allowed … … 1340 1340 ============== ========== =============================================== 1341 1341 1342 ``FloatField`` 1343 ~~~~~~~~~~~~~~ 1344 1345 * Default widget: ``TextInput`` 1346 * Empty value: ``None`` 1347 * Normalizes to: A Python float. 1348 * Validates that the given value is an float. Leading and trailing 1349 whitespace is allowed, as in Python's ``float()`` function. 1350 * Error message keys: ``required``, ``invalid``, ``max_value``, 1351 ``min_value`` 1352 1353 Takes two optional arguments for validation, ``max_value`` and ``min_value``. 1342 ``FloatField`` 1343 ~~~~~~~~~~~~~~ 1344 1345 * Default widget: ``TextInput`` 1346 * Empty value: ``None`` 1347 * Normalizes to: A Python float. 1348 * Validates that the given value is an float. Leading and trailing 1349 whitespace is allowed, as in Python's ``float()`` function. 1350 * Error message keys: ``required``, ``invalid``, ``max_value``, 1351 ``min_value`` 1352 1353 Takes two optional arguments for validation, ``max_value`` and ``min_value``. 1354 1354 These control the range of values permitted in the field. 1355 1355 … … 1411 1411 Takes one extra argument, ``choices``, which is an iterable (e.g., a list or 1412 1412 tuple) of 2-tuples to use as choices for this field. This argument accepts 1413 the same formats as the ``choices`` argument to a model field. See the 1413 the same formats as the ``choices`` argument to a model field. See the 1414 1414 `model API documentation on choices`_ for more details. 1415 1415 … … 1838 1838 ===== 1839 1839 1840 Rendering an attractive and easy-to-use web form requires more than just 1841 HTML - it also requires CSS stylesheets, and if you want to use fancy 1842 "Web2.0" widgets, you may also need to include some JavaScript on each 1843 page. The exact combination of CSS and JavaScript that is required for 1840 Rendering an attractive and easy-to-use web form requires more than just 1841 HTML - it also requires CSS stylesheets, and if you want to use fancy 1842 "Web2.0" widgets, you may also need to include some JavaScript on each 1843 page. The exact combination of CSS and JavaScript that is required for 1844 1844 any given page will depend upon the widgets that are in use on that page. 1845 1845 1846 This is where Django media definitions come in. Django allows you to 1846 This is where Django media definitions come in. Django allows you to 1847 1847 associate different media files with the forms and widgets that require 1848 that media. For example, if you want to use a calendar to render DateFields, 1849 you can define a custom Calendar widget. This widget can then be associated 1850 with the CSS and JavaScript that is required to render the calendar. When 1848 that media. For example, if you want to use a calendar to render DateFields, 1849 you can define a custom Calendar widget. This widget can then be associated 1850 with the CSS and JavaScript that is required to render the calendar. When 1851 1851 the Calendar widget is used on a form, Django is able to identify the CSS and 1852 1852 JavaScript files that are required, and provide the list of file names … … 1859 1859 media requirements, and the Django Admin uses the custom widgets 1860 1860 in place of the Django defaults. The Admin templates will only include 1861 those media files that are required to render the widgets on any 1861 those media files that are required to render the widgets on any 1862 1862 given page. 1863 1863 1864 1864 If you like the widgets that the Django Admin application uses, 1865 1865 feel free to use them in your own application! They're all stored … … 1869 1869 1870 1870 Many JavaScript toolkits exist, and many of them include widgets (such 1871 as calendar widgets) that can be used to enhance your application. 1871 as calendar widgets) that can be used to enhance your application. 1872 1872 Django has deliberately avoided blessing any one JavaScript toolkit. 1873 Each toolkit has its own relative strengths and weaknesses - use 1873 Each toolkit has its own relative strengths and weaknesses - use 1874 1874 whichever toolkit suits your requirements. Django is able to integrate 1875 with any JavaScript toolkit. 1875 with any JavaScript toolkit. 1876 1876 1877 1877 Media as a static definition … … 1880 1880 The easiest way to define media is as a static definition. Using this method, 1881 1881 the media declaration is an inner class. The properties of the inner class 1882 define the media requirements. 1882 define the media requirements. 1883 1883 1884 1884 Here's a simple example:: … … 1892 1892 1893 1893 This code defines a ``CalendarWidget``, which will be based on ``TextInput``. 1894 Every time the CalendarWidget is used on a form, that form will be directed 1895 to include the CSS file ``pretty.css``, and the JavaScript files 1896 ``animations.js`` and ``actions.js``. 1894 Every time the CalendarWidget is used on a form, that form will be directed 1895 to include the CSS file ``pretty.css``, and the JavaScript files 1896 ``animations.js`` and ``actions.js``. 1897 1897 1898 1898 This static media definition is converted at runtime into a widget property 1899 named ``media``. The media for a CalendarWidget instance can be retrieved 1899 named ``media``. The media for a CalendarWidget instance can be retrieved 1900 1900 through this property:: 1901 1901 … … 1911 1911 ~~~~~~~ 1912 1912 1913 A dictionary describing the CSS files required for various forms of output 1914 media. 1913 A dictionary describing the CSS files required for various forms of output 1914 media. 1915 1915 1916 1916 The values in the dictionary should be a tuple/list of file names. See 1917 `the section on media paths`_ for details of how to specify paths to media 1917 `the section on media paths`_ for details of how to specify paths to media 1918 1918 files. 1919 1919 1920 1920 .. _the section on media paths: `Paths in media definitions`_ 1921 1921 1922 The keys in the dictionary are the output media types. These are the same 1922 The keys in the dictionary are the output media types. These are the same 1923 1923 types accepted by CSS files in media declarations: 'all', 'aural', 'braille', 1924 1924 'embossed', 'handheld', 'print', 'projection', 'screen', 'tty' and 'tv'. If … … 1933 1933 } 1934 1934 1935 If a group of CSS files are appropriate for multiple output media types, 1936 the dictionary key can be a comma separated list of output media types. 1937 In the following example, TV's and projectors will have the same media 1935 If a group of CSS files are appropriate for multiple output media types, 1936 the dictionary key can be a comma separated list of output media types. 1937 In the following example, TV's and projectors will have the same media 1938 1938 requirements:: 1939 1939 … … 1944 1944 'print': ('newspaper.css',) 1945 1945 } 1946 1946 1947 1947 If this last CSS definition were to be rendered, it would become the following HTML:: 1948 1948 … … 1950 1950 <link href="http://media.example.com/lo_res.css" type="text/css" media="tv,projector" rel="stylesheet" /> 1951 1951 <link href="http://media.example.com/newspaper.css" type="text/css" media="print" rel="stylesheet" /> 1952 1952 1953 1953 ``js`` 1954 1954 ~~~~~~ 1955 1955 1956 1956 A tuple describing the required JavaScript files. See 1957 `the section on media paths`_ for details of how to specify paths to media 1957 `the section on media paths`_ for details of how to specify paths to media 1958 1958 files. 1959 1959 1960 ``extend`` 1960 ``extend`` 1961 1961 ~~~~~~~~~~ 1962 1962 1963 A boolean defining inheritance behavior for media declarations. 1963 A boolean defining inheritance behavior for media declarations. 1964 1964 1965 1965 By default, any object using a static media definition will inherit all the 1966 media associated with the parent widget. This occurs regardless of how the 1966 media associated with the parent widget. This occurs regardless of how the 1967 1967 parent defines its media requirements. For example, if we were to extend our 1968 basic Calendar widget from the example above:: 1968 basic Calendar widget from the example above:: 1969 1969 1970 1970 class FancyCalendarWidget(CalendarWidget): … … 1983 1983 <script type="text/javascript" src="http://media.example.com/whizbang.js"></script> 1984 1984 1985 The FancyCalendar widget inherits all the media from it's parent widget. If 1985 The FancyCalendar widget inherits all the media from it's parent widget. If 1986 1986 you don't want media to be inherited in this way, add an ``extend=False`` 1987 1987 declaration to the media declaration:: … … 1989 1989 class FancyCalendar(Calendar): 1990 1990 class Media: 1991 extend = False 1991 extend = False 1992 1992 css = { 1993 1993 'all': ('fancy.css',) … … 2000 2000 <script type="text/javascript" src="http://media.example.com/whizbang.js"></script> 2001 2001 2002 If you require even more control over media inheritance, define your media 2002 If you require even more control over media inheritance, define your media 2003 2003 using a `dynamic property`_. Dynamic properties give you complete control over 2004 2004 which media files are inherited, and which are not. 2005 2005 2006 2006 .. _dynamic property: `Media as a dynamic property`_ 2007 2007 2008 2008 Media as a dynamic property 2009 2009 --------------------------- … … 2012 2012 requirements, you can define the media property directly. This is done 2013 2013 by defining a model property that returns an instance of ``forms.Media``. 2014 The constructor for ``forms.Media`` accepts ``css`` and ``js`` keyword 2014 The constructor for ``forms.Media`` accepts ``css`` and ``js`` keyword 2015 2015 arguments in the same format as that used in a static media definition. 2016 2016 … … 2030 2030 -------------------------- 2031 2031 2032 Paths used to specify media can be either relative or absolute. If a path 2032 Paths used to specify media can be either relative or absolute. If a path 2033 2033 starts with '/', 'http://' or 'https://', it will be interpreted as an absolute 2034 2034 path, and left as-is. All other paths will be prepended with the value of … … 2054 2054 When you interrogate the media attribute of a widget or form, the value that 2055 2055 is returned is a ``forms.Media`` object. As we have already seen, the string 2056 representation of a Media object is the HTML required to include media 2057 in the ``<head>`` block of your HTML page. 2056 representation of a Media object is the HTML required to include media 2057 in the ``<head>`` block of your HTML page. 2058 2058 2059 2059 However, Media objects have some other interesting properties. … … 2062 2062 ~~~~~~~~~~~~~ 2063 2063 2064 If you only want media of a particular type, you can use the subscript operator 2064 If you only want media of a particular type, you can use the subscript operator 2065 2065 to filter out a medium of interest. For example:: 2066 2066 … … 2074 2074 <link href="http://media.example.com/pretty.css" type="text/css" media="all" rel="stylesheet" /> 2075 2075 2076 When you use the subscript operator, the value that is returned is a new 2076 When you use the subscript operator, the value that is returned is a new 2077 2077 Media object -- but one that only contains the media of interest. 2078 2078 … … 2101 2101 <script type="text/javascript" src="http://media.example.com/actions.js"></script> 2102 2102 <script type="text/javascript" src="http://media.example.com/whizbang.js"></script> 2103 2103 2104 2104 Media on Forms 2105 2105 -------------- … … 2110 2110 path and inheritance rules for those declarations are exactly the same. 2111 2111 2112 Regardless of whether you define a media declaration, *all* Form objects 2113 have a media property. The default value for this property is the result 2112 Regardless of whether you define a media declaration, *all* Form objects 2113 have a media property. The default value for this property is the result 2114 2114 of adding the media definitions for all widgets that are part of the form:: 2115 2115 … … 2125 2125 <script type="text/javascript" src="http://media.example.com/whizbang.js"></script> 2126 2126 2127 If you want to associate additional media with a form -- for example, CSS for form 2127 If you want to associate additional media with a form -- for example, CSS for form 2128 2128 layout -- simply add a media declaration to the form:: 2129 2129 … … 2136 2136 'all': ('layout.css',) 2137 2137 } 2138 2138 2139 2139 >>> f = ContactForm() 2140 2140 >>> f.media … … 2193 2193 ... 'pub_date': datetime.date.today()}, 2194 2194 ... ]) 2195 2195 2196 2196 >>> for form in formset.forms: 2197 2197 ... print form.as_table() … … 2282 2282 2283 2283 >>> from django.forms.formsets import BaseFormSet 2284 2284 2285 2285 >>> class BaseArticleFormSet(BaseFormSet): 2286 2286 ... def clean(self): 2287 2287 ... raise forms.ValidationError, u'An error occured.' 2288 2288 2289 2289 >>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet) 2290 2290 >>> formset = ArticleFormSet({}) … … 2349 2349 ... 'form-2-ORDER': u'0', 2350 2350 ... } 2351 2351 2352 2352 >>> formset = ArticleFormSet(data, initial=[ 2353 2353 ... {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)}, … … 2404 2404 ... 'form-2-DELETE': u'', 2405 2405 ... } 2406 2406 2407 2407 >>> formset = ArticleFormSet(data, initial=[ 2408 2408 ... {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
