BoundField API

BoundField

class BoundField(form, field, name)

A helper for rendering a field.

This is the primary means of generating components such as labels and input fields in the default form rendering methods.

Its attributes and methods will be of particular use when implementing custom form layout and rndering.

Arguments:
  • form (Form) – the form instance the field is a part of.
  • field (Field) – the field to be rendered.
  • name (String) – the name name associated with the field in the form.

Instance Attributes

boundField.form
boundField.field
boundField.name
boundField.htmlName

A version of the field’s name including any prefix the form has been configured with.

Assuming your forms are configured with prefixes when needed, this should be a unique identifier for any particular field (e.g. if you need something to pass as a key prop to a React component).

Type:String
boundField.label

The label the field is configured with, or a label automatically generated from the field’s name.

Type:String
boundField.helpText

Help text the field is configured with, otherwise an empty string.

Type:String

Prototype Functions

Status: methods for determining the field’s status.

BoundField#status()

Returns a string representing the field’s curent status.

Statuses are determined by checking the following conditions in order:

  • 'pending' – the field has a pending async validation.
  • 'error' – the field has a validation error.
  • 'valid' – the field has a value in form.cleanedData.
  • 'default' – the field meets none of the above criteria, i.e. it hasn’t been interacted with yet, or the whole form hasn’t been validated yet.
BoundField#isCleaned()
Returns:true if the field has some data in its form’s cleanedData.
BoundField#isEmpty()
Returns:true true if the value which will be displayed in the field’s widget is empty.
BoundField#isPending()
Returns:true if the field has a pending asynchronous validation.
BoundField#isHidden()
Returns:true if the field is configured with a hidden widget.

Field data: methods for accessing data related to the field.

BoundField#autoId()

Calculates and returns the id attribute for this BoundField if the associated form has an autoId set, or set to true. Returns an empty string otherwise.

BoundField#data()
Returns:Raw input data for the field or null if it wasn’t given.
BoundField#errors()
Returns:validation errors for the field - if there were none, an empty error list object will be returned.
Type:ErrorList() (by default, but configurable via Form() kwargs.errorConstructor)
BoundField#errorMessage()

Convenience method for getting the first error message for the field, as a single error message is the most common error scenario for a field.

Returns:the first validation error message for the field - if there were none, returns undefined.
BoundField#errorMessages()
Returns:all validation error messages for the field - if there were none, returns an empty list.
BoundField#idForLabel()

Wrapper around the field widget’s Widget#idForLabel(). Useful, for example, for focusing on this field regardless of whether it has a single widget or a MutiWidget().

BoundField#initialValue()

Returns the initial value for the field, will be null if none was configured on the field or given to the form.

BoundField#value()

Returns the value to be displayed in the field’s widget.

Rendering:: methods for, and related to, rendering a widget for the field.

BoundField#asWidget([kwargs])

Renders a widget for the field.

Arguments:
  • kwargs (Object) – widget options, which are as follows:
  • kwargs.widget (Widget) – an override for the widget used to render the field - if not provided, the field’s configured widget will be used.
  • kwargs.attrs (Object) – additional HTML attributes to be added to the field’s widget.
BoundField#asHidden([kwargs])

Renders the field as a hidden field.

Arguments:
  • kwargs (Object) – widget options, which are as follows
  • kwargs.attrs (Object) – additional HTML attributes to be added to the field’s widget.
BoundField#asText([kwargs])

Renders the field as a text input.

Arguments:
  • kwargs (Object) – widget options, which are as follows:
  • kwargs.attrs (Object) – additional HTML attributes to be added to the field’s widget.
BoundField#asTextarea([kwargs])

Renders the field as a textarea.

Arguments:
  • kwargs (Object) – widget options, which are as follows:
  • kwargs.attrs (Object) – additional HTML attributes to be added to the field’s widget.
BoundField#cssClasses([extraClasses])

Returns a string of space-separated CSS classes to be applied to the field.

Arguments:
  • extraClasses (String) – additional CSS classes to be applied to the field
BoundField#helpTextTag([kwargs])

Renders a tag containing help text for the field.

Arguments:
  • kwargs (Object) – help text tag options, which are as follows:
  • kwargs.tagName (String) – allows overriding the type of tag – defaults to 'span'.
  • kwargs.contents (String|Object) –

    help text contents – if not provided, contents will be taken from the field itself.

    To render raw HTML in help text, it should be specified using the React convention for raw HTML, which is to provide an object with a __html property:

    {__html: 'But <strong>be careful</strong>!'}
    
  • kwargs.attrs (Object) – additional attributes to be added to the tag – by default it will get a className of 'helpText'.
BoundField#labelTag([kwargs])

Creates a <label> for the field if it has an id attribute, otherwise generates a text label.

Arguments:
  • kwargs (Object) – label options, which are as follows:
  • kwargs.contents (String) – custom contents for the label – if not provided, label contents will be generated from the field itself.
  • kwargs.attrs (Object) – additional HTML attributes to be added to the label tag.
  • kwargs.labelSuffix (String) – a custom suffix for the label.
BoundField#render([kwargs])

Default rendering method - if the field has showHiddenInitial set, renders the default widget and a hidden version, otherwise just renders the default widget for the field.

Arguments:
BoundField#subWidgets()
Returns:a list of SubWidget() objects that comprise all widgets in this BoundField. This really is only useful for RadioSelect() and CheckboxSelectMultiple() widgets, so that you can iterate over individual inputs when rendering.