---

Classes

• i$
• i$.modules
• i$.promise
• i$.promise.Promise

---

Namespace i$

The global namespace of the IBM Client API

Namespace Summary

Constructor Attributes	Constructor Name and Description
	i$ The global namespace of the IBM Client API

Field Summary

Field Attributes	Field Name and Description
<static>	i$.onLoadPromise Defines a promise which is resolved when the page has finished loading, more specifically when the browser issues the onload event.

Method Summary

Method Attributes	Method Name and Description
<static>	i$.addClass(node, className) Adds the specified class to the given DOM node.
<static>	i$.addListener(name, func) Registers a callback function for a given event name.
<static>	i$.addQueryString(an, obj) Adds a query string to a given URI.
<static>	i$.bindDomEvt(node, name, func) Binds a function to a DOM event such as 'onmouseleave'.
<static>	i$.byId(id) This is a simple alias to document.getElementById, which is shorter to write.
<static>	i$.createDom(name, attrs, parent) This method create a new DOM node with given attributes and adds it into the DOM at the same time if required
<static>	i$.deleteCookie(name, path, domain) Deletes a cookie.
<static>	i$.fireEvent(name, payload) Fires an event with a payload and sends it to all registered listeners of the given event name
<static>	i$.fromJson(str) Parses a JSON string to return a JavaScript object.
<static>	i$.fromQuery(query) Returns an associative map of type object with the parsed values of the given string.
<static>	i$.getCookie(name) Gets a cookie.
<static>	i$.hasClass(node, className) Determine whether the given DOM node is assigned the given class.
<static>	i$.isDescendant(node, ancestor) Determines whether the specified node is a descendant of the ancestor.
<static>	i$.loadScript(args) Loads JavaScript at some URL via a script tag in the head of the page allowing asynchronous handling of scripts that may be in the same domain as the current one or across domains.
<static>	i$.removeClass(node, className) Remove a single class from the given DOM node.
<static>	i$.removeListener(handle) Removes a listener from the given event name, based on previously received connection data.
<static>	i$.setCookie(name, value, expiry, path, domain, secure) Sets a cookie.
<static>	i$.toggleClass(node, className) Add or remove one class from the given DOM node.
<static>	i$.toJson(obj, pretty) Returns a JSON serialization of an object.
<static>	i$.toQuery(obj) Returns a query string serialization of an object, more specifically an associative map where names must be of type string.
<static>	i$.unbindDomEvt(binding) Unbinds a previously bound event.
<static>	i$.xhr(method, args) Sends an AJAX request.
<static>	i$.xhrDelete(args) Executes an XmlHttpRequest using the HTTP DELETE method using the same arguments as i$.xhr except with the first argument pre-filled.
<static>	i$.xhrGet(args) Executes an XmlHttpRequest using the HTTP GET method using the same arguments as i$.xhr except with the first argument pre-filled.
<static>	i$.xhrPost(args) Executes an XmlHttpRequest using the HTTP POST method using the same arguments as i$.xhr except with the first argument pre-filled.
<static>	i$.xhrPut(args) Executes an XmlHttpRequest using the HTTP PUT method using the same arguments as i$.xhr except with the first argument pre-filled.

i$.onLoadPromise.then(function() {
   // this is called on load
});

Parameters:

{DOMNode} node

the DOM node to add the class on. Must not be null.

{String} className

One class name to be added to the class attribute. Must not be null.

---

Example 1:

i$.addListener("sport/baseball/catcher", 
    function(pitch1, pitch2, pitch3) {
        alert(pitch1+"/"+pitch2+"/"+pitch3); 
});
//pitching
i$.fireEvent("sport/baseball/catcher", 
   ["fastball", "curveball", "homerun"]); // alerts "fastball/curveball/homerun"

Example 2:

i$.addListener("sport/baseball/fielder", 
    function(hit1, hit2) {
        alert(hit1+"/"+hit2);
    });
i$.addListener("sport/baseball/fielder", 
    function(hit1, hit2) {
        alert(hit1+"/"+hit2);
    });
i$.fireEvent("sport/baseball/fielder", 
    ["slap", "homerun"]); // alerts "slap/homerun" twice

Parameters:

{String} name

name of the event. Must not be null.

{Function} func

Callback function to be called when the event is issued. Must not be null.

Returns:

{Object} Returns a connection object which must be used again to remove the listener i$.removeListener.

