The initialize method is called within the actual constructor method of the model. The constructor method has specific set up code that should always be run when creating a model and hence, having the initialize method available, allows developers to override this function to ensure that everything that the actual constructor needs to do is executed prior to the initialize method and everything custom that the developer needs won't interfere with the required operations.
- data
- An object of initial data for this model
- parent
- The object that 'owns' this model. This is used for generating urls in the 'makeUrl' function when syncing data between client and server.
1 var Dog = Falcon.Model.extend({
2 initialize: function() {
3 this.name = "Fido";
4 }
5 });
6
7 var dog = new Dog();
8
9 console.log( dog.get("name") ); // Fido
Method used to create a new model that inherits from the base Falcon Model.
- protoProps
- Properties for the prototype of a class
- staticProps
- Static properties for a given object
1 var Dog = Falcon.Model.extend({
2 url: "dog.json"
3 });
4
5 var dog = new Dog();
6
7 console.log( dog instanceof Falcon.Object ); // true
8 console.log( dog instanceof Falcon.Model ); // true
9 console.log( dog instanceof Dog ); // true
This is the top level url piece that relates to this specific model. This is used in the makeUrl() method to dynamically generate urls for how to interact with the server API. Falcon assumes a typical RESTful url structure when generating urls and hence assumes that each individual model correlates to a common url name. For example if we had a Dog model who's url was 'dog.json', then sending a GET request for a dog with id '1' would generate a URL of: '/dog/1.json'. If this model has a parent model (such as Owner with url 'owner.json' and id of 2), then calling the same GET request with the Owner as the parent, we would get '/owner/2/dog/1.json'. Optionally, url can be a function that returns a string rather than being defined as a string if you need the URL to be dynamic based on environment or other variables.
1 var Dog = Falcon.Model.extend({
2 url: "dog.json"
3 });
1 var Dog = Falcon.Model.extend({
2 url: function() {
3 return "dog.json"
4 }
5 });
1 var Dog = Falcon.Model.extend({
2 url: "dog.json"
3 });
4 var Owner = Falcon.Model.extend({
5 url: function() { return "owner.json"; }
6 });
7
8 var owner = new Owner({id: 2});
9 var dog = new Dog({id: 1}, owner);
10
11 console.log( owner.makeUrl("GET") ); // /owner/2.json
12 console.log( owner.makeUrl("POST") ); // /owner.json
13 console.log( owner.makeUrl("PUT") ); // /owner/2.json
14 console.log( owner.makeUrl("DELETE") ); // /owner/2.json
15
16 console.log( dog.makeUrl("GET") ); // /owner/2/dog/1.json
17 console.log( dog.makeUrl("POST") ); // /owner/2/dog.json
18 console.log( dog.makeUrl("PUT") ); // /owner/2/dog/1.json
19 console.log( dog.makeUrl("DELETE") ); // /owner/2/dog/1.json
This represents the 'parent' object that holds this model. Generally this is used for determining the URL structure of rest objects in the makeURL() routine. This should also be a Model.
1 var Dog = Falcon.Model.extend({"url": "dog.json"});
2 var Owner = Falcon.Model.extend({"url": "owner.json"});
3
4 var owner = new Owner();
5 var dog = new Dog( owner ); // Owner becomes the 'parent' of dog
6
7 console.log( dog.parent === owner ); // true
This is a hash map of non-observable defaults to create whenever an instance of this model is initialized. If the value is a function, the function is called and the return value is assigned. Functions are called in context of this instance and with all the same arguments from the constructor method. Defaults are created before observables which means that any duplicate attributes between the observables (as in the 'observables' attribute on Falcon.Object) and default attributes will be overridden by those in the observables
1 var Dog = Falcon.Model.extend({
2 defaults: {
3 "is_tame": true,
4 "name": function(name) {
5 return ( name || "Fido" );
6 }
7 }
8 });
9
10 var dog = new Dog();
11 console.log( dog.name ); // Fido
12 console.log( dog.is_tame ); // true
13
14 var skip = new Dog("Skip");
15 console.log( skip.name ); // Skip
16 console.log( skip.is_tame ); // true
This is a hash map of the default observables and values that will become properties of this model when a new instance is created. If the value of a specific key is a function a computed observable is created. If the value is an object with the keys 'read' and/or 'write' a computed is created with those object keys as the definition for the computed observable. All computed observables are created with this objects's instance as their context.
1 var Dog = Falcon.Model.extend({
2 observables: {
3 "name": "Fido",
4 "parent_dog_name": "",
5 "child_of_lassie": function(parent_dog_name)
6 {
7 return this.parent_dog_name() === "Lassie";
8 }
9 }
10 });
11
12 var dog = new Dog(); // Dog not related to Lassie
13
14 console.log( ko.isObservable( dog.name ) ); // true
15 console.log( ko.isComputed( dog.child_of_lassie ) ); // true
16
17 console.log( dog.name() ); // Fido
18 console.log( dog.child_of_lassie() ); // false
19
20 dog.name("Spot");
21 dog.parent_dog_name("Lassie");
22
23 console.log( dog.name() ); // Spot
24 console.log( dog.child_of_lassie() ); // true
Method used to create a clone of this model. This method is can be used to only copy certain attributes from this model by stating so in the 'attributes' argument. If a 'parent' argument is given, then the resultant model will have that parent rather than the original model's parent. If 'null' is given for parent, then the resultant model will not have a parent.
- attributes
- An object or an array attributes to copy from this model to the new model. If this is not provided all attributes will be copied.
- parent
- An override of the parent to set in the resultant model. If 'null' is explicitly given, then the resultant model will be parent-free
1 var Dog = Falcon.Model.extend();
2
3 var dog = new Dog({"name": "fido"});
4 var fido_clone = dog.clone();
5
6 console.log( dog.get("name"), fido_clone.get("name") ); // fido, fido
7 console.log( dog === fido_clone ); // false
Method used to create a new model, with this model's data, on the server. This method is really just a wrapper around the 'sync' method with a request type of 'POST' auto-filled.
- options
- The options to pass into the 'sync' method
1 var Dog = Falcon.Model.extend({ url: "dog.json" });
2
3 var dog = new Dog({name: "Fido"});
4
5 // Create a dog
6 // Sends the data {"name": "Fido"} to '/dog.json'
7 // If using the jQuery adapter, this will be an ajax POST to '/dog.json'
8 dog.create();
Decrements the value of a property at the key given by one.
- key
- The property that we should decrement.
1 var Dog = Falcon.Model.extend();
2
3 var dog = new Dog({
4 "bark_count": ko.observable(1)
5 });
6 dog.decrement("bark_count");
7 console.log( dog.get("bark_count") ); // 0
Method used to delete this model from the server. This method just called 'sync' with the 'DELETE' request type pre-filled.
- options
- The options to pass into the 'sync' method
1 var Dog = Falcon.Model.extend({ url: "dog.json" });
2
3 var dog = new Dog({id: '1', name: "Fido"});
4
5 // Delete a dog
6 // Sends the data {"id": 1, "name": "Fido"} to '/dog/1.json'
7 // If using the jQuery adapter, this will be an ajax DELETE to '/dog/1.json'
8 dog.destroy();
Method used to determine if this model matches the given model or id. If any model as 'null' id then this method will always consider the result to be unequal.
- model
- A model to compare against this model. Models are compared using ids. If either or both IDs are 'null' then these models will always be unequal
- id
- An id to check against this model's id
1 var Dog = Falcon.Model.extend({ name: "" });
2
3 var dog = new Dog({"id": 1, "name": "Fido"});
4 var another_dog = new Dog({"id": 2, "name": "Another"});
5
6 console.log( dog.equals(1) ); // true
7 console.log( dog.equals(another_dog) ); // false
8 console.log( dog.equals(dog.clone()) ); // true, checks based on id
Method used to 'fetch' data from the server about this specific model. This method just called 'sync' with the 'GET' request type pre-filled.
- options
- The options to pass into the 'sync' method
1 var Dog = Falcon.Model.extend({ url: "dog.json" });
2
3 var dog = new Dog({id: '1'});
4
5 // Retrieves information about a dog
6 // Requests data from '/dog/1.json'
7 // If using the jQuery adapter, this will be an ajax GET to '/dog/1.json'
8 dog.fetch();
Method used to fill this model with data. This is more advanced than the 'set' method as it won't overwrite certain data if it exists. Specificaly this will recurse data into any Falcon Model of Collection 'fill' method as necessary. Additionally, this will put data into observables if a specific attribute identifies as a writeable observable. Lastly, this will do a basic assignment of a given attribute if it isn't a Falcon Data Object or an observable. Note: This method will, intentionally, ignore any attribute/method defined in the Falcon.Model.prototype except for 'id' and 'url'
- data
- The data to fill this object with.
1 var Dog = Falcon.Model.extend({
2 defaults: {
3 "name": ""
4 },
5
6 observables: {
7 "is_tame": true
8 }
9 });
10
11 var dog = new Dog();
12
13 dog.fill({"name": "Fido", "is_tame": false});
14
15 console.log( dog.get("name") ); // Fido
16 console.log( dog.get("is_tame") ); // false
Method used to look up the value of an attribute on this model. If the attribute is an observable, then the observable is unwrapped and its internal value is returned.
- attribute
- The attribute to look up
1 var Dog = Falcon.Model.extend({
2 defaults: {
3 "name": "Fido"
4 },
5
6 observables: {
7 "hello": "world"
8 }
9 });
10
11 var dog = new Dog();
12
13 console.log( ko.isObservable( dog.name ) ); // false
14 console.log( ko.isObservable( dog.hello ) ); // true
15 console.log( dog.get("name") ); // Fido
16 console.log( dog.get("hello") ); // world
The id of this model. By default this is null unless it is set by the server. The id expected to be a Number or a String.
1 var Dog = Falcon.Model.extend({
2 defaults: {
3 "name": "Fido"
4 }
5 });
6
7 var dog = new Dog({id: 1});
8
9 console.log( dog.id ); // 1
10 console.log( dog.get("id") ); // 1
Increments the value of a property at the key given by one.
- key
- The property that we should increment.
1 var Dog = Falcon.Model.extend();
2
3 var dog = new Dog({
4 "bark_count": ko.observable(1)
5 });
6 dog.increment("bark_count");
7 console.log( dog.get("bark_count") ); // 2
Method used to determine if this model is 'new' or not. A model is deemed new if no id has been set (it's still null).
1 var Dog = Falcon.Model.extend({
2 defaults: {
3 "name": "Fido"
4 }
5 });
6
7 var dog = new Dog()
8
9 console.log( dog.isNew() ); // true
10
11 dog.set("id", 1)
12
13 console.log( dog.isNew() ); // false
Generates a URL based on this model's url, the parent model of this model, the type of request we're making and Falcon's defined baseApiUrl
- type
- The type of request we're making (GET, POST, PUT, DELETE)
- parent
- Optional override of the model's parent to generate the url with. If parent is 'null' then this model will act as the root node.
- id
- Optional override of the id to use.
1 Falcon.baseApiUrl = "http://www.falconjs.com/";
2 var Dog = Falcon.Model.extend({'url': "dog.json"});
3 var Owner = Falcon.Model.extend({'url': "owner.json"});
4
5 var owner = new Owner({"id": 1});
6 var dog = new Dog({"id": 2}, owner); // owner is the 'parent' model
7
8 // baseApiUrl + parent url piece + model url piece + model id (if applicable) + extension
9 console.log( dog.makeUrl("GET") ); // http://www.falconjs.com/owner/1/dog/2.json
10 console.log( dog.makeUrl("POST") ); // http://www.falconjs.com/owner/1/dog.json
11 console.log( dog.makeUrl("PUT") ); // http://www.falconjs.com/owner/1/dog/2.json
12 console.log( dog.makeUrl("DELETE") ); // http://www.falconjs.com/owner/1/dog/2.json
13 console.log( dog.makeUrl("GET", null) ); // http://www.falconjs.com/dog/2.json
Maps extra attributes and methods onto this model for use later, mostly in Falcon views. Will ensure that any method that is not a Knockout observable will be called in the context of this model as well as pass this model in as the first argument, pushing the other arguments down the list.
- mapping
- The mapping to augment this model with
1 var Dog = Falcon.Model.extend({
2 defaults: {
3 "name": "Fido"
4 }
5 });
6
7 var dog = new Dog();
8
9 console.log( ko.isObservable( dog.name ) ); // false
10 console.log( dog.bark instanceof Function ); // false
11
12 dog.mixin({
13 "name": ko.observable(),
14 "bark": function() {
15 console.log( this.get("name") + " says woof!");
16 }
17 });
18
19 console.log( ko.isObservable( dog.name ) ); // true
20 console.log( dog.bark instanceof Function ); // true
21
22 dog.bark() // Fido says woof!
Parses the response data from an XmlHttpRequest request. A json object must be returned from this method in order for the data to be filled back into the model properly. This is useful if you're in need of converting a server response into a different format before attempting to fill all of the model's data.
- data
- The raw response data
- options
- The options fed initially into the 'sync' request
- xhr
- The XmlHttpRequest object
1 {
2 "meta": {
3 "page": 1,
4 "page_size": 10,
5 "page_count": 3
6 },
7 "data": {
8 "id": 1,
9 "name": "Fido"
10 }
11 }
Example Server Response JSON for /dog.json
1 var Dog = Falcon.Model.extend({
2 'url': "dog.json",
3
4 defaults: {
5 "name": ""
6 }
7
8 // Example parse method, the object that is returned from
9 // this will be passed into the model's fill() method.
10 parse: function( response ) {
11 return response["data"];
12 }
13 });
14
15 var dog = new Dog();
16
17 // Get's the server data and runs the parse method
18 // Callback is called on complete
19 dog.fetch(function() {
20 console.log( dog.get("id") ); // 1
21 console.log( dog.get("name") ); // Fido
22 });
Calls the sync method with 'PUT' as the default request type. Saves this model to the server. If the model is new then 'create' will be called instead.
- options
- Optional object of settings to use on this call.
1 var Dog = Falcon.Model.extend({ url: "dog.json" });
2
3 var dog = new Dog({id: '1', name: "Fido"});
4
5 // Updates information about a dog
6 // Sends the data {"id": 1, "name": "Fido"} to '/dog/1.json'
7 // If using the jQuery adapter, this will be an ajax PUT to '/dog.json'
8 dog.save();
Serializes the data into a raw json object and only corresponds to the attributes that are primitive and that we wish to be able to send back to the server.
- attributes
- The attributes that should be included in the serialization. If none given, all attributes from this model (except for functions) are serialized
1 var Dog = Falcon.Model.extend({
2 url: 'dog.json',
3
4 defaults: {
5 "name": "Fido",
6 "color": "Black"
7 }
8 });
9
10 var dog = new Dog({"id": 1});
11
12 console.log( dog.serialize() ); // {"id": 1, "name": "Fido", "color": "Black"}
13
14 dog.set("name", "Spot");
15
16 console.log( dog.serialize(["name"]) ); // {"name": "Spot"}
Sets a value for the specific attribute, creating one if it does nto exist. If an object is passed into the first argument of this method, each of the object's key value pairs will be set on this model.
- attribute
- The attribute to look up
- value
- The value to assign
- values
- An object of values to set
1 var Dog = Falcon.Model.extend({
2 url: "dog.json",
3
4 defaults: {
5 "name": "",
6 "color": ""
7 }
8 });
9
10 var dog = new Dog({'id': 1});
11
12 dog.set("name", "Fido");
13 dog.set("color", "Black");
14
15 console.log( dog.get("name") ); // Fido
16 console.log( dog.get("color") ); // Black
17
18 dog.set({
19 "name": "Spot",
20 "color": "Tan"
21 });
22
23 console.log( dog.get("name") ); // Spot
24 console.log( dog.get("color") ); // Tan
Method used to interact with the backend API and this collection. Internally this method just calls the Falcon.adapter.sync method.
- type
- The HTTP Method to call to the backend with. Valid options options include "GET", "POST", "PUT", "DELETE".
- options
- Optional object of settings to use on this call. Please refer to Falcon.Adapter#standardizeOptions
- context
- An optional context value to execute the callback methods on
1 var Dog = Falcon.Model.extend({
2 "url": "dog.json"
3 });
4
5 var dog = new Dog({id: 1});
6 var parent_dog = new Dog({id: 2});
7
8 // Creates a GET request that will be sent to '/dog/1.json'
9 // each callback method has the same arguments:
10 //
11 // dogs: This model
12 // data: The raw response data prior to being passed into the parse() method
13 // options: The standardized request options
14 // other_args: An object of adapter implementation specific arguments
15 //
16 // All of the callback methods will be called with parent_dog as 'this'
17 dog.sync("GET", {
18 complete: function(dogs, data, options, other_args) {
19 console.log("Completed trying to find the Dog.");
20 },
21
22 success: function(dogs, data, options, other_args) {
23 console.log("Successfully found the Dog!");
24 },
25
26 error: function(dogs, data, options, other_args) {
27 console.log("Couldn't find the dog :(");
28 }
29 }, parent_dog);
Toggles the value between true/false on the specific attribute of this model.
- attribute
- The attribute in the model to look up.
1 var Dog = Falcon.Model.extend({
2 defaults: {
3 "is_tame": true
4 }
5 });
6
7 var dog = new Dog({"is_tame": true});
8
9 console.log( dog.get("is_tame") ); // true
10
11 dog.toggle("is_tame");
12
13 console.log( dog.get("is_tame") ); // false
Method used to validate this model before it is sent to the server on create or save. If this method returns true, saving will continue but if it returns false then saving is halted and no request to the server will be made.
- options
- The options passed into the sync method
1 var Dog = Falcon.Model.extend({
2 url: "dog.json",
3
4 defaults: {
5 "name": ""
6 },
7
8 validate: function() {
9 if( name.length === 0 ) {
10 return false;
11 }
12
13 return true;
14 }
15 });
16
17 var dog = new Dog();
18
19 dog.create(); // Attempts to send a POST request but nothing happens, dog's name is empty
20
21 dog.set("name", "Fido");
22
23 dog.create(); // Allows the model to be saved to the server