Styling widget instances¶

If you want to make one widget instance look different from another, you willneed to specify additional attributes at the time when the widget object isinstantiated and assigned to a form field (and perhaps add some rules to yourCSS files).

For example, take the following simple form:

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

This form will include three defaultTextInput widgets, with defaultrendering – no CSS class, no extra attributes. This means that the input boxesprovided 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. Youmight 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 specifythe ‘type’ attribute to take advantage of the new HTML5 input types. To dothis, you use theWidget.attrs argument when creating the widget:

classCommentForm(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 HTMLid usingattrs. SeeBoundField.id_for_label for an example.

Styling widget classes¶

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

In a nutshell, you will need to subclass the widget and eitherdefine a “Media” inner class orcreate a “media” property.

These methods involve somewhat advanced Python programming and are described indetail in theForm Assets topic guide.

Widget¶

classWidget(attrs=None)[source]¶

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

attrs¶

A dictionary containing HTML attributes to be set on the renderedwidget.

>>>fromdjangoimportforms>>>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 ofTrue orFalse to an attribute,it will be rendered as an HTML5 boolean attribute:

>>>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_microseconds¶

An attribute that defaults toTrue. If set toFalse, themicroseconds part ofdatetime andtime values will be set to0.

New in Django 1.9:

In older versions, this attribute was only defined on the dateand time widgets (asFalse).

format_value(value)¶

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

Changed in Django 1.10:

In older versions, this method is a private API named_format_value(). The old name will work until Django 2.0.

id_for_label(self,id_)[source]¶

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

This hook is necessary because some widgets have multiple HTMLelements and, thus, multiple IDs. In that case, this method shouldreturn an ID value that corresponds to the first ID in the widget’stags.

render(name,value,attrs=None)[source]¶

Returns HTML for the widget, as a Unicode string. This method must beimplemented by the subclass, otherwiseNotImplementedError will beraised.

The ‘value’ given is not guaranteed to be valid input, thereforesubclass implementations should program defensively.

value_from_datadict(data,files,name)[source]¶

Given a dictionary of data and this widget’s name, returns the valueof this widget.files may contain data coming fromrequest.FILES. ReturnsNoneif a value wasn’t provided. Note also thatvalue_from_datadict maybe called more than once during handling of form data, so if youcustomize it and add expensive processing, you should implement somecaching mechanism yourself.

value_omitted_from_data(data,files,name)[source]¶

New in Django 1.10.2.

Givendata andfiles 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 formfalls back to its default.

Special cases areCheckboxInput,CheckboxSelectMultiple, andSelectMultiple, which always returnFalse because an unchecked checkbox and unselected<selectmultiple> don’t appear in the data of an HTML formsubmission, so it’s unknown whether or not the user submitted a value.

use_required_attribute(initial)[source]¶

New in Django 1.10.1.

Given a form field’sinitial value, returns whether or not thewidget can be rendered with therequired HTML attribute. Forms usethis method along withField.required andForm.use_required_attribute to determine whether or notto display therequired attribute for each field.

By default, returnsFalse for hidden widgets andTrueotherwise. Special cases areClearableFileInput,which returnsFalse wheninitial is not set, andCheckboxSelectMultiple, which always returnsFalse because browser validation would require all checkboxes to bechecked instead of at least one.

Override this method in custom widgets that aren’t compatible withbrowser validation. For example, a WSYSIWG text editor widget backed bya hiddentextarea element may want to always returnFalse toavoid browser validation on the hidden field.

MultiWidget¶

classMultiWidget(widgets,attrs=None)[source]¶

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

MultiWidget has one required argument:

widgets¶

An iterable containing the widgets needed.

And one required method:

decompress(value)[source]¶

This method takes a single “compressed” value from the field andreturns a list of “decompressed” values. The input value can beassumed valid, but not necessarily non-empty.

This methodmust be implemented by the subclass, and since thevalue 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 howSplitDateTimeWidget turns adatetime value into a list with date and time splitinto two separate values:

fromdjango.formsimportMultiWidgetclassSplitDateTimeWidget(MultiWidget):# ...defdecompress(self,value):ifvalue:return[value.date(),value.time().replace(microsecond=0)]return[None,None]

Tip

Note thatMultiValueField has acomplementary methodcompress()with the opposite responsibility - to combine cleaned values ofall member fields into one.

Other methods that may be useful to override include:

render(name,value,attrs=None)[source]¶

Argumentvalue is handled differently in this method from thesubclasses ofWidget because it has to figure out how tosplit a single value for display in multiple widgets.

Thevalue argument used when rendering can be one of two things:

• Alist.
• A single value (e.g., a string) that is the “compressed” representationof alist of values.

Ifvalue is a list, the output ofrender() willbe a concatenation of rendered child widgets. Ifvalue is not alist, it will first be processed by the methoddecompress() to create the list and then rendered.

Whenrender() executes its HTML rendering, each value in the listis rendered with the corresponding widget – the first value isrendered in the first widget, the second value is rendered in thesecond widget, etc.

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

format_output(rendered_widgets)[source]¶

Given a list of rendered widgets (as strings), returns a Unicode stringrepresenting the HTML for the whole lot.

This hook allows you to format the HTML design of the widgets any wayyou’d like.

Here’s an example widget which subclassesMultiWidget to displaya date with the day, month, and year in different select boxes. This widgetis intended to be used with aDateField rather thanaMultiValueField, thus we have implementedvalue_from_datadict():

fromdatetimeimportdatefromdjango.formsimportwidgetsclassDateSelectorWidget(widgets.MultiWidget):def__init__(self,attrs=None):# create choices for days, months, years# example below, the rest snipped for brevity.years=[(year,year)foryearin(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)defdecompress(self,value):ifvalue:return[value.day,value.month,value.year]return[None,None,None]defformat_output(self,rendered_widgets):return''.join(rendered_widgets)defvalue_from_datadict(self,data,files,name):datelist=[widget.value_from_datadict(data,files,name+'_%s'%i)fori,widgetinenumerate(self.widgets)]try:D=date(day=int(datelist[0]),month=int(datelist[1]),year=int(datelist[2]),)exceptValueError:return''else:returnstr(D)

The constructor creates severalSelect widgets in a tuple. Thesuper class uses this tuple to setup the widget.

Theformat_output() method is fairly vanilla here (infact, it’s the same as what’s been implemented as the default forMultiWidget), but the idea is that you could add custom HTML betweenthe widgets should you wish.

The required methoddecompress() breaks up adatetime.date value into the day, month, and year values correspondingto each widget. Note how the method handles the case wherevalue isNone.

The default implementation ofvalue_from_datadict() returnsa list of values corresponding to eachWidget. This is appropriatewhen using aMultiWidget with aMultiValueField,but since we want to use this widget with aDateFieldwhich takes a single value, we have overridden this method to combine thedata of all the subwidgets into adatetime.date. The method extractsdata from thePOST dictionary and constructs and validates the date.If it is valid, we return the string, otherwise, we return an empty stringwhich will causeform.is_valid to returnFalse.

Widgets handling input of text¶

These widgets make use of the HTML elementsinput andtextarea.

Selector and checkbox widgets¶

File upload widgets¶

Composite widgets¶