Forms API¶
Form
¶
-
Form.
extend
(prototypeProps[, constructorProps])¶ This is the entry point for defining your own forms.
Creates a new constructor which inherits from Form.
Arguments: - prototypeProps (Object) –
form Fields and other prototype properties for the new form, such as a custom constructor and validation methods.
See
DeclarativeFieldsMeta()
for details of how Fields passed as prototypeProps are handled. - constructorProps (Object) – properties to be set directly on the new constructor function.
- prototypeProps (Object) –
-
class
Form
([kwargs])¶ A collection of Fields that knows how to validate and display itself.
Arguments: - kwargs (Object) – form options, which are as follows:
- kwargs.data (Object) – input form data, where property names are field names. A form with data is considered to be “bound” and ready for use validating and coercing the given data.
- kwargs.files (Object) – input file data.
- kwargs.errors (ErrorObject) –
initial errors to be displayed.
Note
Passing initial errors will prevent validation from firing if a form has input
data
andisValid()
orerrors()
are called during rendering.This argument is intended for redisplaying a form with the user’s input and errors received from another source, such as an API call.
This is more typical of server-side usage.
- kwargs.validation –
Configures form-wide interactive validation when the user makes changes to form inputs in the browser. This can be a String, or an Object which configures default validation for form inputs.
If
'manual'
, interactive validation will not be performed – you are responsible for hooking up validation and using methods such assetData()
andisValid()
to perform all validation. This is the default setting.If an Object is given, it should have the following properties:
on
- The name of the default event to use to trigger validation. For
example, if
'blur'
, text input validation will be performed when the input loses focus after editing. Multiple, space-separated event names can be given. onChangeDelay
- A delay, in milliseconds, to be used to debounce performing of
onChange
validation.
If
'auto'
, validation behaviour will be the equivalent of having passed:..code-block: javascript
validation: {on: ‘blur change’, onChangeDelay: 369}If any String but
'manual'
or'auto'
is given, it will be used as if it were passed as theon
property of an Object.For example, passing
{validation: 'change'}
will cause form inputs to trigger validation as soon as the user makes any change.New in version 0.6.
- kwargs.controlled (Boolean) –
Configures whether or not the form will render controlled components - when using controlled components, you can update the values displayed in the form after its initial render using
form.setData()
orform.updateData()
New in version 0.6.
- kwargs.onChange (Function) –
If interactive validation is configured for a Form or any of its Fields, this callback function must be provided, or an Error will be thrown.
It will be called any time the form’s input data or validation state changes as the result of user input.
Typically, this function should at least force React to update the component in which the Form is being rendered, to display the latest validation state to the user from the last change they made to the form.
New in version 0.9: Replaces
kwargs.onStateChange
- kwargs.autoId (String) – a template for use when automatically generating
id
attributes for fields, which should contain a{name}
placeholder for the field name – defaults toid_{name}
. - kwargs.prefix (String) – a prefix to be applied to the name of each field in this instance of the
form - using a prefix allows you to easily work with multiple instances of
the same Form object in the same HTML
<form>
, or to safely mix Form objects which have fields with the same names. - kwargs.initial (Object) – initial form data, where property names are field names – if a field’s
value is not specified in
data
, these values will be used when initially rendering field widgets. - kwargs.errorConstructor (Function) – the constructor function to be used when creating error details. Defaults
to
ErrorList()
. - kwargs.labelSuffix (String) – a suffix to be used when generating labels in one of the convenience
methods which renders the entire Form – defaults to
':'
. - kwargs.emptyPermitted (Boolean) – if
true
, the form is allowed to be empty – defaults tofalse
.
Prototype Properties
-
Form#prefixFormat
¶ This string defines the format used to generate
name
attributes for fields when a form instance is given aprefix
. It must contain{prefix}
and{name}
placeholders.The default format is
'{prefix}-{name}'
.Type String:
Instance Properties
Form options documented in
kwargs
above are all set as instance properties.The following instance properties are also available:
-
form.
fields
¶ Form fields for this instance of the form.
Since a particular instance might want to alter its fields based on data passed to its constructor, fields given as part of the form definition are deep-copied into
fields
every time a new instance is created.Instances should only ever modify
fields
.Note
fields
does not exist until theForm
constructor has been called on the form instance that’s being constructed.This is important to note when you intend to dynamically modify
fields
when extending a form – you must call the constructor of the form which has been extended before attempting to modifyfields
.Type: Object with field names as property names and Field instances as properties.
-
form.
isInitialRender
¶ Determines if this form has been given input data which can be validated.
true
if the form hasdata
orfiles
set.
-
form.
cleanedData
¶ After a form has been validated, it will have a
cleanedData
property. If your data does not validate,cleanedData
will contain only the valid fields.Type: Object with field names as property names and valid, cleaned values coerced to the appropriate JavaScript type as properties.
Prototype Functions
Validation: Methods for validating and getting information about the results of validation:
-
Form#validate
([form[, callback(err, isValid, cleanedData)]])¶ Forces the form to revalidate from scratch. If a
<form>
is given, data from it will be set on this form first. Otherwise, validation will be done with this form’s current input data.Arguments: - form – a
<form>
DOM node – if React’s representation of the<form>
is given, itsgetDOMNode()
function will be called to get the real DOM node. - Boolean, Object) callback (function(Error,) –
Callback for asynchronous validation.
This argument is required if the form uses asynchronous validation - an Error will be thrown if it’s not given in this case.
The callback should be an errback with the signature
(err, isValid, cleanedData)
.
Returns: true
if the form only has synchronous validation and is valid.New in version 0.6.
Changed in version 0.10: Added callback argument for async validation.
- form – a
-
Form#fullClean
()¶ Validates and cleans
forms.data
and populates errors andcleanedData
.You shouldn’t need to call this function directly in general use, as it’s called for you when necessary by
Form#isValid()
andForm#errors()
.
-
Form#partialClean
(fieldNames)¶ Validates and cleans
form.data
for the given field names and triggers cross-form cleaning in case anyform.cleanedData
it uses has changed.Arguments: - fieldNames (Array) – a list of unprefixed field names.
-
Form#clean
([callback(err, validationError)])¶ Hook for doing any extra form-wide cleaning after each Field’s
Field#clean()
has been called. AnyValidationError()
thrown by this method will not be associated with a particular field; it will have a special-case association with the field named'__all__'
.Arguments: - String|ValidationError) callback (function(Error,) – Optional callback for asynchronous validation.
Changed in version 0.10: This method can now be defined with a
callback
parameter if it needs to perform async validation. The form will provide a callback function and wait for it to be called before finishing validation.
Data mutability: Methods for programmatically changing the form’s data.
-
Form#reset
([initialData])¶ Resets the form to its initial render state, optionally giving it new initial data.
Arguments: - initialData (Object) – new initial data for the form.
New in version 0.6.
-
Form#setData
(data[, kwargs])¶ Replaces the form’s
form.data
with the given data (and flipsform.isInitialRender
tofalse
, if necessary) and triggers form cleaning and validation, returning the result ofform.isValid()
.Arguments: - data (Object) – new input data for the form
- kwargs (Object) – data updating options, which are as follows:
- kwargs.prefixed (Boolean) –
pass
true
when updating data in a prefixed form and the field names indata
are already prefixed – defaults tofalse
New in version 0.6.
Returns: true
if the form has no errors after validating the updated data,false
otherwise.New in version 0.5.
-
Form#setFormData
(formData)¶ Replaces with form’s input data with data extracted from a
<form>
(i.e. withformData()
).When using multiple forms with prefixes, form data will always be prefixed - using this method when working with manually extracted form data should ensure there are no surprises if moving from non-prefixed forms to prefixed forms.
Arguments: - formData (Object) – new input data for the form, which has been extracted from a
<form>
New in version 0.6.
- formData (Object) –
-
Form#updateData
(data[, kwargs])¶ Updates the form’s
form.data
(and flipsform.isInitialRender
tofalse
, if necessary).By default, triggers validation of fields which had their input data updated, as well as form-wide cleaning.
Arguments: - data (Object) –
partial input data for the form, field name -> input data.
If your form has a prefix, field names in the given data object must also be prefixed.
- kwargs (Object) – data updating options, which are as follows:
- kwargs.prefixed (Boolean) – pass
true
when updating data in a prefixed form and the field names indata
are already prefixed – defaults tofalse
The follwing options are intended for use with controlled forms, when you’re only updating data in order to change what’s displayed in the controlled components:
Arguments: - kwargs.validate (Boolean) – pass
false
if you want to skip validating the updated fields – defaults totrue
. This can be ignored if you’re passing known-good data. - kwargs.clearValidation (Boolean) – pass
false
if you’re skipping validation and you also want to skip clearing of the results of any previous validation on the fields being updated, such as error messages andcleanedData
– defaults totrue
New in version 0.6.
- data (Object) –
BoundFields: Methods which create BoundField helpers for rendering the form’s fields.
-
Form#boundFields
([test])¶ Creates a
BoundField()
for each field in the form, in the order in which the fields were created.Arguments: - test (Function(field,name)) – If provided, this function will be called with
field
andname
arguments - BoundFields will only be generated for fields for whichtrue
is returned.
- test (Function(field,name)) – If provided, this function will be called with
-
Form#boundFieldsObj
([test])¶ A version of
Form#boundFields()
which returns an Object with field names as property names and BoundFields as properties.
-
Form#boundField
(name)¶ Creates a
BoundField()
for the field with the given name.Arguments: - name (String) – the name of a field in the form.
Returns: a list of BoundField()
objects that correspond to hidden fields. Useful for manual form layout.
-
Form#visibleFields
()¶ Returns: a list of BoundField()
objects that do not correspond to hidden fields. The opposite of theForm#hiddenFields()
function.
Error: Methods for wokring with the form’s validation errors.
-
Form#addError
(field, error)¶ This function allows adding errors to specific fields from within the
form.clean()
method, or from outside the form altogether.Arguments: - field (String) – the name of the field to which the error(s) should be added. If its
value is
null
the error will be treated as a non-field error as returned byform.nonFieldErrors()
. - error (String|Array|ValidationError|Object) –
the error argument can be a single error, a list of errors, or an object that maps field names to lists of errors. A single error can be given as a String or an instance of a
ValidationError()
.Multiple errors can be given as an Array, an Object which maps field names to validation errors, or a ValidationError created with an Array or Object.
If the
error
argument is an Object, thefield
argument must benull
– errors will be added to the fields that correspond to the properties of the object.Note
Using
form.addError()
automatically removes the relevant field fromform.cleanedData
.New in version 0.5.
Changed in version 0.10:
addErrpr()
will no longer add a duplicated error message for the same field. This can happen if event-based validation which runs repeatedly adds errors to a field other than that which triggered the validation, such as in a customclean()
method.- field (String) – the name of the field to which the error(s) should be added. If its
value is
-
Form#errors
()¶ Getter for validation errors which first cleans the form if there are no errors defined yet.
Returns: validation errors for the form, as an ErrorObject()
-
Form#nonFieldErrors
()¶ Returns: errors that aren’t associated with a particular field - i.e., errors generated by Form#clean()
, or by callingForm#addError()
and passingnull
instead of a field name. Will be an empty error list object if there are none.
-
Form#setErrors
(errors)¶ This method’s intended use is replacing a Form’s errors with those received from another source, such as an API call which performs additional validation.
Arguments: - errors (ErrorObject) –
Changes: methods for working with changed data.
-
Form#changedData
()¶ Returns: a list of the names of fields which have differences between their initial and currently bound values.
-
Form#hasChanged
()¶ Returns: true
if data differs from initial,false
otherwise.
Status: methods for determining the form’s status:
-
Form#isAsync
()¶ Returns: true
if the form’s prototype defines any custom cleaning methods which have an arity of 1 (which is assumed to mean they have defined an async callback parameter).New in version 0.10.
-
Form#isComplete
()¶ Determines whether or not the form has valid input data for all required fields. This can be used to indicate to the user that a form which is being validated as they fill it in is ready for submission.
A form which has any errors or is pending async validation will not be considered complete.
The distinction between
isComplete()
andForm#isValid()
is that a form which has had, for example, a single field filled in and validated is valid according to the partial validation which has been performed so far (i.e. it doesn’t have any error messages) but isn’t yet complete.New in version 0.6.
Changed in version 0.10: A form which
isPending()
will not be considered complete.
-
Form#isMultipart
()¶ Determines if the form needs to be multipart-encoded in other words, if it has a
FileInput()
.Returns: true
if the form needs to be multipart-encoded.
-
Form#isPending
()¶ Returns: true
if true if the form is waiting for async validation to complete.
-
Form#isValid
()¶ Determines whether or not the form has errors, triggering cleaning of the form first if necessary.
When user input is being incrementally validated as it’s given, this function gives you the current state of validation (i.e. whether or not there are any errors). It will not reflect the validity of the whole form until a method which performs whole-form validation (
Form#validate()
orsetData()
) has been called.Returns: true
if the form is has input data and has no errors,false
otherwise. If errors are being ignored, returnsfalse
.
-
Form#nonFieldPending
()¶ Returns: true` if the form is waiting for async validation of its clean(callback)
method to complete.New in version 0.10.
-
Form#notEmpty
()¶ Determines if a form which is an extra form in a FormSet has changed from its initial values. Extra forms are allowed to be empty, so required fields in them do not become truly required until the form has been modified.
Returns: true
if a form hasemptyPermitted
and has changed from its initial values.New in version 0.9.
Prefixes: Methods for working with form prefixes.
-
Form#addPrefix
(fieldName)¶ Returns: the given field name with a prefix added, if this Form has a prefix.
-
Form#addInitialPrefix
(fieldName)¶ Adds an initial prefix for checking dynamic initial values.
-
Form#removePrefix
(fieldName)¶ Returns: the given field name with a prefix-size chunk chopped off the start if this form has a prefix set and the field name starts with it.
Utilities¶
-
DeclarativeFieldsMeta
(prototypeProps)¶ This mixin function is responsible for setting up form fields when a new Form constructor is being created.
It pops any Fields it finds off the form’s prototype properties object, determines if any forms are also being mixed-in via a
__mixins__
property and handles inheritance of Fields from any form which is being directly extended, such that fields will be given the following order of precedence should there be a naming conflict with any of these three sources:- Fields specified in
prototypeProps
- Fields from a mixed-in form
- Fields from the Form being inherited from
If multiple forms are provided via
__mixins__
, they will be processed from left to right in order of precedence for mixing in fields and prototype properties.Forms can prevent fields from being inherited or mixed in by adding a same-named property to their prototype, which isn’t a Field. It’s suggested that you use
null
as the value when shadowing to make this intent more explicit.- Fields specified in