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 theWidget#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:
RadioSelect()
to allow access to individual radio inputs.CheckboxSelectMultiple()
to allow access to individual checkbox inputs.
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.
- kwargsAttrs (Object) – any extra HTML attributes passed to the Widget’s
-
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 aDate
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">
widgetNew in version 0.5.
-
class
EmailInput
([kwargs])¶ An
<input type="email">
widgetNew in version 0.5.
-
class
URLInput
([kwargs])¶ An
<input type="url">
widgetNew 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 tofalse
.
-
class
HiddenInput
([kwargs])¶ An
<input type="hidden">
widget.
-
class
Textarea
([kwargs])¶ A
<textarea>
widget.Default
rows
andcols
HTML attributes will be used if not provided inkwargs.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: - kwargs (Object) – widget options
- kwargs.format (String) – a time.strftime() format string for a date.
-
class
DateTimeInput
([kwargs])¶ An
<input type="text">
which, if given a Date object to display, formats it as an appropriate datetime string.Arguments: - kwargs (Object) – widget options
- kwargs.format (String) – a time.strftime() format string for a datetime.
-
class
TimeInput
([kwargs])¶ An
<input type="text">
which, if given a Date object to display, formats it as an appropriate time string.Arguments: - kwargs (Object) – widget options
- kwargs.format (String) – a time.strftime() format string for a time.
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 withNullBooleanField()
.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()
.
- kwargs (Object) – widget options, as per
-
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: - kwargs (Object) – widget options
- kwargs.renderer (Function) – a custom
CheckboxFieldRenderer()
constructor.
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: - kwargs (Object) – widget options additional to those specified in
MultiWidget()
. - kwargs.dateFormat (String) – a time.strftime() format string for a date.
- kwargs.timeFormat (String) – a time.strftime() format string for a time.
- kwargs (Object) – widget options additional to those specified in
-
class
SplitHiddenDateTimeWidget
([kwargs])¶ Splits Date input into two
<input type="hidden">
elements.