Ticket #11185: 11185.diff

File 11185.diff, 16.0 KB (added by timo, 3 years ago)

Updated parts of fadeev that are still applicable

  • docs/ref/forms/fields.txt

    diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
    index 082ec17..6a991a8 100644
    a b Slightly complex built-in ``Field`` classes 
    842842``MultiValueField``
    843843~~~~~~~~~~~~~~~~~~~
    844844
    845 .. class:: MultiValueField(**kwargs)
     845.. class:: MultiValueField(fields=(), **kwargs)
    846846
    847847    * Default widget: ``TextInput``
    848848    * Empty value: ``''`` (an empty string)
    Slightly complex built-in ``Field`` classes 
    851851      as an argument to the ``MultiValueField``.
    852852    * Error message keys: ``required``, ``invalid``
    853853
    854     This abstract field (must be subclassed) aggregates the logic of multiple
    855     fields. Subclasses should not have to implement clean(). Instead, they must
    856     implement compress(), which takes a list of valid values and returns a
    857     "compressed" version of those values -- a single value.  For example,
    858     :class:`SplitDateTimeField` is a subclass which combines a time field and
    859     a date field into a datetime object.
     854    Aggregates the logic of multiple fields that together produce a single
     855    value.
     856
     857    This field is abstract and must be subclassed. In contrast with the
     858    single-value fields, subclasses of :class:`MultiValueField` must not
     859    implement :meth:`~django.forms.Field.clean` but instead - implement
     860    :meth:`~MultiValueField.compress`.
    860861
    861862    Takes one extra required argument:
    862863
    863864    .. attribute:: fields
    864865
    865         A list of fields which are cleaned into a single field. Each value in
    866         ``clean`` is cleaned by the corresponding field in ``fields`` -- the first
    867         value is cleaned by the first field, the second value is cleaned by
    868         the second field, etc.  Once all fields are cleaned, the list of clean
    869         values is "compressed" into a single value.
     866        A tuple of fields whose values are cleaned and subsequently combined
     867        into a single value.  Each value of the field is cleaned by the
     868        corresponding field in ``fields`` -- the first value is cleaned by the
     869        first field, the second value is cleaned by the second field, etc.
     870        Once all fields are cleaned, the list of clean values is is combined
     871        into a single value by :meth:`~MultiValueField.compress`.
     872
     873    .. attribute:: MultiValueField.widget
     874
     875        Must be a subclass of :class:`django.forms.MultiWidget`.
     876        Default value is :class:`~django.forms.widgets.TextInput`, which is
     877        probably is not very useful in this case.
     878
     879    .. method:: compress(data_list)
     880
     881        Takes a list of valid values and returns  a "compressed" version of
     882        those values -- in a single value. For example,
     883        :class:`SplitDateTimeField` is a subclass which combines a time field
     884        and a date field into a ``datetime`` object.
     885
     886        This method must be implemented in the subclasses.
    870887
    871888``SplitDateTimeField``
    872889~~~~~~~~~~~~~~~~~~~~~~
  • docs/ref/forms/widgets.txt

    diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
    index fb76573..4255de7 100644
    a b A widget is Django's representation of a HTML input element. The widget 
    1111handles the rendering of the HTML, and the extraction of data from a GET/POST
    1212dictionary that corresponds to the widget.
    1313
     14.. tip::
     15
     16    Widgets should not be confused with the :doc:`form fields </ref/forms/fields>`.
     17    Form fields deal with the logic of input validation and are used directly
     18    in templates. Widgets deal with rendering of HTML form input elements on
     19    the web page and extraction of raw submitted data. However, widgets do
     20    need to be :ref:`assigned <widget-to-field>` to form fields.
     21
     22.. _widget-to-field:
     23
    1424Specifying widgets
    1525------------------
    1626
    choices are inherent to the model and not just the representational widget. 
    95105Customizing widget instances
    96106----------------------------
    97107
    98 When Django renders a widget as HTML, it only renders the bare minimum
    99 HTML - Django doesn't add a class definition, or any other widget-specific
    100 attributes. This means that all :class:`TextInput` widgets will appear the same
    101 on your Web page.
     108When Django renders a widget as HTML, it only renders very minimal markup -
     109Django doesn't add class names, or any other widget-specific attributes. This
     110means, for example, that all :class:`TextInput` widgets will appear the same
     111on your Web pages.
     112
     113There are two ways to customize widgets: :ref:`per widget instance
     114<styling-widget-instances>` and :ref:`per widget class <styling-widget-classes>`.
    102115
    103 If you want to make one widget look different to another, you need to
    104 specify additional attributes for each widget. When you specify a
    105 widget, you can provide a list of attributes that will be added to the
    106 rendered HTML for the widget.
     116.. _styling-widget-instances:
     117
     118Styling widget instances
     119^^^^^^^^^^^^^^^^^^^^^^^^
     120
     121If you want to make one widget instance look different from another, you will
     122need to specify additional attributes at the time when the widget object is
     123instantiated and assigned to a form field (and perhaps add some rules to your
     124css files).
    107125
    108126For example, take the following simple form::
    109127
    provided for each widget will be rendered exactly the same:: 
    127145On a real Web page, you probably don't want every widget to look the same. You
    128146might want a larger input element for the comment, and you might want the
    129147'name' widget to have some special CSS class. To do this, you use the
    130 :attr:`Widget.attrs` argument when creating the widget:
    131 
    132 For example::
     148:attr:`Widget.attrs` argument when creating the widget::
    133149
    134150    class CommentForm(forms.Form):
    135151        name = forms.CharField(
    Django will then include the extra attributes in the rendered output: 
    146162    <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
    147163    <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
    148164
    149 .. _built-in widgets:
     165.. _styling-widget-classes:
    150166
    151 Built-in widgets
    152 ----------------
     167Styling widget classes
     168^^^^^^^^^^^^^^^^^^^^^^
    153169
    154 Django provides a representation of all the basic HTML widgets, plus some
    155 commonly used groups of widgets:
     170With widgets, it is possible to add media (``css`` and ``javascript``)
     171and more deeply customise their appearance and behavior.
    156172
    157 ``Widget``
    158 ~~~~~~~~~~
     173In a nutshell, you will need to subclass the widget and either
     174:ref:`define a class "Media" <media-as-a-static-definition>` as a member of the
     175subclass, or :ref:`create a property "media" <dynamic-property>`, returning an
     176instance of that class.
     177
     178These methods involve somewhat advanced Python programming and are described in
     179detail in the :doc:`Form Media </topics/forms/media>` topic guide.
     180
     181.. _base-widget-classes:
     182
     183Base Widget classes
     184-------------------
    159185
    160 .. class:: Widget
     186Base widget classes :class:`Widget` and :class:`MultiWidget` are subclassed by
     187all the :ref:`built-in widgets <built-in widgets>` and may serve as a
     188foundation for custom widgets (but, please see the warning below).
    161189
    162     This abstract class cannot be rendered, but provides the basic attribute :attr:`~Widget.attrs`.
     190.. warning::
     191
     192    Interfaces of classes :class:`~django.forms.widgets.Widget` and
     193    :class:`~django.forms.widgets.MultiWidget` are still in flux, therefore -
     194    please take care to test all of your custom widgets when upgrading Django.
     195
     196    It is a particularly good idea to write :doc:`tests </topics/testing>`
     197    for any of your custom widgets.
     198
     199.. class:: Widget(attrs=None)
     200
     201    This abstract class cannot be rendered, but provides the basic attribute
     202    :attr:`~Widget.attrs`.  You may also implement or override the
     203    :meth:`~Widget.render()` method on custom widgets.
    163204
    164205    .. attribute:: Widget.attrs
    165206
    166         A dictionary containing HTML attributes to be set on the rendered widget.
     207        A dictionary containing HTML attributes to be set on the rendered
     208        widget.
    167209
    168210        .. code-block:: python
    169211
    commonly used groups of widgets: 
    171213            >>> name.render('name', 'A name')
    172214            u'<input title="Your name" type="text" name="name" value="A name" size="10" />'
    173215
     216    .. method:: render(name, value, attrs=None)
     217
     218        Returns HTML for the widget, as a Unicode string. This method must be
     219        implemented by the subclass, otherwise ``NotImplementedError`` will be
     220        raised.
     221
     222        The 'value' given is not guaranteed to be valid input, therefore
     223        subclass implementations should program defensively.
     224
     225.. class:: MultiWidget(widgets, attrs=None)
     226
     227    A widget that is composed of multiple widgets.
     228    :class:`~django.forms.widgets.MultiWidget` works hand in hand with the
     229    :class:`~django.forms.MultiValueField`.
     230
     231    .. method:: render(name, value, attrs=None)
     232
     233        Argument `value` is handled differently in this method from the
     234        subclasses of :class:`~Widget`.
     235
     236        If `value` is a list, output of :meth:`~MultiWidget.render` will be a
     237        concatenation of rendered child widgets. If `value` is not a list, it
     238        will be first processed by the method
     239        :meth:`~MultiWidget.decompress()` to create the
     240        list, and then processed as above.
     241
     242        Unlike in the single value widgets, method :meth:`~MultiWidget.render`
     243        need not be implemented in the subclasses.
     244
     245    .. method:: decompress(value)
     246
     247        Returns a list of "decompressed" values for the given value of the
     248        multi-value field that makes use of the widget. The input value can be
     249        assumed as valid, but not necessarily non-empty.
     250
     251        This method **must be implemented** by the subclass, and since the
     252        value may be empty, the implementation must be defensive.
     253
     254        The rationale behind "decompression" is that it is necessary to "split"
     255        the combined value of the form field into the values of the individual
     256        field encapsulated within the multi-value field (e.g. when displaying
     257        the partially or fully filled-out form).
     258
     259        .. tip::
     260
     261            Note that :class:`~django.forms.MultiValueField` has a
     262            complementary method :meth:`~django.forms.MultiValueField.compress`
     263            with the opposite responsibility - combine cleaned values of
     264            all memeber fields into one.
     265
     266
     267.. _built-in widgets:
     268
     269Built-in widgets
     270----------------
     271
     272Django provides a representation of all the basic HTML widgets, plus some
     273commonly used groups of widgets in the ``django.forms.widgets`` module,
     274including :ref:`the input of text <text-widgets>`, :ref:`various checkboxes
     275and selectors <selector-widgets>`, :ref:`uploading files <file-upload-widgets>`,
     276and :ref:`handling of multi-valued input <composite-widgets>`.
     277
     278.. _text-widgets:
     279
     280Widgets handling input of text
     281^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     282
     283These widgets make use of the HTML elements ``input`` and ``textarea``.
     284
    174285``TextInput``
    175286~~~~~~~~~~~~~
    176287
    commonly used groups of widgets: 
    204315
    205316    Hidden input: ``<input type='hidden' ...>``
    206317
    207 ``MultipleHiddenInput``
    208 ~~~~~~~~~~~~~~~~~~~~~~~
    209 
    210 .. class:: MultipleHiddenInput
    211 
    212     Multiple ``<input type='hidden' ...>`` widgets.
    213 
    214     A widget that handles multiple hidden widgets for fields that have a list
    215     of values.
    216 
    217     .. attribute:: MultipleHiddenInput.choices
    218 
    219         This attribute is optional when the field does not have a
    220         :attr:`~Field.choices` attribute. If it does, it will override anything
    221         you set here when the attribute is updated on the :class:`Field`.
    222 
    223 ``FileInput``
    224 ~~~~~~~~~~~~~
    225 
    226 .. class:: FileInput
    227 
    228     File upload input: ``<input type='file' ...>``
    229 
    230 ``ClearableFileInput``
    231 ~~~~~~~~~~~~~~~~~~~~~~
    232 
    233 .. class:: ClearableFileInput
    234 
    235     .. versionadded:: 1.3
    236 
    237     File upload input: ``<input type='file' ...>``, with an additional checkbox
    238     input to clear the field's value, if the field is not required and has
    239     initial data.
     318    Note that there also is a :class:`MultipleHiddenInput`
     319    widget that encapsulates a set of hidden input elements.
    240320
    241321``DateInput``
    242322~~~~~~~~~~~~~
    commonly used groups of widgets: 
    296376
    297377    Text area: ``<textarea>...</textarea>``
    298378
     379.. _selector-widgets:
     380
     381Selector and checkbox widgets
     382^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     383
    299384``CheckboxInput``
    300385~~~~~~~~~~~~~~~~~
    301386
    commonly used groups of widgets: 
    435520          ...
    436521        </ul>
    437522
     523.. _file-upload-widgets:
     524
     525File upload widgets
     526^^^^^^^^^^^^^^^^^^^
     527
     528``FileInput``
     529~~~~~~~~~~~~~
     530
     531.. class:: FileInput
     532
     533    File upload input: ``<input type='file' ...>``
     534
     535``ClearableFileInput``
     536~~~~~~~~~~~~~~~~~~~~~~
     537
     538.. class:: ClearableFileInput
     539
     540    .. versionadded:: 1.3
     541
     542    File upload input: ``<input type='file' ...>``, with an additional checkbox
     543    input to clear the field's value, if the field is not required and has
     544    initial data.
     545
     546.. _composite-widgets:
     547
     548Composite widgets
     549^^^^^^^^^^^^^^^^^
     550
     551``MultipleHiddenInput``
     552~~~~~~~~~~~~~~~~~~~~~~~
     553
     554.. class:: MultipleHiddenInput
     555
     556    Multiple ``<input type='hidden' ...>`` widgets.
     557
     558    A widget that handles multiple hidden widgets for fields that have a list
     559    of values.
     560
     561    .. attribute:: MultipleHiddenInput.choices
     562
     563        This attribute is optional when the field does not have a
     564        :attr:`~Field.choices` attribute. If it does, it will override anything
     565        you set here when the attribute is updated on the :class:`Field`.
     566
    438567``MultiWidget``
    439568~~~~~~~~~~~~~~~
    440569
  • docs/topics/forms/media.txt

    diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt
    index 615dd71..29a7829 100644
    a b in a form suitable for easy inclusion on your Web page. 
    3838    whichever toolkit suits your requirements. Django is able to integrate
    3939    with any JavaScript toolkit.
    4040
     41.. _media-as-a-static-definition:
     42
    4143Media as a static definition
    4244----------------------------
    4345
    A dictionary describing the CSS files required for various forms of output 
    7880media.
    7981
    8082The values in the dictionary should be a tuple/list of file names. See
    81 `the section on media paths`_ for details of how to specify paths to media
    82 files.
    83 
    84 .. _the section on media paths: `Paths in media definitions`_
     83:ref:`the section on media paths <form-media-paths>` for details of how to
     84specify paths to media files.
    8585
    8686The keys in the dictionary are the output media types. These are the same
    8787types accepted by CSS files in media declarations: 'all', 'aural', 'braille',
    If this last CSS definition were to be rendered, it would become the following H 
    117117``js``
    118118~~~~~~
    119119
    120 A tuple describing the required JavaScript files. See
    121 `the section on media paths`_ for details of how to specify paths to media
     120A tuple describing the required JavaScript files. See :ref:`the section on
     121media paths <form-media-paths>` for details of how to specify paths to media
    122122files.
    123123
    124124``extend``
    declaration to the media declaration:: 
    164164    <script type="text/javascript" src="http://static.example.com/whizbang.js"></script>
    165165
    166166If you require even more control over media inheritance, define your media
    167 using a `dynamic property`_. Dynamic properties give you complete control over
    168 which media files are inherited, and which are not.
     167using a :ref:`dynamic property <dynamic-property>`. Dynamic properties give
     168you complete control over which media files are inherited, and which are not.
    169169
    170 .. _dynamic property: `Media as a dynamic property`_
     170.. _dynamic-property:
    171171
    172172Media as a dynamic property
    173173---------------------------
    Paths in media definitions 
    198198.. versionchanged:: 1.3
    199199
    200200Paths used to specify media can be either relative or absolute. If a path
    201 starts with '/', 'http://' or 'https://', it will be interpreted as an absolute
    202 path, and left as-is. All other paths will be prepended with the value of
    203 the appropriate prefix.
     201starts with ``/``, ``http://`` or ``https://``, it will be interpreted as an
     202absolute path, and left as-is. All other paths will be prepended with the value
     203of the appropriate prefix.
    204204
    205205As part of the introduction of the
    206206:doc:`staticfiles app </ref/contrib/staticfiles>` two new settings were added
Back to Top