Falcon.js | Build Stellar Javascript Applications

About Adapters

Adapters act as the glue between collections, models, and views and a backend data source. For the majority of the time you'll never need to interact with the adapter directly. Instead, Falcon.Model.sync() and Falcon.Collection.sync() will call the adapter's sync method when saving/updating data. Additionally, Falcon.View's constructor will call the adapter's getTemplate method to fetch a template's HTML.

By default, Falcon's base adapter does not make any requests to a backend data source. Instead, if you're intending to utilize a backend, you should also include one of the adapters from the List of Adapters. If you need a more customized experience, then feel free to write your own!

If you do decide to write your own adapter, please take note of a few rules of thumb:

Utilize Falcon.Adapter.extend({}) to create a custom adapter from the base adapter
You should always override the sync() method but still call the base Falcon.Adapter sync method. The base Falcon.Adapter sync method returns an object of resolved and standardized options, callback context, request type, and the input data object. Additionally, the returned object from the base sync method, also returns an 'is_valid' flag. If this is set to false, then your custom implementation should not continue as it means that a model's validations failed as part of a POST (create) or PUT (save) routine.
If you're looking to utilize your data source to also serve up View templates, then you may also want to override the getTemplate method
After defining your custom adapter, you should also initilize it and assign it to the Falcon.adapter = new MyCustomAdapter(); configuration. The Falcon.adapter configuration is utilized throughout the application in Falcon.Model.sync(), Falcon.Collection.sync() and the Falcon.View constrcutor (for fetching a template with getTemplate).

List of Adapters

Below is a list of the currently supported adapters. These should be included directly after Falcon and must be included in order to communicate with a backend data source.

Name	Description	Download
jQuery REST Adapter	The jQuery REST Adapter utilizes jquery to perform Ajax calls to a backend data source. This adapter supports both ajax calls for sync methods and an ajax call for the getTemplate method so that we may serve templates up asynchronously. Additionally, this adapter supports extra options: dataType - The data type of the request, default is 'json'. contentType - The return data type of the response, default is 'application/json'. params - Query string parameters to append to the url. headers - An object of additional headers to send with the request. cache - Should we cache the response of this request? The default for this is whatever `Falcon.adapter.cache` is set to.	Production Development Tests

extend Falcon.Adapter.extend( protoProps, [staticProps] )

Method used to create a new adapter that inherits from the base Falcon Adapter.

protoProps: Properties for the prototype of a class
staticProps: Static properties for a given object

1 var DogAdapter = Falcon.Adapter.extend({});

sync adapter.sync( data_object, type, options, context )

Object An object of the standardized input parameters.

This is the core method that Adapters provide which is called by both the Falcon.Model.sync() and Falcon.Collection.sync() methods. This method takes a set of unresolved and non-standard options and passes them through the various different adapter methods to determine the request type, provide standardized options, and determines a callback context. Additionally, this method will run any model validations if we're executing a PUT or POST request against a model.

By itself, this base implementation does not make any requests to a backend data source. Instead, it is up to you, the developer, to choose an implemntation specific adapter that suites your needs (or write your own). Please refer to the 'About Adapters' section to get a list of current adapter implementations. To be more clear, this base adapter class provides the ground work for making and responding to requests, but the actual communication between the front-end application and your data source is provided by adapters who inherit from this base class. For example, if you're using jQuery to connect to a RESTful API with JSON data, then you may want to look at the jQuery Adapter.

Internally, this method will throw an exception if the input data_object isn't a Falcon.Model or Falcon.Collection. If the type checking passes, then this method begins by resolving the request type (resolveRequestType). Following this, it standardizes the options (standardizeOptions) with the resolved request type and then we resolve the context (resolveContext) with both the resolved request type and standardized options. Lastly, if the data object is a Falcon.Model and our request type is "POST" or "PUT", we check to ensure that the model is valid by executing the model validate() method. This method finishes by returning an object of the input data object (data_object), the resolved request type (type), the standardized options (options), the resolved callback context (context), and whether the model is valid or not (is_valid). No actual request to a backend is made.

This method is a pre-request method that should always be called with the same four arguments: data_object, type, options, and context.

This base sync method does not make any requests to a backend data source. Instead it is up to inheritting classes to define how we send and retrive data from a data source. This method must be overriden if writting a custom adapter.

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The standardized options
context: The unresolved request context, will be the context for all of the response handlers

 1 var model = new Falcon.Model();
 2 var adapter = new Falcon.Adapter();
 3 
 4 /* Returns: {
 5 	data_object: model,
 6 	type: "GET",
 7 	options: { ... standardized options ... },
 8 	context: model,
 9 	is_valid: true
10 } */
11 adapter.sync( model, "get", {}, model );

