new Rest(pipeName, settings) → {Object}
Status: Stable
The REST adapter is the default type used when creating a new pipe. It uses jQuery.ajax to communicate with the server. By default, the RESTful endpoint used by this pipe is the app's current context, followed by the pipe name. For example, if the app is running on http://mysite.com/myApp, then a pipe named `tasks` would use http://mysite.com/myApp/tasks as its REST endpoint.
This constructor is instantiated when the "PipeLine.add()" method is called
Parameters:
Name | Type | Argument | Default | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pipeName |
String | the name used to reference this particular pipe | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
settings |
Object |
<optional> |
{} | the settings to be passed to the adapter
Properties
|
- Source:
Returns:
The created pipe
- Type
- Object
Example
// Create an empty pipeline
var pipeline = AeroGear.Pipeline();
// Add a new Pipe with a custom baseURL, custom endpoint and default paging turned on
pipeline.add( "customPipe", {
baseURL: "http://customURL.com",
endpoint: "customendpoint",
pageConfig: true
});
// Add a new Pipe with a custom paging options
pipeline.add( "customPipe", {
pageConfig: {
metadataLocation: "header",
previousIdentifier: "back",
nextIdentifier: "forward"
}
});
Methods
-
read(options) → {Object}
-
Reads data from the specified endpoint
Parameters:
Name Type Argument Default Description options
Object <optional>
{} Additional options Properties
Name Type Argument Default Description complete
AeroGear~completeCallbackREST <optional>
a callback to be called when the result of the request to the server is complete, regardless of success error
AeroGear~errorCallbackREST <optional>
a callback to be called when the request to the server results in an error id
Object <optional>
the value to append to the endpoint URL, should be the same as the pipelines recordId jsonp
Mixed <optional>
Turns jsonp on/off for reads, Set to true, or an object with options Properties
Name Type Argument Description callback
String <optional>
Override the callback function name in a jsonp request. This value will be used instead of 'callback' in the 'callback=?' part of the query string in the url customCallback
String <optional>
Specify the callback function name for a JSONP request. This value will be used instead of the random name automatically generated by jQuery limitValue
Number <optional>
10 the maximum number of results the server should return when using a paged pipe offsetValue
String <optional>
"0" the offset of the first element that should be included in the returned collection when using a paged pipe paging
Object | Boolean <optional>
this object can be used to overwrite the default paging parameters to request data from other pages or completely customize the paging functionality, leaving undefined will cause paging to use defaults, setting to false will turn off paging and request all data for this single read request query
Object <optional>
a hash of key/value pairs that can be passed to the server as additional information for use when determining what data to return statusCode
Object <optional>
a collection of status codes and callbacks to fire when the request to the server returns on of those codes. For more info see the statusCode option on the jQuery.ajax page. success
AeroGear~successCallbackREST <optional>
a callback to be called when the result of the request to the server is successful - Source:
Returns:
The jqXHR created by jQuery.ajax. To cancel the request, simply call the abort() method of the jqXHR object which will then trigger the error and complete callbacks for this request. For more info, see the jQuery.ajax page.- Type
- Object
Examples
var myPipe = AeroGear.Pipeline( "tasks" ).pipes[ 0 ]; // Get a set of key/value pairs of all data on the server associated with this pipe var allData = myPipe.read(); // A data object can be passed to filter the data and in the case of REST, // this object is converted to query string parameters which the server can use. // The values would be determined by what the server is expecting var filteredData = myPipe.read({ query: { limit: 10, date: "2012-08-01" ... } });
// JSONP - Default JSONP call to a JSONP server myPipe.read({ jsonp: true, success: function( data ){ ..... } }); // JSONP - JSONP call with a changed callback parameter myPipe.read({ jsonp: { callback: "jsonp" }, success: function( data ){ ..... } });
// Paging - using the default weblinking protocal var defaultPagingPipe = AeroGear.Pipeline([{ name: "webLinking", settings: { endpoint: "pageTestWebLink", pageConfig: true } }]).pipes[0]; // Get a limit of 2 pieces of data from the server, starting from the first page // Calling the "next" function will get the next 2 pieces of data, if available. // Similarily, calling the "previous" function will get the previous 2 pieces of data, if available defaultPagingPipe.read({ offsetValue: 1, limitValue: 2, success: function( data, textStatus, jqXHR ) { data.next({ success: function( data ) { data.previous({ success: function() { } }); } }); } }); // Create a new Pipe with a custom paging options var customPagingPipe = AeroGear.Pipeline([{ name: "customPipe", settings: { pageConfig: { metadataLocation: "header", previousIdentifier: "back", nextIdentifier: "forward" } } }]).pipes[0]; // Even with custom options, you use "next" and "previous" the same way customPagingPipe.read({ offsetValue: 1, limitValue: 2, success: function( data, textStatus, jqXHR ) { data.next({ success: function( data ) { data.previous({ success: function() { } }); } }); } });
-
remove(data, options) → {Object}
-
Remove data asynchronously from the server. Passing nothing will inform the server to remove all data at this pipe's endpoint.
Parameters:
Name Type Argument Default Description data
String | Object <optional>
A variety of objects can be passed to specify the item(s) to remove options
Object <optional>
{} Additional options Properties
Name Type Argument Description complete
AeroGear~completeCallbackREST <optional>
a callback to be called when the result of the request to the server is complete, regardless of success error
AeroGear~errorCallbackREST <optional>
a callback to be called when the request to the server results in an error statusCode
Object <optional>
a collection of status codes and callbacks to fire when the request to the server returns on of those codes. For more info see the statusCode option on the jQuery.ajax page. success
AeroGear~successCallbackREST <optional>
a callback to be called when the result of the request to the server is successful - Source:
Returns:
The jqXHR created by jQuery.ajax. To cancel the request, simply call the abort() method of the jqXHR object which will then trigger the error and complete callbacks for this request. For more info, see the jQuery.ajax page.- Type
- Object
Example
var myPipe = AeroGear.Pipeline( "tasks" ).pipes[ 0 ]; // Store a new task myPipe.save({ title: "Created Task", id: 1 }); // Store another new task myPipe.save({ title: "Another Created Task", id: 2 }); // Store one more new task myPipe.save({ title: "And Another Created Task", id: 3 }); // Remove a particular item from the server by its id myPipe.remove( 1 ); // Delete all remaining data from the server associated with this pipe myPipe.remove();
-
save(data, options) → {Object}
-
Save data asynchronously to the server. If this is a new object (doesn't have a record identifier provided by the server), the data is created on the server (POST) and then that record is sent back to the client including the new server-assigned id, otherwise, the data on the server is updated (PUT).
Parameters:
Name Type Argument Default Description data
Object For new data, this will be an object representing the data to be saved to the server. For updating data, a hash of key/value pairs one of which must be the `recordId` you set during creation of the pipe representing the identifier the server will use to update this record and then any other number of pairs representing the data. The data object is then stringified and passed to the server to be processed. To upload a File, pass in a File or Blob object. *IE Users - File Upload is only supported in IE 10 and above* options
Object <optional>
{} Additional options Properties
Name Type Argument Description complete
AeroGear~completeCallbackREST <optional>
a callback to be called when the result of the request to the server is complete, regardless of success error
AeroGear~errorCallbackREST <optional>
a callback to be called when the request to the server results in an error statusCode
Object <optional>
a collection of status codes and callbacks to fire when the request to the server returns on of those codes. For more info see the statusCode option on the jQuery.ajax page. success
AeroGear~successCallbackREST <optional>
a callback to be called when the result of the request to the server is successful progress
AeroGear~progressCallbackREST <optional>
a callback that is a hook to monitor the upload progress when uploading a File.( if available ) - Source:
Returns:
The jqXHR created by jQuery.ajax. To cancel the request, simply call the abort() method of the jqXHR object which will then trigger the error and complete callbacks for this request. For more info, see the jQuery.ajax page.- Type
- Object
Example
var myPipe = AeroGear.Pipeline( "tasks" ).pipes[ 0 ]; // Store a new task myPipe.save({ title: "Created Task", date: "2012-07-13", ... }); // Pass a success and error callback, in this case using the REST pipe and jQuery.ajax so the functions take the same parameters. myPipe.save({ title: "Another Created Task", date: "2012-07-13", ... }, { success: function( data, textStatus, jqXHR ) { console.log( "Success" ); }, error: function( jqXHR, textStatus, errorThrown ) { console.log( "Error" ); } }); // Update an existing piece of data var toUpdate = { id: "Some Existing ID", title: "Updated Task" } myPipe.save( toUpdate );