---

Example 1:


var str = i$.addQueryString("http://foo.bar", {
    "cat" : "chases",
    "mouse" : ["runs", "hides"]
});
alert(str); // alerts "http://foo.bar?cat=chases&mouse=runs&mouse=hides"

Example 2:

var str = i$.addQueryString("http://foo.bar?foo=baz", {
    "cat" : "chases",
    "mouse" : ["runs", "hides"]
});
alert(str); // alerts "http://foo.bar?foo=baz&cat=chases&mouse=runs&mouse=hides"

Parameters:

{String} an

URI with or without query string params. Must not be null

{Object} obj

The JavaScript object to serialize. Must not be null

Returns:

{String} an URI where the input URI and input query string has been appended

---

Parameters:

{DOMNode} node

node to bind the event on. Must not be null.

{String} name

name of the event to bind. Must not be null.

{Function} func

Callback function to be called when the event is issued. Must not be null.

Returns:

{Object} Returns a connection object which must be used again to unbind the event i$.unbindDomEvt.

---

Parameters:

{String} id

The id of the DOM node to be returned. Must not be null.

---

Example 1: Creates a new div element which is not part of any DOM (yet).
var divElement = i$.createDom("div");

Example 2: Inserts a new input element into a 'form' with the attributes, type, name, value
i$.createDom("input", {
   "type": "hidden",
   "name": "x-method-override",
   "value": method.toUpperCase()
}, form);

Parameters:

{String} name

DOM node name, examples are "div", "a" and "span". Must not be null.

{Object} attrs Optional

associative map defining name and value to be set on the new DOM node.

{DOMNode} parent Optional

The parent DOM node under which the newly created node should be inserted. If this is not defined the DOM node will not be inserted into the DOM and must be added manually afterwards.

Returns:

{DOMNode} Returns the newly created DOM node. Never null.

---

Parameters:

{String} name

The name of the cookie to delete. Must not be null.

{String} path Optional

The path for the cookie (must be the same as the path used to create the cookie). Defaults to / (the entire site) if not specified.

{String} domain Optional

The domain of the cookie (must be the same as the domain used to create the cookie). Defaults to the domain of the calling document if not specified.

---

i$.addListener("sport/baseball/batter", 
    function(pitch) {
        alert("hitting "+pitch);
    });
//pitching
i$.fireEvent("sport/baseball/batter", ["fastball"])  // alerts "hitting fastball"
.then(function() {
    alert("event received");
});

Parameters:

{String} name

name of the event. Must not be null.

{Array} payload

The payload as array to be sent to all registered listeners.

Returns:

{i$.promise.Promise} TBD

---

Parameters:

{String} str

the JSON string. Must not be null

Returns:

{Object} An object with all values of the JSON string. Never null.

---

i$.fromQuery("cat=chases&mouse=runs&mouse=hides");
// returns an object with the following format:
// {
//     "cat" : "chases",
//     "mouse" : ["runs", "hides"]
// }

Parameters:

{String} query

The query string to parse. Must not be null

Returns:

{Object} The object representing the query string.

---

Parameters:

{String} name

The name of the cookie to get. Must not be null

Returns:

{String} A string that is the value of the cookie, or null if the cookie does not exist.

---

Parameters:

{DOMNode} node

the DOM node to test. Must not be null.

{String} className

the class name to test against. Must not be null.

Returns:

{Boolean} true if the DOM node has the given class name assigned, false otherwise

---

Parameters:

{DOMNode} node

node to test. Must not be null.

{DOMNode} ancestor

node of potential parent to test against. Must not be null.

Returns:

{Boolean} Returns true if the specified node is a descendant of the ancestor, false otherwise

---

Parameters:

{Object} args

A config object used to refine how the request is processed.

{String} args.url

url to which the request should be sent, required

{Function} args.callback Optional

Function to call when the request completes, with the following signature: function(success, data){}

{Number} args.timeout Optional

A timeout, if exceeded cancels the XHR and rejects the returned promise.

{Object} args.scriptAttrs Optional

map of attributes to add to the script

Returns:

{i$.promise.Promise} A promise that resolves to a simple string 'responseData' on success or 'error' on failure. Chaining promises to this one should not change the structure of the resolved value in delegated promises unless their consumers aren't expecting the resolved value to be in the JSON structure produced by this i$.xhr API call. Modifying the value to implement filtering promise chains is properly done by modifying the resolved value's data property and returning either the resolved value again or an undefined value to ensure the consumers can safely assume the same JSON structure in their callbacks.

