diff options
Diffstat (limited to 'docs/ref/forms/api.txt')
| -rw-r--r-- | docs/ref/forms/api.txt | 38 |
1 files changed, 27 insertions, 11 deletions
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 9dcfbcfb09..d80d9ea224 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -1210,6 +1210,29 @@ Methods of ``BoundField`` .. method:: BoundField.label_tag(contents=None, attrs=None, label_suffix=None) + Renders a label tag for the form field using the template specified by + :attr:`.Form.template_name_label`. + + The available context is: + + * ``field``: This instance of the :class:`BoundField`. + * ``contents``: By default a concatenated string of + :attr:`BoundField.label` and :attr:`Form.label_suffix` (or + :attr:`Field.label_suffix`, if set). This can be overridden by the + ``contents`` and ``label_suffix`` arguments. + * ``attrs``: A ``dict`` containing ``for``, + :attr:`Form.required_css_class`, and ``id``. ``id`` is generated by the + field's widget ``attrs`` or :attr:`BoundField.auto_id`. Additional + attributes can be provided by the ``attrs`` argument. + * ``use_tag``: A boolean which is ``True`` if the label has an ``id``. + If ``False`` the default template omits the ``<label>`` tag. + + .. tip:: + + In your template ``field`` is the instance of the ``BoundField``. + Therefore ``field.field`` accesses :attr:`BoundField.field` being + the field you declare, e.g. ``forms.CharField``. + To separately render the label tag of a form field, you can call its ``label_tag()`` method:: @@ -1217,17 +1240,10 @@ Methods of ``BoundField`` >>> print(f['message'].label_tag()) <label for="id_message">Message:</label> - You can provide the ``contents`` parameter which will replace the - auto-generated label tag. An ``attrs`` dictionary may contain additional - attributes for the ``<label>`` tag. - - The HTML that's generated includes the form's - :attr:`~django.forms.Form.label_suffix` (a colon, by default) or, if set, - the current field's :attr:`~django.forms.Field.label_suffix`. The optional - ``label_suffix`` parameter allows you to override any previously set - suffix. For example, you can use an empty string to hide the label on - selected fields. The label is rendered using the template specified by the - forms :attr:`.Form.template_name_label`. + If you'd like to customize the rendering this can be achieved by overriding + the :attr:`.Form.template_name_label` attribute or more generally by + overriding the default template, see also + :ref:`overriding-built-in-form-templates`. .. versionchanged:: 4.0 |