Instance properties

You can also “include” instance methods on the model’s prototype. These are often used to link objects together in a way that mimics the relationships the data might have in the remote database (“has many” etc). However, they can be pretty much anything and can overwrite the defaults.

Custom events

Validations

To add your own validations you should define a custom validate() method on your model that adds error messages to the errors object. valid() is called on save() and checks that there are no errors. Validations are useful when using localStorage persistence but can also help you avoid hitting your server unnecessarily if you’re using REST persistence.

Persistence

js-model is different to several other solutions, it’s not a REST-based proxy for the objects on your server and doesn’t rely on constant HTTP requests to gather information. Instead, it looks up objects in its own cache which can be populated via a persistence adapter — think of it as maintaining the state of your objects in the browser.

When responding to POST or PUT requests any JSON returned will be merged into the model’s attributes — you should also make sure to include the id in the POST response so it can be assigned to the model. 422 responses from the server will be interpreted as having failed validations, any returned JSON will be assumed to be errors and replace client-side errors.

Note: If you’re using Rails you should make sure to add the following setting in an initializer as js-model expects non-namespaced JSON:

Loading data

If you have existing data stored in your persistence layer you’ll want to be able to have it available when you next open your app. You’ll typically call load() when your document loads and perform an action when it has completed.

// wait for the document to load$(function(){Project.load(function(){// do something with the UI})})

js-model ♥ Sammy

js-model works really well with Sammy — you are using Sammy right? Your routes might look something like this:

persistence(adapter, ...)

Set or get the persistence adapter for a class. The first argument is a reference to the adapter which is initialised with a reference to the class and any further arguments provided. See persistence for more.

attributes

changes

Attributes set with the attr() method are written to the changes intermediary object rather than directly to the attributes object. This allows you to see any previous attribute values and enables validations — see validate() for more on validations. changes are committed to attributes on successful save().

size()

Persistence interface

Persistence adapters implement CRUD and return an object with the following interface. You probably don’t need to know this but is documented here in case you want to implement your own.

create(model, callback)

Calls the supplied callback with a boolean indicating whether the action was a success or not and any further parameters that the persistence adapter sends.

Project.persistence().create(project,function(success){// do something...})

destroy(model, callback)

Calls the supplied callback with a boolean indicating whether the action was a success or not and any further parameters that the persistence adapter sends.

Project.persistence().destroy(project,function(success){// do something...})

read(callback)

Calls the supplied callback with an array of models — models are not automatically added to the collection when calling read(). You probably won’t need to use this much as this functionality is taken care of by load().

Project.persistence().read(function(models){// do something with the models...})

update(model, callback)

Calls the supplied callback with a boolean indicating whether the action was a success or not and any further parameters that the persistence adapter sends.

Project.persistence().update(project,function(success){// do something...})