standardizeOptions adapter.standardizeOptions( data_object, type, options, context )

mixed An new object of the standardized options

Used to standardize the input options and ensure that the resultant options object has all of the correct options for our sync request. This method will do a shallow clone on the input options so that we do not disturb the original object.

This method will return an object that, at it's base, will always have:

url - The url to send this request to. This is assigned using the adapter's makeUrl method which should acknowledge a previously defined url in the options and pass that through if it exists otherwise use the data_object's makeUrl method.
data - The data to send to the data source. This is created from the response of the adapter.serializeData method which should pass through any pre-existing 'data' property on the input options. If no 'data' is present, the serializeData method will return the data_objects serialize(attributes) response.
success - The success callback to trigger from within the adapter.successResponseHandler. This will be called on the context and with arguments: data_object, raw_response_data, standardized options, and other adapter-specific arguments.
error - The error callback to trigger from within the adapter.errorResponseHandler. This will be called on the context and with arguments: data_object, raw_response_data, standardized options, and other adapter-specific arguments.
complete - The error callback to trigger from within the adapter.completeResponseHandler. This will be called on the context and with arguments: data_object, raw_response_data, standardized options, and other adapter-specific arguments.
parent - The parent data object to utilize in the makeUrl method. This may be 'null' if we're looking to not utilize a parent at all
attributes - The attributes to pass into the data_object's serialize method (reduces which properties are serialized in the resultant JSON)
fill_options - An object of optional options to pass along to the 'fill' method on successful responses

This method is a pre-request method that should always be called with the same four arguments: data_object, type, options, and context.

This method should always be called with the resolved request type (from resolveRequestType).

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The non-standardized options. This may be an object who's values will be carrier over to the output options, a callback function that will be assigned to the 'complete' property, a string that will be split on ',' and the resultant array assigned to the attributes property, or an array which will be assigned to the 'attribute' property.
context: The unresolved request context, will be the context for all of the response handlers

 1 var parent_model = new Falcon.Model();
 2 var collection = new Falcon.Collection(parent_model);
 3 var other_model = new Falcon.Model();
 4 var adapter = new Falcon.Adapter();
 5 var my_callback = function(){}
 6 
 7 /*
 8 	Returns: {
 9 		url: "",                    //url generated by adapter.makeUrl
10 		data: serialized_collection //The collection.serialize() response
11 		success: function(){},      //Blank success callback
12 		complete: function(){},     //Blank complete callback
13 		error: function(){},        //Blank error callback
14 		parent: parent_model,       //The collection's parent
15 		attributes: null,           //Attributes to serialize
16 		fill_options: null,         //Options to pass to the fill method after success
17 	}
18 */
19 adapter.standardizeOptions( collection, "GET", {}, null ); 
20 
21 /*
22 	Returns: {
23 		url: "http://www.falconjs.com",
24 		data: {'hello': 'world'},
25 		success: my_callback,
26 		error: my_callback,
27 		complete: my_callback,
28 		parent: other_model,
29 		attributes: ["id", "name"],
30 		fill_options: {'method': 'merge'}
31 	}
32 */
33 adapter.standardizeOptions( collection, "GET", {
34 	"url": "http://www.falconjs.com",
35 	"data": {'hello': 'world'},
36 	"success": my_callback,
37 	"error": my_callback,
38 	"complete": my_callback,
39 	"parent": other_model,
40 	"attributes": ["id", "name"],
41 	"fill_options": {'method': 'merge'}
42 }, null);
43 
44 /*
45 	Returns: {
46 		url: "",
47 		data: serialized_collection,
48 		success: function(){},
49 		complete: my_callback,
50 		error: function(){},
51 		parent: parent_model,
52 		attributes: null,
53 		fill_options: null
54 	}
55 */
56 adapter.standardizeOptions( collection, "GET", my_callback, null );
57 
58 /*
59 	Returns: {
60 		url: "",
61 		data: serialized_collection,
62 		success: function(){},
63 		complete: function(){},
64 		error: function(){},
65 		parent: parent_model,
66 		attributes: ["id","name","foo"],
67 		fill_options: null
68 	}
69 */
70 adapter.standardizeOptions( collection, "GET", "id,name,foo", null );
71 
72 /*
73 	Returns: {
74 		url: "",
75 		data: serialized_collection,
76 		success: function(){},
77 		complete: function(){},
78 		error: function(){},
79 		parent: parent_model,
80 		attributes: ["id","name","foo"],
81 		fill_options: null
82 	}
83 */
84 adapter.standardizeOptions( collection, "GET", ["id","name","foo"], null );

