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 Widget
s to load and subscribe BajaScript values in a single
network call).
It states:
- If my
load()
method does receive abatch
parameter, and does add
a transaction to it (say, by passing it tobaja.comm.Subscriber#subscribe
), then I must notify the caller after I
am through adding transactions to thatBatch
and it is safe to commit.
I do this by checking for aprogressCallback
parameter, and passingCOMMIT_READY
to it. - If my
load()
method does not make use of the batch, it must still
emitCOMMIT_READY
, but can do so at any time. (Due to this constraint,
it does not make sense to addbatchLoadMixin
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 theload()
function can be safely committed.Type:
- string
Methods
-
<static> loadWidgets(widgets, values [, params])
-
Loads values into the given widgets, passing one
Batch
into theload()
method for each one.Widgets that make use of the
Batch
are expected to havebatchLoadMixin
.
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 receiveCOMMIT_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