bajaux

Module: bajaux/mixin/batchSaveMixin

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

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.

Parameters:
Name Type Description
target module:bajaux/Widget
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;
};

Members

<static, constant> COMMIT_READY :string

Value to be passed to a progressCallback parameter to indicate that
a batch given to the save() function can be safely committed.

Type:
  • string

Methods

<static> saveWidgets(widgets [, params])

Saves the given widgets, passing one Batch into the save() method for
each one.

Widgets that make use of the Batch are expected to have batchSaveMixin.
See documentation for the mixin itself for contractual details.

Parameters:
Name Type Argument Description
widgets Array.<module:bajaux/Widget>

the widgets to save
params Object <optional>
Properties
Name Type Argument Description
batch baja.comm.Batch <optional>

a batch to pass into each widget's
save method. If none is given, a new batch will be created and committed.
progressCallback function <optional>

This callback function itself
will receive COMMIT_READY when the input batch is ready to commit.
The callback will not be fired if no batch is input.
Returns:

promise to be resolved when all widgets have completed
saving

Type
Promise