---

Classes

• i$

---

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$.global Refers to the global namespace, by default the window object.
<static>	i$.isChrome Value indicating the version of Chrome being used; undefined otherwise.
<static>	i$.isFF Value indicating the version of Firefox being used; undefined otherwise.
<static>	i$.isIE Value indicating the version of Internet Explorer being used; undefined otherwise.
<static>	i$.isOpera Value indicating the version of Opera being used; undefined otherwise.
<static>	i$.isSafari Value indicating the version of Safari being used; undefined otherwise.
<static>	i$.isWebKit Value indicating the version of WebKit being used; undefined otherwise.

Method Summary

Method Attributes	Method Name and Description
<static>	i$.addOnLoad(func, scope) Adds a function to call on page load
<static>	i$.addOnUnload(func, scope) Adds a function to call on page unload.
<static>	i$.augment(func, props) Like i$.mash but mashes properties into the function's prototype.
<static>	i$.cachedFn(func, scope) Wraps a function into a singleton-factory builder such that on the first function call, it calls the wrapped function and stores its return value then returns it.
<static>	i$.each(obj, func, scope) Enumerates over all properties of obj if obj is an object, or all items in obj if it is an array or is like an array (see i$.isLikeArray), calling function func in optional scope (defaulting to the global scope) for each enumerated value.
<static>	i$.every(arr, func, scope) Tests whether all elements in the array pass the test implemented by the provided function.
<static>	i$.fromPath(namepath, create, scope) Gets whatever value is resolved by the dot-delimited namepath in the property chain of the scope object, which defaults to the global scope if none is provided.
<static>	i$.isArray(obj) Determines if an object is an array or not.
<static>	i$.isBoolean(obj) Determines if an object is a boolean or not.
<static>	i$.isFunction(obj) Determines if an object is a function or not.
<static>	i$.isLikeArray(obj) Determines if an object is array like or not.
<static>	i$.isNode(obj) Determines if an object is a DOM node or not.
<static>	i$.isNumber(obj) Determines if an object is a number or not.
<static>	i$.isObject(obj) Determines if an object is an object or not.
<static>	i$.isRTL(locale) Determines whether a certain locale is a right to left language.
<static>	i$.isString(obj) Determines if an object is a string or not.
<static>	i$.make(proto, props) Creates and returns a new object whose prototype is the proto argument.
<static>	i$.mash(obj, props) Enumerates over arguments, mashing all the native properties of each argument object into the first argument object, returning the first.
<static>	i$.mashSpec(names, obj, props) Like i$.mash but only mashes properties whose names are in the names array first argument.
<static>	i$.merge(obj, target, path) Merges a value object's properties into the target object.
<static>	i$.partial(func, args) Generates a partial function based on an existing function.
<static>	i$.scope(obj, func, args) Generates a partial function based on an existing function but fixes the scope in which the partial function is called regardless of the eventual calling scope.
<static>	i$.shadow(source, target, names, overwrite) Creates shadowing functions on target that call the underlying functions on the shadowed source referred to by source.
<static>	i$.some(arr, func, scope) Tests whether some element in the array passes the test implemented by the provided function.
<static>	i$.toArray(obj) Returns a true array from obj, creating a copy if obj is already an array.
<static>	i$.toPath(namepath, value, scope) Sets a value to the dot-delimited path namepath in the property chain of the scope object, which defaults to the global scope if none is provided.
<static>	i$.trim(str) The trim function removes all newlines, spaces (including non-breaking spaces), and tabs from the beginning and end of the supplied string.
<static>	i$.unwrap(obj, name) Unwraps a previously wrapped function at obj[name] from i$.wrap to its original form and resets it back.
<static>	i$.wrap(obj, name, func) Provides light-weight AOP-style programming with around advice semantics.

---

---

---

---

---

---

Parameters:

{Function|String} func

The function to call, either a function or name of a function on scope object. Must not be null

{Object} scope Optional, Default: i$.global

The scope in which to call the function, i.e. the 'this' keyword within the function represents the scope object

---

Parameters:

{Function|String} func

The function to call, either a function or name of a function on scope object. Must not be null.

{Object} scope Optional, Default: i$.global

The scope in which to call the function

---

var visuals = {
    color: "white"
};
var structural = {
    make: "sedan"
};
i$.augment(Car, visuals, structural);

is functionally equivalent to:

Car.prototype.color = "white";
Car.prototype.make = "sedan";

Parameters:

{Function} func

Function whose prototype should be augmented. Must not be null.

{Object} props

Objects to mash properties into the prototype. Must not be null.

Returns:

{Function} Returns func again which has been passed into the augment function

---

var singleton = i$.cachedFn(function() {
    alert("hello");
    return true;
});
singleton(); // alerts "hello"
singleton(); // does not alert anything, just returns true

Parameters:

{Function} func

the function to be called the first time. Must not be null.

{Object} scope Optional

Object optional scope to call func in

