ish.js API Doc (alpha)

The ish namespace

A jQuery'ish set of utility methods. There is very few methods available under this namespace, the ish('selector') will by far be the most commonly used method. You'll also find an extends method and an optional AJAX utility.

Example
(function($){
	// now you can use the $ sign in place of ish just as you would using jQuery.
	// Let's start by grabbing a reference to a DOM node with the selector engine
	var $element = $('selector');
	// now we'll add the attribute 'data-ish' with a property of 'true'
	$element.attr('data-ish','true');

	var obj1 = {a:'a'};
	var obj2 = {a:'new a', b:'b'};
	$.extend(obj1,obj2);
})(ish);

Properties

fn

line 80

An object which stores prototype objects.

Methods

ajax(options)

line 1
Description:

Make an XHR request. The implementation is currently very basic, the response is not parsed as JSON or converted to a String, you will have to do that to the response manually when it's returned.

Returns
ish

Returns the XMLHttpRequest Object.

Parameters:
Name Type Description
options Object
Properties
Name Type Description
type String

Acceptable values are; 'GET','POST','PUT','DELETE'.
url String

The url of the request.
success function

A callback function triggered when the ajax call is successful. The responseText is passed as the first parameter of the function, other values are availiable from the XMLHttpRequest Object returned from this component.
error function

A callback function triggered if the ajax call is unsuccessful.
data Object

A custom data object to pass with the request.
headers Object

An Object with String key values representing the header and its values. You can add custom header values here.

Properties
Name Type Description
Accept String

By default the Accept header is ommited although it is a common one to set so it gains a mention here. Common values are: "text/plain", "text/html", "application/xml, text/xml", "application/json, text/javascript"
Content-Type String

Default value is 'application/x-www-form-urlencoded' other values often used are: 'text/plain', 'multipart/form-data', 'application/json' or 'text/xml'.
X-Requested-With String

Default value is 'XMLHttpRequest'.
Example:
var reqSuccess = function(data){
	//success
	console.log('success', data, req);
};
var reqError = function(statusText, status){
	//error
	console.log('There was an error. '+status+' : '+statusText, req);
};

var req = ish.ajax({
	type:'JSON',
	url: 'http://domain.com/ajaxhandler',
	success: reqSuccess,
	error: reqError,
	data: {"JSON":"data"}
});

bindToObject(domNode, dataObject)

line 75
Description:

Whilst the ish.renderBind method renders values to the DOM, ish.bindToObject sets the values of the binds DOM attributes in the target object.

Returns
ish

Chainable with other ish methods.

Parameters:
Name Type Description
domNode String

An exisiting DOM Node.
dataObject Object

An object whose values will be bound to the rendered HTML.
Example:
var template = '<p ish-bind="textContent:text"></p>'
var node = ish.renderTemplate(template, {text:'text has been rendered'});
// you would usualy use ish.updateTemplate, this is just for exmaple
ish.renderBind(node, {text: 'text has been updated text'});

ish(selector, context, forceSelector)

line 9
Description:

Simple selector engine based on querySelectorAll. The usage and result is similar to jQuery(selector).

Returns
ishObject

A list of nodes with inherited library methods.

Parameters:
Name Type Description
selector String | Node

A CSS Selector compatible with document.querySelectorAll or a single Node.
context ishObject | Array | NodeList | Node

Used to give a selector a search context.
forceSelector String

Set the ish('selector').selector paramter forcibly.
Example:
ish('selector');
//filter the collection with some context of type Node || NodeList
ish('selector', Node);
ish('selector', NodeList);

renderBind(domNode, dataObject)

line 49
Description:

Render the values given in the dataObject to a single node.

Returns
Node

The rendered HTML template Node which can be inserted into the DOM.

Parameters:
Name Type Description
domNode String

An exisiting DOM Node.
dataObject Object

An object whose values will be bound to the rendered HTML.
Example:
var template = '<p ish-bind="textContent:text"></p>'
var node = ish.renderTemplate(template, {text:'text has been rendered'});
// you would usualy use ish.updateTemplate, this is just for exmaple
ish.renderBind(node, {text: 'text has been updated text'});

renderTemplate(templateString, dataObject)

line 4
Description:

Render a template string with corresponding object data.

Returns
Node

The rendered HTML template Node which can be inserted into the DOM.

Parameters:
Name Type Description
templateString String

A valid HTML template string.
dataObject Object

An object whose values will be bound to the rendered HTML.
Example:
var template = '<div><p ish-bind="textContent:text"></p></div>'

ish.renderTemplate(template, {text: 'Text has been rendered.'});

resolveObjectPath(object, pathString)

line 1
Description:

Resolves an Object path given in String format within the given Object.

Returns
Object

The resolved value.

Parameters:
Name Type Description
object Object

The object which contains the value you're attempting to resolve.
pathString String

The path of the value which you are attempting to resolve.
Example:
var object = {
    nested: {
        value : 'a nested value',
        array: [1,2,'third',4,5]
    }
};

var value = ish.resolveObjectPath(object, 'nested.value'); // 'a nested value'
var arrayValue = ish.resolveObjectPath(object, 'nested.array[3]'); // 'third'

setPathByString(object, pathString, value)

line 36
Description:

Sets an the value of an Object path given in String format within the given Object.

Returns
Object

The resolved value.

Parameters:
Name Type Description
object Object

The object which contains the value you're attempting to set.
pathString String

The path of the value which you are attempting to set.
value value

The value you're attempting to set.
Example:
var object = { 
    nested: { 
        value : 'a nested value',
        array: [1,2,'third',4,5]
    }
};

var value = ish.resolveObjectPath(object, 'nested.value'); // 'a nested value'
var arrayValue = ish.resolveObjectPath(object, 'nested.array[3]'); // 'third'

updateTemplate(updateNode, updateObject)

line 27
Description:

Update a template Node with a corresponding object data.

Returns
ish
Parameters:
Name Type Description
updateNode Node

The node to update, all child Node's will be updated.
updateObject Object

An object whose values will be updated in the provided HTML.
Example:
var template = '<div><p ish-bind="textContent:text"></p></div>';
var renderedTemplate = ish.renderTemplate();
ish.updateTemplate(renderedTemplate, {});

extend(object1, ,obectj2opt)

line 209
Description:

Accepts a series objects, merging the second parameter into the first recursively, if more than two objects are supplied the other objects are merged into the first in the order given.

Returns
Object

A merged Object.

Parameters:
Name Type Attributes Description
object1 Object

An Object that will have values of object2 recursively merged.
,obectj2 Object <optional>

A series of Objects to merge into object1.
Example:
var obj1 = {a:'a',b:{ba:'ba',bb:'bb',bc:{bca:'bca'}},c:[1,2,3]};
var obj2 = {d:'d',b:{ba:'ba-change',bc:{bcb:'added'}},c:[4,5,6]};
ish.extend(obj1,obj2);