WidgetsLink to this heading#

Styling widget instancesLink to this heading#

If you want to make one widget instance look different from another, you will need to specify additional attributes at the time when the widget object is instantiated and assigned to a form field (and perhaps add some rules to your CSS files).

For example, take the following simple form:

from django import forms

class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField()

This form will include three default TextInput widgets, with default rendering – no CSS class, no extra attributes. This means that the input boxes provided for each widget will be rendered exactly the same:

>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" required /></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required /></td></tr>

On a real Web page, you probably don’t want every widget to look the same. You might want a larger input element for the comment, and you might want the “name” widget to have some special CSS class. It is also possible to specify the “type” attribute to take advantage of the new HTML5 input types. To do this, you use the Widget.attrs argument when creating the widget:

class CommentForm(forms.Form):
    name = forms.CharField(widget=forms.TextInput(attrs={'class': 'special'}))
    url = forms.URLField()
    comment = forms.CharField(widget=forms.TextInput(attrs={'size': '40'}))

Django will then include the extra attributes in the rendered output:

>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" class="special" required /></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" size="40" required /></td></tr>

You can also set the HTML id using attrs. See BoundField.id_for_label for an example.

Styling widget classesLink to this heading#

With widgets, it is possible to add assets (css and javascript) and more deeply customize their appearance and behavior.

In a nutshell, you will need to subclass the widget and either define a «Media» inner class or create a «media» property.

These methods involve somewhat advanced Python programming and are described in detail in the Form Assets topic guide.

WidgetLink to this heading#

class Widget(attrs=None)Link to this definition#

This abstract class cannot be rendered, but provides the basic attribute attrs. You may also implement or override the render() method on custom widgets.

attrsLink to this definition#

A dictionary containing HTML attributes to be set on the rendered widget.

Python console

>>> from django import forms
>>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name',})
>>> name.render('name', 'A name')
'<input title="Your name" type="text" name="name" value="A name" size="10" required />'

If you assign a value of True or False to an attribute, it will be rendered as an HTML5 boolean attribute:

Code

>>> name = forms.TextInput(attrs={'required': True})
>>> name.render('name', 'A name')
'<input name="name" type="text" value="A name" required />'
>>>
>>> name = forms.TextInput(attrs={'required': False})
>>> name.render('name', 'A name')
'<input name="name" type="text" value="A name" />'

supports_microsecondsLink to this definition#

An attribute that defaults to True. If set to False, the microseconds part of datetime and time values will be set to 0.

format_value(value)Link to this definition#

Cleans and returns a value for use in the widget template. value isn’t guaranteed to be valid input, therefore subclass implementations should program defensively.

id_for_label(self, id_)Link to this definition#

Returns the HTML ID attribute of this widget for use by a <label>, given the ID of the field. Returns None if an ID isn’t available.

This hook is necessary because some widgets have multiple HTML elements and, thus, multiple IDs. In that case, this method should return an ID value that corresponds to the first ID in the widget’s tags.

render(name, value, attrs=None)Link to this definition#

Returns HTML for the widget, as a Unicode string. This method must be implemented by the subclass, otherwise NotImplementedError will be raised.

The “value” given is not guaranteed to be valid input, therefore subclass implementations should program defensively.

value_from_datadict(data, files, name)Link to this definition#

Given a dictionary of data and this widget’s name, returns the value of this widget. files may contain data coming from request.FILES. Returns None if a value wasn’t provided. Note also that value_from_datadict may be called more than once during handling of form data, so if you customize it and add expensive processing, you should implement some caching mechanism yourself.

value_omitted_from_data(data, files, name)Link to this definition#

Given data and files dictionaries and this widget’s name, returns whether or not there’s data or files for the widget.

The method’s result affects whether or not a field in a model form falls back to its default.

Special cases are CheckboxInput, CheckboxSelectMultiple, and SelectMultiple, which always return False because an unchecked checkbox and unselected <select multiple> don’t appear in the data of an HTML form submission, so it’s unknown whether or not the user submitted a value.

