setData() and updateData() now take unprefixed data by default

Prefixed data can still be passed by also passing {prefixed: true}

Added some options to updateData to control how validation or clearing of existing validation state is handled.

docs/forms.rst

@@ -327,7 +327,7 @@ fields). More information about this is in :doc:`validation`.
 Updating a form's input data
 =============================
 
-To update a Form's input data use ``form.setData()``.
+To replace a Form's input data use ``form.setData()``.
 
 This will also trigger validation -- updating ``form.errors()`` and
 ``form.cleanedData``, and returning the result of ``form.isValid()``:

docs/forms_api.rst

@@ -104,15 +104,15 @@ Forms API
 
       .. versionadded:: 0.6
 
-   :param Boolean controlled:
+   :param Boolean kwargs.controlled:
       Configures whether or not the form will render controlled components -
       when using controlled components, you can update the values displayed in
       the form post initial render using ``form.setData()`` or
       ``form.updateData()``
 
       .. versionadded:: 0.6
 
-   :param Function onStateChange:
+   :param Function kwargs.onStateChange:
       .. _ref-form-kwargs-onstatechange:
 
       If interactive validation is configured for a Form or any of its Fields,
@@ -219,7 +219,7 @@ Forms API
       :return:
          ``true`` if the <form> data is valid, ``false`` otherwise.
 
-   .. js:function:: BaseForm#setData(data)
+   .. js:function:: BaseForm#setData(data[, kwargs])
 
       .. versionadded:: 0.5
 
@@ -229,24 +229,53 @@ Forms API
 
       :param Object data: new input data for the form
 
+      :param Object kwargs: data updating options, which are as follows:
+
+      :param Boolean kwargs.prefixed:
+         pass ``true`` when updating data in a prefixed form and the field
+         names in ``data`` are already prefixed -- defaults to ``false``
+
       :return:
          ``true`` if the form has no errors after validating the updated data,
          ``false`` otherwise.
 
-   .. js:function:: BaseForm#updateData(data)
+   .. js:function:: BaseForm#updateData(data[, kwargs])
 
       .. versionadded:: 0.6
 
       Updates the form's :js:attr:`form.data` (and flips :js:attr:`form.isBound`
-      to true, if necessary) then triggers validation of fields which had their
-      input data updated, as well as form-wide cleaning.
+      to true, if necessary).
+
+      By default, triggers validation of fields which had their input data
+      updated, as well as form-wide cleaning.
 
       :param Object data:
          partial input data for the form, field name -> input data.
 
          If your form has a :ref:`prefix <ref-form-prefixes>`, field names in
          the given data object must also be prefixed.
 
+      :param Object kwargs: data updating options, which are as follows:
+
+      :param Boolean kwargs.prefixed:
+         pass ``true`` when updating data in a prefixed form and the field
+         names in ``data`` are already prefixed -- defaults to ``false``
+
+      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:
+
+      :param Boolean kwargs.validate:
+         pass ``false`` if you want to skip validating the  updated fields --
+         defaults to ``true``. This can be ignored if you're passing known-good
+         data.
+
+      :param Boolean kwargs.clearValidation:
+         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 and ``cleanedData`` -- defaults to
+         ``true``
+
    .. js:function:: BaseForm#isValid()
 
       Determines whether or not the form has errors, triggering cleaning of the

lib/forms.js

@@ -468,14 +468,15 @@ BaseForm.prototype.validate = function(form) {
  * @param {Object.<string,*>} data new input data for the form.
  * @retun {boolean} true if the new data is valid.
  */
-BaseForm.prototype.setData = function(data) {
+BaseForm.prototype.setData = function(data, kwargs) {
+  kwargs = object.extend({prefixed: false}, kwargs)
   this._errors = null
   this._changedData = null
-  this.data = data
+  this.data = (kwargs.prefixed ? data : this._prefixData(data))
   if (!this.isBound) {
     this.isBound = true
   }
-  // This call ultimately triggers a fullClean() because _errors isn't set
+  // This call ultimately triggers a fullClean() because _errors is null
   var isValid = this.isValid()
   if (typeof this.onStateChange == 'function') {
     this.onStateChange()
@@ -484,24 +485,33 @@ BaseForm.prototype.setData = function(data) {
 }
 
 /**
- * Updates some of the form's input data, then triggers validation of fields
- * which had their input data updated as well as form-wide cleaning.
+ * Updates some of the form's input data, then optionally triggers validation of
+ * updated fields and form-wide cleaning, or clears existing errors from the
+ * updated fields.
  * @param {Object.<string,*>} data updated input data for the form.
+ * @param {Object.<string,boolean>} kwargs update options.
  */
-BaseForm.prototype.updateData = function(data) {
+BaseForm.prototype.updateData = function(data, kwargs) {
+  kwargs = object.extend({prefixed: false, validate: true, clearValidation: true}, kwargs)
   this._changedData = null
-  object.extend(this.data, data)
+  object.extend(this.data, (kwargs.prefixed ? data : this._prefixData(data)))
   if (!this.isBound) {
     this.isBound = true
   }
 
   var fields = Object.keys(data)
-  if (this.prefix !== null) {
-    for (var i = 0, l = fields.length; i < l; i++) {
-      fields[i] = this.removePrefix(fields[i])
-    }
+  if (kwargs.prefixed) {
+    fields = fields.map(this.removePrefix.bind(this))
+  }
+
+  if (kwargs.validate) {
+    this.partialClean(fields)
+  }
+  else if (kwargs.clearValidation) {
+    this._removeErrors(fields)
+    this._removeCleanedData(fields)
   }
-  this.partialClean(fields)
+
   if (typeof this.onStateChange == 'function') {
     this.onStateChange()
   }
@@ -1093,6 +1103,21 @@ BaseForm.prototype._fieldInitialData = function() {
 }
 
 /**
+ * Return a version of the given data object with prefixes added to the property
+ * names if this form has a prefix, otherwise returns the object itself.
+ * @param {Object.<string,*>} data
+ * @return {Object.<string,*>}
+ */
+BaseForm.prototype._prefixData = function(data) {
+  if (this.prefix === null) { return data }
+  var prefixedData = {}
+  var fieldNames = Object.keys(data)
+  for (var i = 0, l = fieldNames.length; i < l; i++) {
+    prefixedData[fieldNames[i]] = this.addPrefix(data[fieldNames[i]])
+  }
+  return prefixedData
+}
+
  * Returns a list of all the BoundField objects that correspond to hidden
  * fields. Useful for manual form layout.
  */