getTemplate adapter.getTemplate( uri, loaded_callback )

Falcon.Adapter This instance

Method used to retrieve a template's HTML and return it to the given callback function as its first argument. This method should be overriden by inherriting adapters though it does not need to be. By default, this method expects to get a DOM Element's identifier beginning with a '#'. If the element is found then its innerHTML will be passed back to the callback. If no element is found, then the callback is triggered with an empty string.

uri: The uri of the template to fetch.
callback: A callback method used to return the template HTML

 1 var adapter = new Falcon.Adapter();
 2 
 3 var log_callback = function(html) {
 4 	console.log(html);
 5 };
 6 
 7 // Logs: 'Hello World'
 8 adpater.getTemplate("#hello_world", log_callback);
 9 
10 // Logs: ''
11 // an empty string because no element was found
12 adpater.getTemplate("#invalid_template", log_callback);

Application Javascript

1 <template id="hello_world">
2 	Hello World
3 </template>

Application HTML

successResponseHandler adapter.successResponseHandler( data_object, type, options, context, response_args )

Method used to handle success responses. This will parse the raw response data, present the raw data to the data_object's parse() method, and then use that parsed data to call the data_object's fill() method with the parsed_data and fill options (if specified). This method will also trigger a "fetch" event on GET, "create" event on POST, "save" event on PUT, and "destroy" event on DELETE all with the parsed_data being the trigger arguments. Finally, this method will call the success callback on the given context and with the data_object, raw response data, standardized options, and response_args as its arguments.

This method is a post-request method that should always be called with the same five arguments: data_object, type, options, and context, response_args.

This method does not do anything by itself and should be overridden by an inheritting adapter implementation.

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The standardized options
context: The resolved request context
response_args: An object that inheritting adapters can and should use to pass along the inheriting adapter implementation-specific data between post-request methods

errorResponseHandler adapter.errorResponseHandler( data_object, type, options, context, response_args )

Method to call on erroneous responses. This will parse the raw response data and call the 'error' response method provided in the options on the given context and with the data object, raw response data, standardized options, and the response args as its arguments

This method is a post-request method that should always be called with the same five arguments: data_object, type, options, and context, response_args.

This method does not do anything by itself and should be overridden by an inheritting adapter implementation.

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The standardized options
context: The resolved request context
response_args: An object that inheritting adapters can and should use to pass along the inheriting adapter implementation-specific data between post-request methods

completeResponseHandler adapter.completeResponseHandler( data_object, type, options, context, response_args )

Method to call on completed responses. This will parse the raw response data and call the 'complete' response method provided in the options on the given context and with the data object, raw response data, the standardized options, and the response args as its arguments

This method is a post-request method that should always be called with the same five arguments: data_object, type, options, and context, response_args.

This method does not do anything by itself and should be overridden by an inheritting adapter implementation.

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The standardized options
context: The resolved request context
response_args: An object that inheritting adapters can and should use to pass along the inheriting adapter implementation-specific data between post-request methods

makeUrl adapter.makeUrl( data_object, type, options, context )

String The generated url

Called from within the standardizeOptions method to generate a valid URL for the data object being prepaired. If the input options already have a url property, then that value is returned. Otherwise, the makeUrl() method of the data object is called with the resolvedRequestType and options.parent.

This method is a pre-request method that should always be called with the same four arguments: data_object, type, options, and context.

This method should always be called with the resolved request type (from resolveRequestType) and the standardized options (from or within standardizeOptions).

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The partially standardized options
context: The unresolved request context

1 var model = new Falcon.Model({url: "hello_world"});
2 var adapter = new Falcon.Adapter();
3 
4 // Returns: '/hello_world'
5 apater.makeUrl( model, "GET", {}, model );
6 
7 // Returns: '/foo_bar'
8 adapter.makeUrl( model, "GET", {url: '/foo_bar'}, model );

parseRawResponseData adapter.parseRawResponseData( data_object, type, options, context, response_args )

Object The 'response_args' argument

Method used to parse the raw response data to ensure that it is a javascript array or object to pass along to the data_object's parse() method (eg. Parsing a JSON string). This base implementation does nothing but return the response_args. It is expected that this method will be overridden by an inheritting adapter who's task it is to parse the data and return it from its version of this method properly. This method will be called from the adapter.successResponseHandler, adapter.errorResponseHandler, and adapter.completeResponseHandler

