module:bajaux/mixin/batchSaveMixin

new (require("bajaux/mixin/batchSaveMixin"))(target)

Description:

• Applies the batchSave mixin to the target Widget.

  The batchSave mixin does not alter the behavior of the target Widget,
  but instead defines a behavioral contract. It defines the way it will
  handle a baja.comm.Batch passed to the save() method (thus allowing
  multiple Widgets to save BajaScript values in a single network call).

  It states:

  • If my save() method does receive a batch parameter, and does add
    a transaction to it (say, by passing it to Component#set), then I
    must notify the caller after I am through adding transactions to that
    Batch and it is safe to commit. I do this by checking for a
    progressCallback parameter, and passing COMMIT_READY to it.
  • If my save() method does not make use of the batch, it must still
    emit COMMIT_READY, but can do so at any time. (Due to this constraint,
    it does not make sense to add batchSaveMixin to a widget that does not
    actually use a batch.)

  Widgets that append transactions to a batch parameter in the save()
  function, without marking themselves with this mixin, should be expected
  have those saves fail. Likewise, passing a batch to a Widget's save()
  function without checking whether it has the batchSave mixin can also
  fail.

  Why is this contract necessary? When passing a batch to save(), you
  aren't guaranteed that save() will not perform some other asynchronous
  work before appending transactions to the batch. If you don't wait for
  the transactions to complete, you run the risk of committing the batch
  prematurely. Then when the widget gets around to appending transactions
  to the already-committed batch, it will fail.

  To make this easier, batchSaveMixin.saveWidgets handles a lot of this
  workflow for you.

Source:

• mixin/batchSaveMixin.js, line 96

Example

Example implementation of the batchSave contract.

MyWidget.prototype.doSave = function (component, params) {
  var batch = params && params.batch,
      progressCallback = params && params.progressCallback,
      promise = component.set({ slot: 'saved', value: true, batch: batch });
  
  //I'm done with the batch - let the caller know they can commit it
  if (progressCallback) {
    progressCallback(batchSaveMixin.COMMIT_READY);
  }
  
  return promise;
};

Parameters:

Name	Type	Description
target	module:bajaux/Widget