---

Parameters:

{DOMNode} node

the DOM node to remove the class from. Must not be null.

{String} className

One class name to be removed from the class attribute. Must not be null.

---

var handle = i$.addListener("sport/baseball/catcher",
    function(pitch1, pitch2, pitch3) {
        alert(pitch1+"/"+pitch2+"/"+pitch3);
});
//pitching
i$.fireEvent("sport/baseball/catcher", 
    ["fastball", "curveball", "homerun"]); // alerts "fastball/curveball/homerun"
i$.removeListener(handle);
i$.fireEvent("sport/baseball/catcher", 
    ["fastball", "curveball", "homerun"]); // no alert

Parameters:

{Object} handle

The connection handle returned from i$.addListener. Must not be null.

---

Parameters:

{String} name

The name of the cookie to set. Must not be null.

{String} value

The value to set into the cookie. Must not be null.

{Date} expiry Optional

The date that the cookie expires. Defaults to 100 years from now if not specified.

{String} path Optional

The path for which the cookie is valid. Defaults to / (the entire site) if not specified.

{String} domain Optional

The domain of the cookie. Defaults to the domain of the calling document if not specified.

{boolean} secure Optional

Whether to secure transmission of the cookie or not. Defaults to unsecure if not specified.

---

Parameters:

{DOMNode} node

the DOM node. Must not be null.

{String} className

One class name to be added or removed from the class attribute. Must not be null.

---

Parameters:

{Object} obj

The JavaScript object to serialize. Must not be null

{String} pretty Optional, Default: false

if true the string representation is pretty printed.

Returns:

{String} A JSON string representing the JavaScipt object.

---

Example 1:

var query = i$.toQuery({
    "cat" : "chases",
    "mouse" : "hides"
});
alert(query); // alerts "cat=chases&mouse=hides"

Example 2:

var query = i$.toQuery({
    "cat" : "chases",
    "mouse" : ["runs", "hides"]
});
alert(query); // alerts "cat=chases&mouse=runs&mouse=hides"

Parameters:

{Object} obj

The JavaScript object to serialize. Must not be null

Returns:

{String} A query string representing the object.

---

Parameters:

{Object} binding

the connection object which was returned from the i$.bindDomEvt. Must not be null.

---

Parameters:

{String} method Optional, Default: "get"

HTTP method such as "get or "post", default = "get"

{Object} args

A config object used to refine how the request is processed.

{String} args.url

url to which the request should be sent, required

{String} args.sync Optional, Default: false

HTTP method such as "get or "post", default = "get"

{Function} args.callback Optional

Function to call when the request completes, with the following signature: function(responseBody, httpStatus, statusText){}

{Object} args.headers Optional

an associative map of strings defining the headers of this xhr.

{String} args.postData Optional

a string of data you wish to send as the post body.

{String} args.responseType Optional, Default: "text"

Response type choices are "xml" or "json", default is "text".

{Integer} args.timeout Optional

The timeout in milliseconds before rejecting the promise and calling the error function. The data parameter is set to "timeout" in this case.

Returns:

{i$.promise.Promise} A promise that resolves to {data: responseData, xhr: xhr} on success or {data: error, xhr: xhr} on failure. Chaining promises to this one should not change the structure of the resolved value in delegated promises unless their consumers aren't expecting the resolved value to be in the JSON structure produced by this i$.xhr API call. Modifying the value to implement filtering promise chains is properly done by modifying the resolved value's data property and returning either the resolved value again or an undefined value to ensure the consumers can safely assume the same JSON structure in their callbacks.

---

Parameters:

{Object} args

For description see i$.xhr

Returns:

{i$.promise.Promise} For description see i$.xhr

See:

i$.xhr

---

Parameters:

{Object} args

For description see i$.xhr

Returns:

{i$.promise.Promise} For description see i$.xhr

See:

i$.xhr

---

Parameters:

{Object} args

For description see i$.xhr

Returns:

{i$.promise.Promise} For description see i$.xhr

See:

i$.xhr

---

Parameters:

{Object} args

For description see i$.xhr

Returns:

{i$.promise.Promise} For description see i$.xhr

See:

i$.xhr

---