bajaux

Module: bajaux/mixin/batchLoadMixin

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

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.

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

Members

<static, constant> COMMIT_READY :string

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

Type:
  • string

Methods

<static> loadWidgets(widgets, values [, params])

Loads values into the given widgets, passing one Batch into the load()
method for each one.

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

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

the widgets to load
values Array.<*>

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

a batch to pass into each widget's
load 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
loading

Type
Promise