Widgets API

Widget

class Widget([kwargs])

An HTML form widget.

A widget handles the rendering of HTML, and the extraction of data from an object that corresponds to the widget.

This base widget cannot be rendered, but provides the basic attribute widget.attrs. You must implement the Widget#render`() method when extending this base widget.

Arguments:
  • kwargs (Object) – widget options, which are as follows:
  • kwargs.attrs (Object) – HTML attributes for the rendered widget.

Instance Properties

widget.attrs

Base HTML attributes for the rendered widget.

Type:Object

Prototype Properties

Widget#isHidden

Determines whether this corresponds to an <input type="hidden">.

Type:Boolean
Widget#needsMultipartForm

Determines whether this widget needs a multipart-encoded form.

Type:Boolean
Widget#needsInitialValue

Determines whether this widget’s render logic always needs to use the initial value.

Type:Boolean
Widget#isRequired

Determines whether this widget is for a required field.

Type:Boolean

Prototype Functions

Widget#subWidgets(name, value[, kwargs])

Yields all “subwidgets” of this widget. Used by:

Arguments are the same as for Widget#render().

Widget#render(name, value[, kwargs])

Returns a rendered representation of this Widget as a ReactElement object.

The default implementation throws an Error – extending widgets must provide an implementation.

The value given is not guaranteed to be valid input, so inheriting implementations should program defensively.

Arguments:
  • name (String) – the name to give to the rendered widget, or to be used as the basis for other, unique names when the widget needs to render multiple inputs.
  • value – the value to be disaplyed in the widget.
  • kwargs (Object) – rendering options, which are:
  • kwargs.attrs (Object) – additonal HTML attributes for the rendered widget.
  • kwargs.controlled (Boolean) – true if the Widget should render a controlled component.
  • kwargs.initialValue – if the widget has Widget#needsInitialValue configured to true, its initial value will always be passed
Widget#buildAttrs(kwargAttrs, renderAttrs)

Helper function for building an HTML attributes object using widget.attrs and the given arguments.

Arguments:
  • kwargsAttrs (Object) – any extra HTML attributes passed to the Widget’s render() method.
  • renderAttrs (Object) – any other attributes which should be included in a Widget’s HTML attributes by default – provided by the render() method for attributes related to the type of widget being implemented.
Widget#valueFromData(data, files, name)

Retrieves a value for this widget from the given form data.

Returns:a value for this widget, or null if no value was provided.
Widget#idForLabel(id)

Determines the HTML id attribute of this Widget for use by a <label>, given the id of the field.

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.

class SubWidget(parentWidget, name, value[, kwargs])

Some widgets are made of multiple HTML elements – namely, RadioSelect(). This represents the “inner” HTML element of a widget.

Prototype Functions

SubWidget#render()

Calls the parent widget’s render function with this Subwidget’s details.

MultiWidget

class MultiWidget(widgets[, kwargs])

A widget that is composed of multiple widgets.

You’ll probably want to use this class with MultiValueField().

Arguments:
  • widgets (Array) – the list of widgets composing this widget.
  • kwargs (Object) – widget options.

Prototype Functions

MultiWidget#render(name, value[, kwargs])
Arguments:
  • name (String) – the name be used as the basis for unique names for the multiple inputs this widget must render.
  • value – the value to be disaplyed in the widget – may be a list of values or a single value which needs to be split for display.
  • kwargs (Object) – rendering options, which are:
  • kwargs.attrs (Object) – additonal HTML attributes.
MultiWidget#formatOutput(renderedWidgets)

Creates an element containing a given list of rendered widgets.

This hook allows you to format the HTML design of the widgets, if needed – by default, they are wrapped in a <div>.

Arguments:
  • renderedWidgets (Array) – a list of rendered widgets.
MultiWidget#decompress(value)

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 when extending MultiWidget, 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 Date value into a list with date and time split into two separate values.

Text input widgets

class Input([kwargs])

An <input> widget.

class TextInput([kwargs])

An <input type="text"> widget

class NumberInput([kwargs])

An <input type="number"> widget

New in version 0.5.

class EmailInput([kwargs])

An <input type="email"> widget

New in version 0.5.

class URLInput([kwargs])

An <input type="url"> widget

New in version 0.5.

class PasswordInput([kwargs])

An <input type="password"> widget.

Arguments:
  • kwargs (Object) – widget options
  • kwargs.renderValue (Boolean) – if false a value will not be rendered for this field – defaults to false.
class HiddenInput([kwargs])

An <input type="hidden"> widget.

class Textarea([kwargs])

A <textarea> widget.

Default rows and cols HTML attributes will be used if not provided in kwargs.attrs.

Date-formatting text input widgets

class DateInput([kwargs])

