Model

Models are the core component of bamboo. They are defined by a schema and options for performing CRUD operations (create, read, update, delete)

Creating a model is done via the model builder (the function returned by require('bamboo/model').

var Post = Model({
    title: String,
    author: {
        name: String,
        email: String
    }
}, { sync: persist_function });

// you can add your own instance methods by adding to the prototype
// of the build Model
Post.prototype.do_something = function() {
    ...
}

Once you have defined a model, you can create a new, unsaved instance.

var post = Post();

// set the properties

// ready to save to server
post.save(function...);

If you want to load a post rather than create on, see the Model.[get] class method.

Make sure to understand the [sync] page for CRUD patterns before creating and persisting models.

model builder

Models are created by passing in two parameters: schema object and optional options object. The model builder will return a constructor like function which can be used to instantiate new instances of the model or load existing instances via the [sync] function.

Models are defined by schemas. Schemas are descriptions of the expected fields of a Model. Only schema fields are loaded/persisted to the backend. Whenever an instance's schema fields are set, the model will emit events to indicate changes.

Schemas use plain javascript style objects and types to indicate the type of each property. You can specify single fields, nested objects, and even arrays.

See the [schema] page for details and examples.

options

Options configure additional behavior for the model.

id

Change the name of the id key field. Default is id.

sync

Specifies the function to use for CRUD operations to/from a backend. Typically this will be over ajax, but you could easily create a localstorage backend, etc.

The bamboo-sync-ajax module provides a sync function that uses ajax.

var ajax = require('bamboo-sync-ajax');

// now pass the ajax var as an option to the model
// { sync: ajax }

See the [sync] wiki page for details on how to implement a sync function.

url_root

Specifies the base url for the model. This base url will be used when performing CRUD operations. The url_root can be set on the created Model class as a class property or even changed on the instance after created.

events

Model state changes will emit events on the model. The most common state changes are schema property changes and persistence changes.

var post = Post();
post.title = 'foobar'; // emits `change title`
post.author.name = 'Poe'; // emits `change author.name`

instance methods

Instance methods are available on individual created instances of models. I.E. a post variable representing a single post and not the Post class which is used to fetch and create posts.

toJSON()

Return the json representation of the Model. Only schema fields will be in the json object.

clone()

Returns a new instance of the model with the same properties of the cloned instance.

is_new()

Returns true if the model is a new instance not yet been persisted.

is_saved()

Returns true if the model has been persisted successfully.

save(cb)

Persist the model using the sync function. Which operation used depends on the new state of the instance. If the instance has an id property then it will be assumed to exist on the server and a PUT (update) method will be used for sync. If the instance does not have an id property, then a POST (create) method will be done on the url_root

fetch(cb)

Sync the model instance properties with the server. Will only work on non-new models (instances where is_new() would return false)

destroy([query, ] cb)

Delete the model by performing a DELETE (delete) sync operation. If the model is_new then this will be a no-op.

Optionally specify a query object to the destroy request.

instance properties

Instance properties (like methods) are available on a per instance basis. Changing these in one instance will not affect other instances.

url

The url for the instance. For is_new() instances this will be the same as the url_root and for persisted or loaded instances it will be the full url where the instance RUD operations are performed; typically url_root/<id>

url_root

Url Root for the instance. This will be the same as Model.url_root in most cases. You should not need to modify this.

class methods

Class methods are available on the created Model class (returned by the Model builder). I.E. The Post variable from the above example.

get(id, cb)

Load a specific Model instance by id. This will perform a read operation on url_root/<id> to load the schema fields.

callback(err, instance) is called on completion. If successfully loaded the fields, instance will be an instance of your defined Model from the model builder.

find([query,] cb)

extend([schema][, opt])

Return a copy of the Model and optionally add additional schema fields. Changing class properties on the new Model will have no effect on the original.

class properties

url_root

The base url for CRUD sync operations. This is set by the url_root option to the Model builder but can be changed by modifying the class property.

// Post.url_root will be '/posts'
var Post = Model({}, { url_root: '/posts' });

// change to /api/posts
Post.url_root = '/api/posts';

Typically this is not modified after the Model is created.