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 includes cleanedData from incomplete
  extra forms.
• You can no longer change cleanedData by returning a value from a Form's
  clean<Name>() or clean() method.

New Features

• Added RenderForm, FormRow and RenderFormSet components for default
  rendering.
  • The browser build requires the react-with-addons build of React in order to
    use RenderForm's custom rendering support.
• Custom clean() and clean<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.
• form.validate() and formset.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).
• 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's clean(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 fields
  • pendingCssClass - 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 to ErrorList and ErrorObject
  constructors and fromJSON() instance methods. These can be used to rehydrate
  an ErrorObject on the receiving end when form.errors() is transferred as
  JSON. This assumes the structure created by these objects' toJSON() methods.
• Added form.setErrors() to set an ErrorObject with errors from another
  source.
• An ErrorObject can now be passed as an errors 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 input data and
  isValid() or errors() are called during rendering.

Deprecations

• Form rendering methods (render(), asTable(), asDiv() and asUl()) are
  deprecated in favour of using React components for rendering - RenderForm
  now provides default rendering.
• FormSet rendering methods (render(), asTable() and asDiv()) 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 like forceUpdate() just enqueues a
  future re-render.
• form.isComplete() is now false 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 default onBlur
    event from re-running the same validation as the default onChange.
  • Special cases for onBlur:
    • Pending validation is triggered immediately.
    • Validation is always triggered if the field is required and empty.
• Changed form.addError() to no longer add duplicate error messages for the
  same field. This can happen if onChange validation which runs repeatedly
  adds errors to a field other than that which triggered the validation, using
  addError().
• The default rows attribute for a Textarea 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 - use onChange instead.