Returns:

{Function} Returns the singleton factory function. Never null.

---

Parameters:

{Object|Array} obj

Object or Array to enumerate. Must not be null

{Function} func

Function with signature function(value, index|propName, originalObject) to call for each property or index. Must not be null

{Object} scope Optional, Default: i$.global

Object optional scope to call func in

---

Parameters:

{Array|ArrayLike} arr

Array to search; may simply be like an array. Must not be null.

{Function} func

Function with signature function(value) to call for each property or index. Must not be null.

{Object} scope Optional, Default: i$.global

Object optional scope to call func in

Returns:

{Boolean} Returns true if calling function func on each of the items in arr never returns false; false otherwise.

---

Example 1:

var obj = i$.fromPath("com.ibm.theme.feature");
alert(obj); // alerts "null"

Example 2:

var obj = i$.fromPath("com.ibm.theme.feature", true);
alert(obj===com.ibm.theme.feature); // alerts "true"

Example 3:

var obj1 = i$.fromPath("com.ibm.theme", true);
var obj2 = i$.fromPath("feature", true, obj1);
alert(obj2===com.ibm.theme.feature); // alerts "true"

Parameters:

{String} namepath

String with dot-delimited segments that refer to a name path to an object. Must not be null.

{Boolean} create Optional, Default: false

Boolean value that instructs the function to create the name path if it does not exist completely.

{Object} scope Optional, Default: i$.global

Object to begin the lookup for the name path resolution.

Returns:

{Object} the path object or null.

---

Parameters:

{Object} obj

Object to be tested. Must not be null.

Returns:

{Boolean} Returns true if obj is an array, false otherwise.

---

Parameters:

{Object} obj

Object to be tested. Must not be null.

Returns:

{Boolean} Returns true if obj is a boolean, false otherwise.

---

Parameters:

{Object} obj

Object to be tested. Must not be null.

Returns:

{Boolean} Returns true if obj is a function, false otherwise.

---

Parameters:

{Object} obj

Object to be tested. Must not be null.

Returns:

{Boolean} Returns true if obj is like an array, namely that it at least has a length property of type number; false otherwise.

---

Parameters:

{Object} obj

Object to be tested. Must not be null.

Returns:

{Boolean} Returns true if obj is a DOM node, false otherwise.

---

Parameters:

{Object} obj

Object to be tested. Must not be null.

Returns:

{Boolean} Returns true if obj is a number, false otherwise.

---

Parameters:

{Object} obj

Object to be tested. Must not be null.

Returns:

{Boolean} Returns true if obj is an object, false otherwise.

---

Parameters:

{String} locale

The locale to be tested. Must not be null.

Returns:

{Boolean} Returns true if locale is right to left, false otherwise.

---

Parameters:

{Object} obj

Object to be tested. Must not be null.

Returns:

{Boolean} Returns true if obj is a string, false otherwise.

---

Parameters:

{Object} proto

Object to use as the prototype of the returned object. Must not be null.

{Object} props

Objects to mash properties into the prototype. Must not be null.

Returns:

{Object} A new object. Never null.

---

var bag1 = {
    prop1: "value", 
    prop2: "Pass"
};
var bag2 = {
    prop2: 15
};
i$.mash(stash, bag1, bag2);

is functionally equivalent to:

stash.prop1 = "value";
stash.prop2 = "Pass";
stash.prop2 = 15;

Parameters:

{Object} obj

Target object to get new property values from subsequent arguments. Must not be null.

{Object} props

Objects to mash properties into the prototype. Must not be null.

Returns:

{Function} Returns obj again which has been passed into the mash function

---

Parameters:

{String[]} names

An array of property names to mash. Must not be null.

{Object} obj

Target object to get new property values from subsequent arguments. Must not be null.

{Object} props

Objects to mash properties from. Must not be null.

Returns:

{Function} Returns obj again which has been passed into the mashSpec function

---

Example 1:

var visuals = {
    color: "white"
};
var structural = {
    make: "sedan"
};
var car = {};
i$.merge(visuals, car);
i$.merge(structural, car);

Result:
car = {
    color: "white",
    make: "sedan"
};

Example 2:

var car = ["4 doors"];
i$.merge(["white","sedan"], car);

Result:
car = ["4 doors", "white", "sedan"]

Parameters:

{Object|Array} obj

Either object or array/array-like object to merge into the target object. Must not be null.

{Object|Array} target Optional, Default: i$.global

The target object or array

path

Returns:

{Object|Array} Returns the merged object target. Same type as the target object that was passed in.

---

Example 1
var f = i$.partial(function(a, b, c){ 
    alert(a + " - " + b + " - " + c);
}, 1, 5); // fixes the first 2 parameters a and b
f(10); // alerts "1 - 5 - 10"

Example 2
var f = i$.partial(function(a, b, c){ 
    alert(a + " - " + b + " - " + c);
}, 1, undefined, 5); // fixes parameter a and c, and marks b as a placeholder
f(3); // alerts "1 - 3 - 5"

