Composer.js
- Start
- Class system
- Eventing
- Utilities
- Base
- Model
- Collection
- Controller
- Controller xdom
- Relational model
- Filter collection
- List controller
- Router
- Best practices
- Building/load order
- Tests
Utilities
Composer has a number of utilities that are used throughout the framework, but can also be used by your app as well.
Composer.sync :: function(method, model, options)
Composer’s syncing function. It provides a central location for models and collections to grab and post data to your servers/browser storage/etc. By default, it does nothing and should be overridden by you.
method
is one of “create”, “read”, “update”, “delete”. model
is the model
the sync function is being called on. options
is the options object passed to
the model/collection’s save
, fetch
, destroy
function.
Note that options
also has two functions in it: success
and error
.
success
should be called when the call to your API finishes, the only argument
being the data returned from the API. error
should be called if any errors
happen (first arg is the error, second is the XHR object).
Note that you can also provide syncing functions on a per-model or
per-collection basis by setting the .sync
parameter in that object (ie
mymodel.sync = my_sync_function;
.
Sync function example:
Composer.set_sync :: function(syncfn)
A helper function to set the Composer.sync function. Not super useful in a browser setting, but helpful if running Composer in Node.js.
Composer.cid :: function()
A function that generates client-ids for every object instantiated by Composer. This function can be replaced with your own.
Composer.eq :: function(a, b)
Determines if two objects are equal. Does a deep-inspection of objects and arrays.
Composer.merge_extend :: function(class, array_of_property_names)
See Composer.merge_extend in the class docs.
Composer.array
A collection of array utilities.
erase :: function(array, item)
Erase all instances of an item from an array.
is :: function(obj)
Determine if obj
is an Array object. This can usually be done with
instanceof
, however if you get an array from another window/iframe, the test
will crash and burn. Composer.array.is
has some provisions to work around
this.
Composer.object
A collection of object utilities.
each :: function(obj, fn, bind)
Call fn
for each key/value pair on obj
(optionally binding bind
to fn
’s
scope).
clone :: function(obj, options)
Returns a clone of the given object obj
(shallow by default)`.
options
can contain the following items:
deep
- if true, performs a deep clone
merge :: function(to, …)
Merge a number of objects into to
, objects being listed later having
preference.
set :: function(object, key, value)
Recursively set a value into an object:
get :: function(object, key)
Recursively get a value from an object:
Composer.promisify :: function(options)
New in version 1.0.6, this function replaces the following methods with promise-ready versions:
Instead of accepting options.success
and options.error
, these functions will
now return promises (assuming you have included a promise library in the page).
This changes the interface for these functions a bit, but once you get the hang of it, you can use the same technique for all of them.
options
can contain the following items:
warn
- if true, will fire a warning when trying to use callbacks (iesuccess
orerror
) with a promisified function. This helps to track down places where your app used callbacks previously but no longer uses them.
Here’s an example:
…and now after calling promisify
:
The syntax difference is negligable, however promises offer a lot of power when it comes to stringing together async operations and especially handling errors.
Note that your Composer.sync function will not need to change
once you call promisify
: it still makes use of the options.success
and
options.error
callbacks in the same way.
Note on promisify usage
If you are going to use promisify()
, you need to call it before you define
your app’s Models/Collections, otherwise their prototypes will extend the old
(non-promisified) Composer.Model/Collection objects (and won’t return promises).
Composer.find_parent :: function(selector, element)
Although this is a global utility function, it exists as part of the Controller/Adapter library and is documented there.