use_required_attribute(initial)Link to this definition#

Given a form field’s initial value, returns whether or not the widget can be rendered with the required HTML attribute. Forms use this method along with Field.required and Form.use_required_attribute to determine whether or not to display the required attribute for each field.

By default, returns False for hidden widgets and True otherwise. Special cases are ClearableFileInput, which returns False when initial is not set, and CheckboxSelectMultiple, which always returns False because browser validation would require all checkboxes to be checked instead of at least one.

Override this method in custom widgets that aren’t compatible with browser validation. For example, a WSYSIWG text editor widget backed by a hidden textarea element may want to always return False to avoid browser validation on the hidden field.

MultiWidgetLink to this heading#

class MultiWidget(widgets, attrs=None)Link to this definition#

A widget that is composed of multiple widgets. MultiWidget works hand in hand with the MultiValueField.

MultiWidget has one required argument:

widgetsLink to this definition#

An iterable containing the widgets needed.

And one required method:

decompress(value)Link to this definition#

This method takes a single «compressed» value from the field and returns a list of «decompressed» values. The input value can be assumed valid, but not necessarily non-empty.

This method must be implemented by the subclass, and since the value may be empty, the implementation must be defensive.

The rationale behind «decompression» is that it is necessary to «split» the combined value of the form field into the values for each widget.

An example of this is how SplitDateTimeWidget turns a datetime value into a list with date and time split into two separate values:

Code

from django.forms import MultiWidget

class SplitDateTimeWidget(MultiWidget):

    # ...

    def decompress(self, value):
        if value:
            return [value.date(), value.time().replace(microsecond=0)]
        return [None, None]

Other methods that may be useful to override include:

render(name, value, attrs=None)Link to this definition#

Argument value is handled differently in this method from the subclasses of 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.

If value is a list, the output of render() will be a concatenation of rendered child widgets. If value is not a list, it will first be processed by the method decompress() to create the list and then rendered.

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.

Unlike in the single value widgets, method render() need not be implemented in the subclasses.

format_output(rendered_widgets)Link to this definition#

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.

Here’s an example widget which subclasses MultiWidget to display a date with the day, month, and year in different select boxes. This widget is intended to be used with a DateField rather than a MultiValueField, thus we have implemented value_from_datadict():

Code

from datetime import date
from django.forms import widgets

class DateSelectorWidget(widgets.MultiWidget):
    def __init__(self, attrs=None):
        # create choices for days, months, years
        # example below, the rest snipped for brevity.
        years = [(year, year) for year in (2011, 2012, 2013)]
        _widgets = (
            widgets.Select(attrs=attrs, choices=days),
            widgets.Select(attrs=attrs, choices=months),
            widgets.Select(attrs=attrs, choices=years),
        )
        super(DateSelectorWidget, self).__init__(_widgets, attrs)

    def decompress(self, value):
        if value:
            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)
            for i, widget in enumerate(self.widgets)]
        try:
            D = date(
                day=int(datelist[0]),
                month=int(datelist[1]),
                year=int(datelist[2]),
            )
        except ValueError:
            return ''
        else:
            return str(D)

The constructor creates several Select widgets in a tuple. The super class uses this tuple to setup the widget.

The 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 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 None.

The default implementation of value_from_datadict() returns a list of values corresponding to each Widget. This is appropriate when using a MultiWidget with a MultiValueField, but since we want to use this widget with a DateField which takes a single value, we have overridden this method to combine the data of all the subwidgets into a datetime.date. The method extracts data from the POST dictionary and constructs and validates the date. If it is valid, we return the string, otherwise, we return an empty string which will cause form.is_valid to return False.

Widgets handling input of textLink to this heading#

These widgets make use of the HTML elements input and textarea.

Selector and checkbox widgetsLink to this heading#

File upload widgetsLink to this heading#

Composite widgetsLink to this heading#