diff options
Diffstat (limited to 'docs/ref/forms/widgets.txt')
| -rw-r--r-- | docs/ref/forms/widgets.txt | 156 |
1 files changed, 96 insertions, 60 deletions
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index c6148a5460..f0301c1eee 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -241,6 +241,28 @@ foundation for custom widgets. In older versions, this method is a private API named ``_format_value()``. The old name will work until Django 2.0. + .. method:: get_context(name, value, attrs=None) + + .. versionadded:: 1.11 + + Returns a dictionary of values to use when rendering the widget + template. By default, the dictionary contains a single key, + ``'widget'``, which is a dictionary representation of the widget + containing the following keys: + + * ``'name'``: The name of the field from the ``name`` argument. + * ``'is_hidden'``: A boolean indicating whether or not this widget is + hidden. + * ``'required'``: A boolean indicating whether or not the field for + this widget is required. + * ``'value'``: The value as returned by :meth:`format_value`. + * ``'attrs'``: HTML attributes to be set on the rendered widget. The + combination of the :attr:`attrs` attribute and the ``attrs`` argument. + * ``'template_name'``: The value of ``self.template_name``. + + ``Widget`` subclasses can provide custom context values by overriding + this method. + .. method:: id_for_label(self, id_) Returns the HTML ID attribute of this widget for use by a ``<label>``, @@ -251,14 +273,16 @@ foundation for custom widgets. return an ID value that corresponds to the first ID in the widget's tags. - .. method:: render(name, value, attrs=None) + .. method:: render(name, value, attrs=None, renderer=None) - Returns HTML for the widget, as a Unicode string. This method must be - implemented by the subclass, otherwise ``NotImplementedError`` will be - raised. + Renders a widget to HTML using the given renderer. If ``renderer`` is + ``None``, the renderer from the :setting:`FORM_RENDERER` setting is + used. - The 'value' given is not guaranteed to be valid input, therefore - subclass implementations should program defensively. + .. versionchanged:: 1.11 + + The ``renderer`` argument was added. Support for subclasses that + don't accept it will be removed in Django 2.1. .. method:: value_from_datadict(data, files, name) @@ -360,40 +384,21 @@ foundation for custom widgets. with the opposite responsibility - to combine cleaned values of all member fields into one. - Other methods that may be useful to override include: - - .. method:: render(name, value, attrs=None) - - Argument ``value`` is handled differently in this method from the - subclasses of :class:`~Widget` because it has to figure out how to - split a single value for display in multiple widgets. - - The ``value`` argument used when rendering can be one of two things: - - * A ``list``. - * A single value (e.g., a string) that is the "compressed" representation - of a ``list`` of values. + It provides some custom context: - If ``value`` is a list, the output of :meth:`~MultiWidget.render` will - be a concatenation of rendered child widgets. If ``value`` is not a - list, it will first be processed by the method - :meth:`~MultiWidget.decompress()` to create the list and then rendered. + .. method:: get_context(name, value, attrs=None) - When ``render()`` executes its HTML rendering, each value in the list - is rendered with the corresponding widget -- the first value is - rendered in the first widget, the second value is rendered in the - second widget, etc. + In addition to the ``'widget'`` key described in + :meth:`Widget.get_context`, ``MultiValueWidget`` adds a + ``widget['subwidgets']`` key. - Unlike in the single value widgets, method :meth:`~MultiWidget.render` - need not be implemented in the subclasses. + These can be looped over in the widget template: - .. method:: format_output(rendered_widgets) + .. code-block:: html+django - Given a list of rendered widgets (as strings), returns a Unicode string - representing the HTML for the whole lot. - - This hook allows you to format the HTML design of the widgets any way - you'd like. + {% for subwidget in widget.subwidgets %} + {% include widget.template_name with widget=subwidget %} + {% endfor %} Here's an example widget which subclasses :class:`MultiWidget` to display a date with the day, month, and year in different select boxes. This widget @@ -421,9 +426,6 @@ foundation for custom widgets. return [value.day, value.month, value.year] return [None, None, None] - def format_output(self, rendered_widgets): - return ''.join(rendered_widgets) - def value_from_datadict(self, data, files, name): datelist = [ widget.value_from_datadict(data, files, name + '_%s' % i) @@ -442,11 +444,6 @@ foundation for custom widgets. The constructor creates several :class:`Select` widgets in a tuple. The ``super`` class uses this tuple to setup the widget. - The :meth:`~MultiWidget.format_output` method is fairly vanilla here (in - fact, it's the same as what's been implemented as the default for - ``MultiWidget``), but the idea is that you could add custom HTML between - the widgets should you wish. - The required method :meth:`~MultiWidget.decompress` breaks up a ``datetime.date`` value into the day, month, and year values corresponding to each widget. Note how the method handles the case where ``value`` is @@ -485,14 +482,18 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. class:: TextInput - Text input: ``<input type="text" ...>`` + * ``input_type``: ``'text'`` + * ``template_name``: ``'django/forms/widgets/text.html'`` + * Renders as: ``<input type="text" ...>`` ``NumberInput`` ~~~~~~~~~~~~~~~ .. class:: NumberInput - Text input: ``<input type="number" ...>`` + * ``input_type``: ``'number'`` + * ``template_name``: ``'django/forms/widgets/number.html'`` + * Renders as: ``<input type="number" ...>`` Beware that not all browsers support entering localized numbers in ``number`` input types. Django itself avoids using them for fields having @@ -503,21 +504,27 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. class:: EmailInput - Text input: ``<input type="email" ...>`` + * ``input_type``: ``'email'`` + * ``template_name``: ``'django/forms/widgets/email.html'`` + * Renders as: ``<input type="email" ...>`` ``URLInput`` ~~~~~~~~~~~~ .. class:: URLInput - Text input: ``<input type="url" ...>`` + * ``input_type``: ``'url'`` + * ``template_name``: ``'django/forms/widgets/url.html'`` + * Renders as: ``<input type="url" ...>`` ``PasswordInput`` ~~~~~~~~~~~~~~~~~ .. class:: PasswordInput - Password input: ``<input type='password' ...>`` + * ``input_type``: ``'password'`` + * ``template_name``: ``'django/forms/widgets/password.html'`` + * Renders as: ``<input type='password' ...>`` Takes one optional argument: @@ -531,7 +538,9 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. class:: HiddenInput - Hidden input: ``<input type='hidden' ...>`` + * ``input_type``: ``'hidden'`` + * ``template_name``: ``'django/forms/widgets/hidden.html'`` + * Renders as: ``<input type='hidden' ...>`` Note that there also is a :class:`MultipleHiddenInput` widget that encapsulates a set of hidden input elements. @@ -541,7 +550,9 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. class:: DateInput - Date input as a simple text box: ``<input type='text' ...>`` + * ``input_type``: ``'text'`` + * ``template_name``: ``'django/forms/widgets/date.html'`` + * Renders as: ``<input type='text' ...>`` Takes same arguments as :class:`TextInput`, with one more optional argument: @@ -558,7 +569,9 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. class:: DateTimeInput - Date/time input as a simple text box: ``<input type='text' ...>`` + * ``input_type``: ``'text'`` + * ``template_name``: ``'django/forms/widgets/datetime.html'`` + * Renders as: ``<input type='text' ...>`` Takes same arguments as :class:`TextInput`, with one more optional argument: @@ -579,7 +592,9 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. class:: TimeInput - Time input as a simple text box: ``<input type='text' ...>`` + * ``input_type``: ``'text'`` + * ``template_name``: ``'django/forms/widgets/time.html'`` + * Renders as: ``<input type='text' ...>`` Takes same arguments as :class:`TextInput`, with one more optional argument: @@ -598,7 +613,8 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. class:: Textarea - Text area: ``<textarea>...</textarea>`` + * ``template_name``: ``'django/forms/widgets/textarea.html'`` + * Renders as: ``<textarea>...</textarea>`` .. _selector-widgets: @@ -610,7 +626,9 @@ Selector and checkbox widgets .. class:: CheckboxInput - Checkbox: ``<input type='checkbox' ...>`` + * ``input_type``: ``'checkbox'`` + * ``template_name``: ``'django/forms/widgets/checkbox.html'`` + * Renders as: ``<input type='checkbox' ...>`` Takes one optional argument: @@ -624,7 +642,8 @@ Selector and checkbox widgets .. class:: Select - Select widget: ``<select><option ...>...</select>`` + * ``template_name``: ``'django/forms/widgets/select.html'`` + * Renders as: ``<select><option ...>...</select>`` .. attribute:: Select.choices @@ -637,6 +656,8 @@ Selector and checkbox widgets .. class:: NullBooleanSelect + * ``template_name``: ``'django/forms/widgets/select.html'`` + Select widget with options 'Unknown', 'Yes' and 'No' ``SelectMultiple`` @@ -644,6 +665,8 @@ Selector and checkbox widgets .. class:: SelectMultiple + * ``template_name``: ``'django/forms/widgets/select.html'`` + Similar to :class:`Select`, but allows multiple selection: ``<select multiple='multiple'>...</select>`` @@ -652,6 +675,8 @@ Selector and checkbox widgets .. class:: RadioSelect + * ``template_name``: ``'django/forms/widgets/radio.html'`` + Similar to :class:`Select`, but rendered as a list of radio buttons within ``<li>`` tags: @@ -744,6 +769,8 @@ Selector and checkbox widgets .. class:: CheckboxSelectMultiple + * ``template_name``: ``'django/forms/widgets/checkbox_select.html'`` + Similar to :class:`SelectMultiple`, but rendered as a list of check buttons: @@ -776,16 +803,18 @@ File upload widgets .. class:: FileInput - File upload input: ``<input type='file' ...>`` + * ``template_name``: ``'django/forms/widgets/file.html'`` + * Renders as: ``<input type='file' ...>`` ``ClearableFileInput`` ~~~~~~~~~~~~~~~~~~~~~~ .. class:: ClearableFileInput - File upload input: ``<input type='file' ...>``, with an additional checkbox - input to clear the field's value, if the field is not required and has - initial data. + * ``template_name``: ``'django/forms/widgets/clearable_file_input.html'`` + * Renders as: ``<input type='file' ...>`` with an additional checkbox + input to clear the field's value, if the field is not required and has + initial data. .. _composite-widgets: @@ -797,7 +826,8 @@ Composite widgets .. class:: MultipleHiddenInput - Multiple ``<input type='hidden' ...>`` widgets. + * ``template_name``: ``'django/forms/widgets/multiple_hidden.html'`` + * Renders as: multiple ``<input type='hidden' ...>`` tags A widget that handles multiple hidden widgets for fields that have a list of values. @@ -813,6 +843,8 @@ Composite widgets .. class:: SplitDateTimeWidget + * ``template_name``: ``'django/forms/widgets/splitdatetime.html'`` + Wrapper (using :class:`MultiWidget`) around two widgets: :class:`DateInput` for the date, and :class:`TimeInput` for the time. Must be used with :class:`SplitDateTimeField` rather than :class:`DateTimeField`. @@ -832,6 +864,8 @@ Composite widgets .. class:: SplitHiddenDateTimeWidget + * ``template_name``: ``'django/forms/widgets/splithiddendatetime.html'`` + Similar to :class:`SplitDateTimeWidget`, but uses :class:`HiddenInput` for both date and time. @@ -840,6 +874,8 @@ Composite widgets .. class:: SelectDateWidget + * ``template_name``: ``'django/forms/widgets/select_date.html'`` + Wrapper around three :class:`~django.forms.Select` widgets: one each for month, day, and year. |