The plugin can be used normally in any browser as well as in the node.js server-side environment.
Install using the package manager for your desired environment(s):
Obviously, this plugin depends on Backbone along with its dependencies.
The API supports both Backbone collections and models. The main difference what data is sent to the server when selected model attributes are sent and how the server response is handled.
Giving your model actions is as simple as adding a new hash and calling this plugin in your model's
actions can even be a function that returns a hash.
Book model has the 2 additional functions;
getPages which, when
called, will result in a request being sent to the server based on their options as well as any options passed in.
If the server returns an attribute hash, those values will then be applied to the model. In the previous example the following requests would have been sent to the server:
POST http://example.com/books/hobbit/buy GET http://example.com/books/hobbit/pages?pageCount=310
The first request would have been sent the JSON-formatted data in the request body.
Each action function accepts optional data (to be sent to the server) and options (to configure the action) that can overload the defaults for that action.
There's a lot of ways in which actions can be declared so let's go over the different configurations. Each configuration can also be a function that returns the value to be used and all are entirely optional. Even the whole action can be a function that returns the configuration hash.
Any other undocumented configurations will simply be passed along to Backbone.sync and, eventually, Backbone.ajax as options. Action functions also support the same asynchronous patterns as Backbone.ajax whose result is also used as their return value.
A subset of attributes to be picked from the model and sent to the server. If used on a collection, this is done for each child model of the collection and then that mapping is sent to the server.
Note: If the
data configuration is used, this will be ignored.
JSON-ifiable value that is to be sent to the server in the request body.
Note: If the
attrs configuration is used and no
data is specified, the
resulting attributes hash will replace the populate this value.
The CRUD method to be passed to Backbone.sync. By default this is the value of defaultMethod. This can be any of the following methods;
The path to be appended to URL of the model, which is used as the target of the server request. If this is not specified, the parseName function will be called instead to derive an appropriate path based on the action's name.
The default CRUD method used internally by
Backbone. This can be any of the same values for the method configuration but, by
If an action doesn't specify a
url, this function will be called to derive a path from it's name.
By default, it simply returns the
name with no modifications, but this allows you to customize this
behaviour. For example; if you wanted actions with names in camel case to instead use hypens you could use something
like the following;
The current version of this plugin.
Two different events will be trigger by this plugin:
- (model, name, resp, options)
- When a model's action has successfully completed
- (model, resp, options)
- When a specific action has successfully completed
#4: Add support for
- #5: Add support for Backbone v1.1.2
- #8: Change methods from HTTP to CRUD to match Backbone API
#10: Change parameters for calling action methods
options(both still optional)
- #10: Action names must not match any existing property names
- #11: Fix bug with Backbone module import on node.js
- Improve code styling
- Bump development dependencies
If you have any problems with this library or would like to see the changes currently in development browse our issues.
See the Contributing document for more details.
Take a look at the documentation to get a better understanding of what the code is doing.
If that doesn't help, feel free to follow me on Twitter, @neocotic.