jacks-js
v0.2.1
Published
![Travis CI](https://travis-ci.org/jccazeaux/Jacks.svg?branch=master)
Downloads
5
Readme
Jacks
Fluent extensible ajax framework.
GET http://my.api/todos?limit=50
jacks().get("http://my.api/todos")
.query("limit", "50")
.header("Accepts", "application/json")
.send(function(jacksResponse) {
// Callback success
}, function(jacksError) {
// Callback error
});
POST
jacks().post("http://my.api/todos")
.body({"title": "Finish the job",
"date": "2015/12/31"})
.header("Content-Type", "application/json")
.send(function(jacksResponse) {
// Callback success
}, function(jacksError) {
// Callback error
});
Main API
jacks()
This creates a new instance of jacks. This instance will be an empty shell and the base to create requests. Each instance will have its own configuration (see plugins and use). So you can have many instances of jacks, each using different sorts of configuration. In your application you should keep the instances in a context to avoid a recreation each time you need it.
A jacks instance is only the beginning, to start a request use the methods described below.
jacks().get(<String> url)
Creates a GET JacksRequest with the url
jacks().post(<String> url)
Creates a POST JacksRequest with the url
jacks().put(<String> url)
Creates a PUT JacksRequest with the url
jacks().delete(<String> url)
Creates a DELETE JacksRequest with the url
jacks().options(<String> url)
Creates a OPTIONS JacksRequest with the url
jacks().head(<String> url)
Creates a HEAD JacksRequest with the url
jacks.plugin(<String> pluginName, <Function> pluginFn)
You can add a plugin to jacks using the plugin() function on jacks (not on request)
jacks.plugin("pluginName", function(jacksRequest) {
// Access to all request methods
});
A plugin is a function wich receives the request as parameter.
jacks.use(<String> pluginName) | use(<Function> pluginFn)
Use a plugin. Parameter can be the name of a declared plugin or a function for a live plugin
jacks().use("myPlugin")
.use(function(jacksRequest) {
// Plugin code
})
This plugin will be used for all requests.
Mocks
Jacks comes with a mock API.
jacks.mock(request, response);
request
Request defines wich requests are mocked. It contains two attributes
- url : url of mocked resource. Can be a String or a regular expression
- method : mocked method. If not specifed, all methods will be mocked
response
Mocked response to send
- responseText : Text of the response
- response : function callback to create a dynamic responseText. The function takes as only parameter a "done" callback. Use it if your callback is asynchronous.
- headers : response headers
- status : status code
- statusText : status text
- error : mock an error
- delay : simulates a delayed response. In ms.
Exemples
Basic mock
jacks.mock({
url: "/myurl"
}, {
responseText: "My mocked response",
headers: {"Content-Type": "plain/text"}
});
Dynamic mock
jacks.mock({
url: "/myurl"
}, {
response: function() {
this.responseText = "My dynamic mock";
},
headers: {"Content-Type": "plain/text"}
});
Asynchronous dynamic mock
jacks.mock({
url: "/myurl"
}, {
response: function(done) {
var that = this;
setTimeout(function() {
that.responseText = "My dynamic mock";
done();
}, 0);
},
headers: {"Content-Type": "plain/text"}
});
JacksRequest API
jacksRequest.body(<Object> data)
Sets the body. Only for POST and PUT
jacks().post("http://myurl")
.body({"age": 35, "city": "Bordeaux"})
.send(function(jacksReponse) {
// Callback success
}, function(jacksError) {
// Callback error
});
jacksRequest.query(<String> name, <String> value) | query(<Object> params)
Add query parameters. Will concatenate the query parameters to the URL.
jacks().get("http://myurl")
.query("age", "35")
.query({"age": 35, "city": "Bordeaux"})
.send(function(jacksReponse) {
// Callback success
}, function(jacksError) {
// Callback error
});
jacksRequest.header(<String> name, <String> value)
Add a request header.
jacks().get("http://myurl")
.header("X-MY-HEADER", "foo")
jacksRequest.use(<String> pluginName) | use(<Function> pluginFn)
Use a plugin. Parameter can be the name of a declared plugin or a function for a live plugin
jacks().get("http://myurl")
.use("myPlugin")
.use(function(jacksRequest) {
// Plugin code
})
The plugin will be used for this request only.
jacksRequest.on(<String> eventName, <Function> callback)
Register a callback for an event on the request.
Available events
- timeout : when the request has been aborted due to a timeout
- abort : when the request has been aborted
- loadstart : XMLHttpRequest loadstart event
- loadend : XMLHttpRequest loadend event
- progress : XMLHttpRequest progress event
- upload-progress : XMLHttpRequest upload progress event
jacksRequest.abort()
Aborts the request.
jacksRequest.sync()
Switches the request to synchronous mode. By default it's asynchronous.
jacksRequest.timeout(<int> delay)
Defines a timeout for the request. After the delay (in ms) the request will be aborted.
jacksRequest.send(<Function> callback, <function> error)
Sends the request.
jacksRequest.sendAsBinary(<Function> callback, <function> error)
Sends the request as binary.
callback
The callback function takes JacksResponse object as parameter witch contains
{
status : <http status code>,
statusText : <http status text>,
responseText : <raw response body>,
response : <parsed response body. The parser is selected with Content-Type header. If no parser is found, will contain the raw response body>,
headers : <response headers>,
getHeader(name): <function to get one header. Delegates it to xhr>
}
error
The error function takes a JacksError as parameter with contains
{
url : <url called>
type : <error type>
}
Type will be
- "timeout" if request has been interrupted after a timeout
- "abort" if request has been aborted