An <input type="text"> which, if given a Date object to display, formats it as an appropriate date string.

Arguments:
class DateTimeInput([kwargs])

An <input type="text"> which, if given a Date object to display, formats it as an appropriate datetime string.

Arguments:
class TimeInput([kwargs])

An <input type="text"> which, if given a Date object to display, formats it as an appropriate time string.

Arguments:

Selector and checkbox widgets

class CheckboxInput([kwargs])

An <input type="checkbox"> widget.

Arguments:
  • kwargs (Object) – widget options
  • kwargs.checkTest (Function) – a function which takes a value and returns true if the checkbox should be checked for that value.
class Select([kwargs])

An HTML <select> widget.

Arguments:
  • kwargs (Object) – widget options
  • kwargs.choices (Array) – choices to be used when rendering the widget, with each choice specified as pair in [value, text] format – defaults to [].
class NullBooleanSelect([kwargs])

A <select> widget intended to be used with NullBooleanField().

Any kwargs.choices provided will be overrridden with the specific choices this widget requires.

class SelectMultiple([kwargs])

An HTML <select> widget which allows multiple selections.

Arguments:
  • kwargs (Object) – widget options, as per Select().
class RadioSelect([kwargs])

Renders a single select as a list of <input type="radio"> elements.

Arguments:
  • kwargs (Object) – widget options
  • kwargs.renderer (Function) – a custom RadioFieldRenderer() constructor.

Prototype Functions

RadioSelect#getRenderer(name, value[, kwargs])
Returns:an instance of the renderer to be used to render this widget.
RadioSelect#subWidgets(name, value[, kwargs])
Returns:a list of RadioChoiceInput() objects created by this widget’s renderer.
class RadioFieldRenderer(name, value, attrs, choices)

An object used by RadioSelect() to enable customisation of radio widgets.

Arguments:
  • name (String) – the field name.
  • value (String) – the selected value.
  • attrs (Object) – HTML attributes for the widget.
  • choices (Array) – choices to be used when rendering the widget, with each choice specified as an Array in [value, text] format.
RadioFieldRenderer#choiceInputs()

gets all RadioChoiceInput inputs created by this renderer.

RadioFieldRenderer#choiceInput(i)

gets the i-th RadioChoiceInput created by this renderer.

class RadioChoiceInput(name, value, attrs, choice, index)

An object used by RadioFieldRenderer() that represents a single <input type="radio">.

Arguments:
  • name (String) – the field name.
  • value (String) – the selected value.
  • attrs (Object) – HTML attributes for the widget.
  • choice (Array) – choice details to be used when rendering the widget, specified as an Array in [value, text] format.
  • index (Number) – the index of the radio button this widget represents.
class CheckboxSelectMultiple([kwargs])

Multiple selections represented as a list of <input type="checkbox"> widgets.

Arguments:

Prototype Functions

CheckboxSelectMultiple#getRenderer(name, value[, kwargs])
Returns:an instance of the renderer to be used to render this widget.
CheckboxSelectMultiple#subWidgets(name, value[, kwargs])
Returns:a list of CheckboxChoiceInput() objects created by this widget’s renderer.
class CheckboxFieldRenderer(name, value, attrs, choices)

An object used by CheckboxSelectMultiple() to enable customisation of checkbox widgets.

Arguments:
  • name (String) – the field name.
  • value (Array) – a list of selected values.
  • attrs (Object) – HTML attributes for the widget.
  • choices (Array) – choices to be used when rendering the widget, with each choice specified as an Array in [value, text] format.
CheckboxFieldRenderer#choiceInputs()

gets all CheckboxChoiceInput inputs created by this renderer.

CheckboxFieldRenderer#choiceInput(i)

gets the i-th CheckboxChoiceInput created by this renderer.

class CheckboxChoiceInput(name, value, attrs, choice, index)

An object used by CheckboxFieldRenderer() that represents a single <input type="checkbox">.

Arguments:
  • name (String) – the field name.
  • value (Array) – a list of selected values.
  • attrs (Object) – HTML attributes for the widget.
  • choice (Array) – choice details to be used when rendering the widget, specified as an Array in [value, text] format.
  • index (Number) – the index of the chckbox this widget represents.

File upload widgets

class FileInput([kwargs])

An <input type="file"> widget.

class ClearableFileInput([kwargs])

A file widget which also has a checkbox to indicate that the field should be cleared.

Composite widgets

class MultipleHiddenInput([kwargs])

A widget that handles <input type="hidden"> for fields that have a list of values.

class SplitDateTimeWidget([kwargs])

Splits Date input into two <input type="text"> elements.

Arguments:
class SplitHiddenDateTimeWidget([kwargs])

Splits Date input into two <input type="hidden"> elements.