v0.10.0
Major features in 0.10 are support for asynchronous validation and new React components for default rendering.
Asynchronous validation (docs)
clean()
and clean<FieldName>()
methods can now use asynchronous validation - defining them with a single parameter will let newforms know they will be asynchronous: There is a bunch of new API on Forms, FormSets and BoundFields
cleanUsername: function(cb) {
// ...
}
form.validate()
now takes an additional callback argument which is required if a Form or FormSet has async validation.
Default rendering now includes a <progress>
element on fields, forms and formsets which have pending asynchronous validation.
React components (docs)
Newforms now provides RenderForm
and RenderFormSet
React components for default Form and FormSet rendering:
<RenderForm form={MyForm} ref="myForm"/>
Default rendering methods on Forms and FormSets (.render()
, .asTable()
, .asDiv()
, .asUl()
) are now deprecated and will be removed in the next release.
CHANGES for 0.10.0
Breaking Changes
- Removed
formset.asUl()
- it never appeared properly due to the management
Form. formset.cleanedData()
to no longer includescleanedData
from incomplete
extra forms.- You can no longer change
cleanedData
by returning a value from a Form's
clean<Name>()
orclean()
method.
New Features
- Added
RenderForm
,FormRow
andRenderFormSet
components for default
rendering.- The browser build requires the react-with-addons build of React in order to
useRenderForm
's custom rendering support.
- The browser build requires the react-with-addons build of React in order to
- Custom
clean()
andclean<Field>()
validation methods can now be
specified with the signature(callback)
if they need to perform
asynchronous validation.- The callback is an errback with the signature
(err, validationError)
. clean()
will not be called until other fields - or just fields it
depends on, if configured - have been cleaned, synchronously or
asynchronously.
- The callback is an errback with the signature
form.validate()
andformset.validate()
now take a callback argument,
which is required if the Form or Formset has custom async validation
configured -validate()
can be used as normal for Form and Formsets
without async validation.- The callback is an errback with the signature
(err, isValid, cleanedData)
.
- The callback is an errback with the signature
- New API related to async validation:
form.isAsync()
/formset.isAsync()
-true
if a form/formset has custom
async validation.form.isPending()
/formset.isPending()
-true
if a form/formset has
pending async validation.form.nonFieldPending()
/formset.nonFieldPending()
-true
if async
validation of a form/formset'sclean(cb)
method is pending.boundField.isPending()
-true
if a field has a pending async validation.isFormAsync(Form)
-true
if a Form constructor's prototype has async
validation methods.
<progress>
indicators are now displayed by default rendering methods:- Beside fields with pending async validation.
- At the end of the form when cross-field validation is pending.
- Added more conditional CSS classes which will be used if defined in a Form:
optionalCssClass
- used for optional fieldspendingCssClass
- used for fields with pending async validation
- Added
boundField.helpTextTag()
to expose the mechanism for rendering raw
HTML. - Added
boundField.status()
to get a field's status as a string
(pending/error/valid/default). - Added
fromJSON()
factory functions toErrorList
andErrorObject
constructors andfromJSON()
instance methods. These can be used to rehydrate
anErrorObject
on the receiving end whenform.errors()
is transferred as
JSON. This assumes the structure created by these objects'toJSON()
methods. - Added
form.setErrors()
to set anErrorObject
with errors from another
source. - An
ErrorObject
can now be passed as anerrors
option when creating a form
instance, to redisplay a form with errors from another source. This prevents
the form's own validation from running if the form has inputdata
and
isValid()
orerrors()
are called during rendering.
Deprecations
- Form rendering methods (
render()
,asTable()
,asDiv()
andasUl()
) are
deprecated in favour of using React components for rendering -RenderForm
now provides default rendering. - FormSet rendering methods (
render()
,asTable()
andasDiv()
) are
deprecated in favour of using React components for rendering -RenderFormSet
now provides default rendering.
Changes
- Reverted a change from 0.9. Synchronous calls to
form/formset.validate()
will trigger a re-render, as it looks likeforceUpdate()
just enqueues a
future re-render. form.isComplete()
is nowfalse
if there is any pending async validation,
even if all required fields currently have cleaned data.- Changes to when event-based validation fires:
- Validation now only fires if the field's data has changed since it was last
validated. For'auto'
validation, this prevents the defaultonBlur
event from re-running the same validation as the defaultonChange
. - Special cases for
onBlur
:- Pending validation is triggered immediately.
- Validation is always triggered if the field is required and empty.
- Validation now only fires if the field's data has changed since it was last
- Changed
form.addError()
to no longer add duplicate error messages for the
same field. This can happen ifonChange
validation which runs repeatedly
adds errors to a field other than that which triggered the validation, using
addError()
. - The default
rows
attribute for aTextarea
changed from 10 to 3. - Error messages now make use of a
displayName
property if a Form has one.
Removals
- The deprecated
onStateChange
argument to Form and FormSet constructors has
been removed - useonChange
instead.