This method is a post-request method that should always be called with the same five arguments: data_object, type, options, and context, response_args.

This method does not do anything by itself and should be overridden by an inheritting adapter implementation.

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The standardized options
context: The resolved request context
response_args: An object that inheritting adapters can and should use to pass along the inheriting adapter implementation-specific data between post-request methods

1 var model = new Falcon.Model();
2 var adapter = new Falcon.Adapter();
3 
4 // Returns: {"hello": "world"}
5 apater.parseRawResponseData( model, "GET", options, model, {"hello": "world"} );

resolveContext adapter.resolveContext( data_object, type, options, context )

mixed The resolved context

Used to discern the context to call the response handlers on. If no context is given as the fourth argument or there's no context property of the standardized the data object will be selected as the context. If no fourth argument is given, but a context is present in the standardized options, then the context from the options will be used. Otherwise, if a fourth context argument is given, that context is returned.

This method is a pre-request method that should always be called with the same four arguments: data_object, type, options, and context.

This method should always be called with the resolved request type (from resolveRequestType) and the standardized options (from standardizeOptions).

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The standardized options
context: The unresolved request context

 1 var model = new Falcon.Model();
 2 var other_model = new Falcon.Model();
 3 var third_model = new Falcon.Model();
 4 var adapter = new Falcon.Adapter();
 5 
 6 // returns model
 7 adapter.resolveContext( model, "GET", {}, null ); 
 8 
 9 // returns other_model
10 adapter.resolveContext( model, "GET", {context: other_model}, null ); 
11 
12 // returns third_model
13 adapter.resolveContext( model, "GET", {}, third_model );

resolveRequestType adapter.resolveRequestType( data_object, type, options, context )

String The resolved request type. 'GET' if we were unable to resolve

Used to reslve and standardize the request type to either GET, PUT, POST, or DELETE. This method will try its best to select the correct type and ensure that it's always returned in the correct format (trimmed and capitalized).

This method is a pre-request method that should always be called with the same four arguments: data_object, type, options, and context.

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The unresolved request type
options: The non-standardized options
context: The unresolved request context, will be the context for all of the response handlers

1 var model = new Falcon.Model();
2 var adapter = new Falcon.Adapter();
3 
4 adapter.resolveRequestType( model, "get", {}, model ); // GET
5 adapter.resolveRequestType( model, "put", {}, model ); // PUT
6 adapter.resolveRequestType( model, "post", {}, model ); // POST
7 adapter.resolveRequestType( model, "delete", {}, model ); // DELETE
8 adapter.resolveRequestType( model, "invalid", {}, model ); // GET

serializeData adapter.serializeData( data_object, type, options, context )

String The generated url

Serializes the data_object by calling its serialize method with the 'attributes' peropety of the standardized options on POST and PUT request types. If a 'data' property already exists on the options, however, then that will always be returned and the 'serialize' method will never be called. The result of this method is typically assigned to the 'data' property of the standradized options from within the standardizeOptions method.

This method is a pre-request method that should always be called with the same four arguments: data_object, type, options, and context.

This method should always be called with the resolved request type (from resolveRequestType) and the standardized options (from or within standardizeOptions).

data_object: The data object being prepaired. Should be either a Falcon.Model or a Falcon.Collection
type: The resolved request type
options: The partially standardized options
context: The unresolved request context

 1 var model = new Falcon.Model({"hello": "world", "foo": "bar"});
 2 var adapter = new Falcon.Adapter();
 3 
 4 // Returns: undefined
 5 apater.serializeData( model, "GET", {}, model );
 6 
 7 // Returns: {"id": null, "hello": "world", "foo": "bar"}
 8 apater.serializeData( model, "POST", {}, model );
 9 
10 // Returns: {"id": null, "hello": "world", "foo": "bar"}
11 apater.serializeData( model, "PUT", {}, model );
12 
13 // Returns: undefined
14 apater.serializeData( model, "DELETE", {}, model );
15 
16 // Returns: {"foo": "bar"}
17 apater.serializeData( model, "POST", {attributes: ["foo"]}, model );
18 
19 // All of these Returns: {"free": "bird"}
20 apater.serializeData( model, "GET", {data: {"free": "bird"}}, model );
21 apater.serializeData( model, "POST", {data: {"free": "bird"}}, model );
22 apater.serializeData( model, "PUT", {data: {"free": "bird"}}, model );
23 apater.serializeData( model, "DELETE", {data: {"free": "bird"}}, model );

Falcon.Adapter extends Falcon.Object

Adapters specify how data is serialized and sent to and received from a backend data source. They also specify how to handle success and error scenarios.