Example 3
var f = i$.partial(function(a, b, c){ 
    alert(a + " - " + b + " - " + c);
}, undefined, 10); // fixes parameter b
f(1, 100); // alerts "1 - 10 - 100"

Parameters:

{Function} func

Function to create a partial from. Must not be null.

{Mixed} args Optional

Values to set at fixed positions in the calling context's actual arguments.

Returns:

{Function} A new partial function based on f. Never null.

---

Example 1:
var obj = {a: 1};
var f = i$.scope(obj, function(b, c){ 
    alert(this.a + " - " + b + " - " + c); 
});
f(3, 5); // alerts "1 - 3 - 5"

Example 2:
var obj = {a: 1};
var f = i$.scope(obj, function(b, c){ 
    alert(this.a + " - " + b + " - " + c); 
}, undefined, 5);
f(3); // alerts "1 - 3 - 5"

Parameters:

{Object} obj

Object to scope the function to so that the returned function always calls func in context of this scope object. Must not be null.

{Function} func

Function to scope. Must not be null.

{Mixed} args Optional

Arguments with same semantics as i$.partial

Returns:

{Function} A new function like i$.partial but fixes the function's scope permanently. Calling this without additional arguments besides obj and func simply creates a new function of the same arity whose scope is fixed to obj.

See:

i$.partial

---

Example 1:

var source = {
    say: function(){ 
        alert("I am " + this.name); 
    }, 
    name: "Sam" 
};
var target = {
    name: "Mouse"
};
i$.shadow(source, target, ["say"]);	// creates a "say" function on target
target.say(); // alerts "I am Mouse"
source.say = function(){ alert(this.name + " I am"); };
target.say(); // alerts "Mouse I am"

Example 2:

var target = {
    name: "Mouse", 
    sourceProp: {
         say: function(){ 
             alert("I am " + this.name); 
         },
         name: "Sam" 
    }
};
i$.shadow("sourceProp", target, ["say"]);	// creates a "say" function on target
target.say(); // alerts "I am Mouse"
target.sourceProp.say = function(){ alert(this.name + " I am"); };
target.say(); // alerts "Mouse I am"

Parameters:

{String|Object} source

String|Object refers to the source to delegate functions to. If it is a string, it refers to the name of the property on the scope of the function's execution context. If it is an object, it is accessed directly as a property on that object.

{Object} target

Object the target to create new functions on which shadow functions on the source.

{Array} names

Array of string names to create function properties for.

{Boolean} overwrite Optional, Default: false

Boolean property to specify whether or not the shadowing process should overwrite existing functions on the target with the same name.

---

Parameters:

{Array|ArrayLike} arr

Array to search; may simply be like an array. Must not be null.

{Function} func

Function with signature function(value) to call for each property or index. Must not be null.

{Object} scope Optional, Default: i$.global

Object optional scope to call func in

Returns:

{Boolean} Returns true if calling function func on each of the items in arr ever returns true; false otherwise.

---

Parameters:

{Object|Array} obj

Array or array-like object to convert into a new array. Must not be null.

Returns:

{Array} A new array. Never null.

---

Example 1:

i$.toPath("com.ibm.theme.feature", {
    say: function() {
        alert("hello");
    }
});
com.ibm.theme.feature.say(); // alerts "hello"

Example 2:

var ibm = i$.fromPath("com.ibm", true);
i$.toPath("theme.feature", {
    say: function() {
        alert("hello");
    }
}, ibm);
com.ibm.theme.feature.say(); // alerts "hello"

Parameters:

{String} namepath

String with dot-delimited parts that refer to a name path to an object. Must not be null. Any null or undefined segments in the path will be initialized to empty objects.

{Mixed} value

Any value to set at the last part of the objects resolved by the name path. Must not be null.

{Object} scope Optional, Default: i$.global

Object to begin the lookup for the name path resolution.

Returns:

{Mixed} the passed in value.

---

Parameters:

{String} str

String to be trimmed. Must not be null.

Returns:

{String} The trimmed string

---

Parameters:

{Object} obj

object to unwrap a function property on. Must not be null.

{String} name

name of the object property that references a function to unwrap. Must not be null.

Returns:

{Function} the unwrapped function or if no unwrapping possible, the original function again. Never null.

---

Example:
var car = {
    drive: function(){
        console.log("Driving");
    }
};
i$.wrap(car, "drive", function(originalFn, args) {
    if(!isIcy) {
        return originalFn.apply(this, args);
    }
    else {
        console.warn("It is too icy!");
    }
});

Parameters:

{Object} obj

object to wrap a function property on. Must not be null.

{String} name

name of the object property that references a function to wrap. Must not be null.

{Function} func

function to replace the original with that has the signature function(originalFn, args). Must not be null.

Returns:

{Function} the wrapped function. Never null.

---