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 Widget
s to save BajaScript values in a single network call).
It states:
- If my
save()
method does receive abatch
parameter, and does add
a transaction to it (say, by passing it toComponent#set
), 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
save()
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 addbatchSaveMixin
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 thesave()
function can be safely committed.Type:
- string
Methods
-
<static> saveWidgets(widgets [, params])
-
Saves the given widgets, passing one
Batch
into thesave()
method for
each one.Widgets that make use of the
Batch
are expected to havebatchSaveMixin
.
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 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
saving- Type
- Promise