module:bajaux/mixin/batchLoadMixin

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

Description:

• Applies the batchLoad mixin to the target Widget.

  The batchLoad 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 load() method (thus allowing
  multiple Widgets to load and subscribe BajaScript values in a single
  network call).

  It states:

  • If my load() method does receive a batch parameter, and does add
    a transaction to it (say, by passing it to
    baja.comm.Subscriber#subscribe), 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 load() 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 batchLoadMixin to a widget that does not
    actually use a batch.)

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

  Why is this contract necessary? When passing a batch to load(), you
  aren't guaranteed that load() 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, batchLoadMixin.loadWidgets handles a lot of this
  workflow for you.

Source:

• mixin/batchLoadMixin.js, line 99

Example

Example implementation of the batchLoad contract.

MyWidget.prototype.doLoad = function (component, params) {
  var batch = params && params.batch,
      progressCallback = params && params.progressCallback,
      promise = this.getSubscriber().subscribe({
        comps: component,
        batch: batch
      });
  
  //I'm done with the batch - let the caller know they can commit it
  if (progressCallback) {
    progressCallback(batchLoadMixin.COMMIT_READY);
  }
  
  return promise;
};

Parameters:

Name	Type	Description
target	module:bajaux/Widget