My Library API Reference

This is the reference for the functional API, which is the only interface used by the Build Test and Examples pages. There is also an object-oriented interface built on top of the API. See the Object Reference for details.

Note the Table of Contents contains links to functions and objects, organized by module; however, the entries that follow are organized alphabetically. This incongruity, which is an issue inherited from the original documentation, will be addressed in a future revision (likely by breaking up the content into multiple documents).

$

Feature Detection

Immediate

The global $ variable is an alias for getEBCS.

Syntax

a = $(selector[, node]);

Examples

divs = $('div div div');
divs = $('div.myclass');
divs = $('#myid div');
divs = $('div + div#myid');
divs = $('div ~ div#myid');
links = $('a[href]');
homelinks = $('a[rel~=home]');
stylesheets = $('a[rel~=stylesheet]');
alternatestylesheets = $('link[rel~=stylesheet][rel~=alternate]');

Return Value

The function returns an array of elements.

API

The global API variable is an object that encapsulates all library functions.

absoluteElement

Feature Detection

Deferred

The absoluteElement function positions an element absolutely, preserving its position and size.

Syntax

absoluteElement(el);

Examples

API.absoluteElement(el);

addBookmark

Feature Detection

Immediate

The addBookmark function calls on the browser to display its bookmarking (AKA favorites) dialog with the supplied location and title.

Syntax

addBookmark(href, title[, win]);

Examples

API.addBookmark('http://www.hartkelaw.net', 'Hartke Law Firm');

addBookmarkCurrent

Feature Detection

Immediate

The addBookmarkCurrent function calls on the browser to display its bookmarking (AKA favorites) dialog with the current location and title.

Syntax

addBookmarkCurrent([win]);

Examples

API.addBookmarkCurrent();

addClass

See Also

Feature Detection

Immediate

The addClass function adds a CSS class to an element.

Syntax

addClass(el, className);

Examples

API.addClass(el, 'sidebar');

addElementHtml

See Also

Feature Detection

Deferred

The addElementHtml function adds HTML to an element, preserving listeners attached to the existing nodes.

Syntax

addElementHtml(el, html);

Examples

API.addElementHtml(el, '<p>And the first guy says...</p>');

addElementScript

See Also

Feature Detection

Deferred

The addElementScript function adds script to a script element.

Syntax

addElementScript(el, script);

Examples

API.addElementScript(el, 'window.alert("Hello world!")');

addElementNodes

See Also

Feature Detection

Deferred

The addElementNodes function adds nodes to an element.

Syntax

addElementNodes(el, elNewNodes);

Examples

API.setElementHtml(elNew, '<p>Why would I exchange it?</p><p>It's the perfect colour!</p>');
API.addElementNodes(elDiv, elNew);

addElementText

See Also

Feature Detection

Immediate

The addElementText function adds text to an element.

Syntax

addElementText(el, text);

Examples

API.addElementText(el, 'Burma-Shave');

addOption

See Also

Feature Detection

Immediate

The addOption function adds an option to a select element.

Syntax

addOption(el, text[, value]);

Examples

API.addOption(el, 'Apples');
API.addOption(el, 'Apples', 'apples');
elOption = API.addOption(el, 'oranges');

Return Value

The function returns the new option.

addOptions

See Also

Feature Detection

Immediate

The addOptions function adds one or more options to a select element.

Syntax

opt = addOption(el, options);

Examples

API.addOptions(el, { apples:'Apples', oranges:'Oranges' });

addScript

Feature Detection

Deferred

The addScript function adds script to a document.

Syntax

addScript(text[, docNode]);

Examples

API.addScript('window.alert("Hello World!")');
API.addScript('window.alert("Hello Yourself!")', doc);

addStyleRule

See Also

Feature Detection

Immediate

The addStyleRule function adds a CSS rule to a document. It is typically used to hide content during the page load, after which the content is enhanced and/or made visible, depending on the available features of the environment.

Note that the canAdjustStyle function should be consulted before hiding content in this way.

Syntax

addStyleRule(selector, rule[, media[, docNode]]);

Examples

API.addStyleRule('.banner { display:none }', 'handheld');
API.addStyleRule('.flash { visibility:hidden }');
API.addStyleRule('.flash { visibility:hidden }', 'all', doc);

adjacentElement

See Also

Feature Detection

Deferred

The adjacentElement function positions an element adjacent to another.

Syntax

adjacentElement(el, elAdjacent[, side]);

Examples

API.adjacentElement(elMenu, elParentMenu, 'right');

applyDirectXTransitionFilter

See Also

Feature Detection

Deferred

The applyDirectXTransitionFilter function applies a DirectX transition.

Syntax

applyDirectXTransitionFilter(el, name[,duration[, params]]);

Examples

API.applyDirectXTransitionFilter(el, 'fade', 1000);
API.applyDirectXTransitionFilter(el, 'iris', { irisstyle:'STAR' });

areFeatures

Feature Detection

Immediate

The areFeatures function is used to test features of the API. This allows application to degrade gracefully in older, buggy or otherwise limited environments.

Syntax

b = areFeatures(feature1[, feature2, ... feature n]);

Examples

canRunApp = API.areFeatures('getEBI', 'getOpacity', 'setScrollPosition');

attachContextClickListener

See Also

Feature Detection

Immediate

The attachContextClickListener function adds a listener to an element for two events (contextmenu and mouseup), calling the specified function once per click of the context button.

Syntax

attachContextClickListener(el, fn[, context]);

Examples

API.attachContextClickListener(el, function() { window.alert('Do not do this!'); });
API.attachContextClickListener(el, function() { this.log('context'); }, clickHistory);

attachDocumentListener

See Also

Feature Detection

Immediate

The attachDocumentListener function adds an event listener to a document.

Syntax

attachDocumentListener(ev, fn[, docNode[, context]]);

Examples

API.attachDocumentListener('click', function() { window.alert('Hello again!'); });
API.attachDocumentListener('click', function() { window.alert('Hello from another document'); }, doc);
API.attachDocumentListener('click', function() { this.doSomethingElse(); }, doc, someObject);

attachDocumentReadyListener

See Also

Feature Detection

Immediate

The attachDocumentReadyListener function adds a DOMContentLoaded listener to a document and a load listener to the document's window, calling the specified function once when the document is ready for programmatic manipulation. The load event is used as a fallback for browsers that do not support the DOMContentLoaded event (e.g. Internet Explorer, Safari.) As the load event is not fired until all document assets (e.g. images, Flash movies) are fully loaded, it is usually preferable to call the documentReady function from a script at the end of the body element. The Document Ready add-on serves this purpose.

Note that some features of the library are not available until the document is ready (e.g. DirectX.) Code that utilizes these features should be wrapped in a function that is passed to attachDocumentReadyListener.

Syntax

attachDocumentReadyListener(fn[, docNode]);

Examples

API.attachDocumentReadyListener(function() { window.alert('Ready!'); });
API.attachDocumentReadyListener(function() { window.alert('Me too!'); }, doc);
if (!API.attachDocumentReadyListener(function() { window.alert('Me too!'); }, doc)) {
  window.alert('No idea when that document will be ready');
}

Return Value

The function returns a boolean indicating whether the operation was successful.

attachDrag

See Also

Feature Detection

Deferred

The attachDrag function enables an element to be dragged.

Syntax

attachDrag(el[, elHandle[, options]]);

Examples

API.attachDrag(el);
API.attachDrag(el, elHandle);
API.attachDrag(el, elHandle, { ondrop: function() { window.alert('Dropped!' } });

attachHelpListener

See Also

Feature Detection

Immediate

The attachHelpListener function adds a listener to an element for two events (help and keydown), calling the specified function once per press of the help key.

Syntax

attachHelpListener(el, fn[, context]);

Examples

API.attachHelpListener(el, function() { window.alert('Help!'); });
API.attachHelpListener(el, function() { this.showHelp(); }, helpObject);

attachListener

See Also

Feature Detection

Immediate

The attachListener function adds an event listener to an element.

Syntax

attachListener(el, ev, fn[, context]);

Examples

API.attachListener(el, 'click', function() { window.alert('Clicked!'); });
API.attachListener(el, 'click', function(e) { this.onclick(e); }, someObject);

attachMousewheelListener

See Also

Feature Detection

Immediate

The attachMousewheelListener function adds a listener for two events (mousewheel and dommousescroll), calling the specified function once per mousewheel movement. In addition to passing the standard event parameter, a second argument indicates the direction and distance of the movement.

Syntax

attachMousewheelListener(el, fn[, context]);

Examples

API.attachMousewheelListener(el, function(e, delta) { window.status = delta; });
API.attachMousewheelListener(el, function(e, delta) { this.onmousewheel(e, delta); }, someObject);

attachRolloverListeners

See Also

Feature Detection

Immediate

The attachRolloverListeners function adds listeners to an element for two events (mouseover and mouseout), calling each of the two passed functions as appropriate. Optionally, it adds the listeners for the focus and blur events. Another option allows for the automatic display of the element's title in the status bar (requires Status Bar module.)

Syntax

attachRolloverListeners(el, fnOver, fnOut[, context[, bAddFocusListeners[, bSetStatus]]]);

Examples

API.attachRolloverListeners(el, function() { window.status = 'over'; }, function() { window.status = 'and out'; } );
API.attachRolloverListeners(el, function(e) { this.onover(e); }, function(e) { this.onout(e); }, someObject);

attachWindowListener

See Also

Feature Detection

Immediate

The attachWindowListener function adds an event listener to a window.

Syntax

attachWindowListener(ev, fn[, win[, context]]);

Examples

API.attachWindowListener('resize', function() { window.status = 'Resized'; });
API.attachWindowListener('scroll', function(e) { this.onscroll(e); }, win, someObject);

canAdjustStyle

See Also

Feature Detection

Immediate

The canAdjustStyle function tests if the specified style (display, position or visibility) can be changed programmatically.

Syntax

b = canAdjustStyle(style);

Examples

if (API.canAdjustStyle('visibility') && API.canAdjustStyle('display')) {
  enhanceDocument();
}

Return Value

The function returns a boolean.

cancelDefault

See Also

Feature Detection

Immediate

The cancelDefault function prevents the default action of an event.

Syntax

cancelDefault(e);

Examples

API.cancelDefault(e);
return API.cancelDefault(e); // Compatible with DOM0

cancelPropagation

See Also

Feature Detection

Immediate

The cancelPropagation function prevents the bubbling of an event.

Syntax

cancelPropagation(e);

Examples

API.cancelPropagation(e);

centerElement

Feature Detection

Deferred

The centerElement function centers an element in the viewport.

Syntax

centerElement(el[, options[, callback]]);

Examples

API.centerElement(el);
API.centerElement(el, { duration:1000, ease:API.ease.circle });
API.centerElement(el, { duration:1000, ease:API.ease.circle }, fn);

Note that like showElement, sizeElement, positionElement, maximizeElement, restoreElement, setElementHtml and setElementNodes this function has an async property, which determines whether a callback is supported. This is used by the test page as it has to deal with any build, but is not needed for normal applications as the signature is known at build time, in this case depending on whether FX is included.

changeImage

See Also

Feature Detection

Hybrid

The changeImage function changes the source of an image. The source may be specified by an image location or the handle of a preloaded image. The optional parameters are for use with effects modules (e.g. DirectX), which replace the standard function with one that supports progressively rendered changeovers.

Syntax

changeImage(el, src[, options[, callback]]);

Examples

API.changeImage(el, 'http://www.cinsoft.net/images/cinsoft.gif');
API.changeImage(el, 'http://www.cinsoft.net/images/cinsoft.gif', { effects: API.effects.fade, duration:1000, ease:API.ease.circle });
API.changeImage(el, 'http://www.cinsoft.net/images/cinsoft.gif', { effects: [API.effects.fade, API.effects.grow], duration:1000, ease:API.ease.circle });

clonePreloadedImage

See Also

Feature Detection

Immediate

The clonePreloadedImage function creates an image element from a preloaded image.

Syntax

el = clonePreloadedImage(handle);

Examples

handle = API.preloadImage('http://www.cinsoft.net/images/cinsoft.gif', 100, 100);
img = API.clonePreloadedImage(handle);

Return Value

The function returns an image element.

cookiesEnabled

See Also

Feature Detection

Immediate

The cookiesEnabled function tests if cookies are enabled.

Syntax

b = cookiesEnabled();

Examples

var b = API.cookiesEnabled();

Return Value

The function returns a boolean.

coverDocument

Feature Detection

Deferred

The coverDocument function sizes and positions an element to cover the document.

Syntax

coverDocument(el);

Examples

API.coverDocument(el);

createElement

See Also

Feature Detection

Immediate

The createElement function creates an (X)HTML element.

Syntax

el = createElement(tag[, docNode]);

Examples

el = API.createElement('div');
el = API.createElement('div', doc);

Return Value

The function returns an element.

createElementWithAttributes

See Also

Feature Detection

Immediate

The createElementWithAttributes function creates an (X)HTML element and sets one or more attributes.

Syntax

el = createElementWithAttributes(tag, attributes[, docNode]);

Examples

el = API.createElementWithAttributes('div', { id:'me', 'class':'hello' });
el = API.createElementWithAttributes('div', { id:'you', 'class':'hello' }, doc);

Return Value

The function returns an element.

createElementWithProperties

See Also

Feature Detection

Immediate

The createElementWithProperties function creates an (X)HTML element and sets one or more properties.

Syntax

el = createElementWithProperties(tag, properties[, docNode]);

Examples

el = API.createElementWithProperties('input', { type:'checkbox', checked:true });
el = API.createElementWithProperties('input', { type:'checkbox', checked:true }, doc);

Return Value

The function returns an element.

createFlash

See Also

Feature Detection

Immediate

The createFlash function creates a Flash movie, replacing the element with the specified id (if the required version of Flash is available). The Flash movie is not created until the document is ready. The fallback content is hidden during load (when possible).

Syntax

createFlash(uri, id[, options]);

Examples

var vars = new API.FlashVariables();
vars.addQuery('name1');
vars.addBookmark('name3');
vars.add('name1', 'Test 1');
vars.add('name2', 'Test 2');
vars.add('name3', 'Test 3');
API.createFlash('http://www.cinsoft.net/flash/testflash_vars.swf', 'flashFallback2', { height:120, width:300, variables:vars, versionRequired:6 });

createXmlHttpRequest

Feature Detection

Immediate

The createXmlHttpRequest creates an XHR object.

Syntax

xhr = createXmlHttpRequest();

Examples

xhr = API.createXmlHttpRequest();

Return Value

The function returns an XHR object.

deleteCookie

See Also

Feature Detection

Immediate

The deleteCookie function deletes a cookie.

Syntax

deleteCookie(name[, path[, docNode]]);

Examples

API.deleteCookie('test');

deleteCookieCrumb

See Also

Feature Detection

Immediate

The deleteCookieCrumb function deletes a portion of a cookie.

Syntax

deleteCookieCrumb(name, crumb[, docNode]);

Examples

API.deleteCookieCrumb('test', 'testing');

detachContextClickListener

See Also

Feature Detection

Immediate

The detachContextClickListener function removes context click-related event listeners.

Syntax

detachContextClickListener(el);

Examples

API.detachContextClickListener(el);

detachHelpListener

See Also

Feature Detection

Immediate

The detachHelpListener function removes context help-related event listeners.

Syntax

detachHelpListener(el);

Examples

API.detachHelpListener(el);

detachListener

See Also

Feature Detection

Immediate

The detachListener function removes an event listener from an element.

Syntax

detachListener(el, ev, fn);

Examples

API.detachListener(el, 'click', fn);

detachDocumentListener

See Also

Feature Detection

Immediate

The detachDocumentListener function removes an event listener from a document.

Syntax

detachDocumentListener(ev, fn[, docNode]);

Examples

API.detachDocumentListener('click', fn);
API.detachDocumentListener('click', fn, doc);

detachDrag

See Also

Feature Detection

Deferred

The detachDrag function disables dragging for an element.

Syntax

detachDrag(el[, elHandle]);

Examples

API.detachDrag(el);
API.detachDrag(el, elHandle);

detachMousewheelListener

See Also

Feature Detection

Immediate

The detachMousewheelListener function removes mousewheel-related event listeners.

Syntax

detachMousewheelListener(el);

Examples

API.detachRolloverListeners(el);

detachRolloverListeners

See Also

Feature Detection

Immediate

The detachRolloverListeners function removes rollover-related event listeners.

Syntax

detachRolloverListeners(el);

Examples

API.detachRolloverListeners(el);

detachWindowListener

See Also

Feature Detection

Immediate

The detachWindowListener function removes an event listener from a window.

Syntax

detachWindowListener(ev, fn[, win]);

Examples

API.detachWindowListener('resize', fn);
API.detachWindowListener('scroll', fn, win);

dispatchEvent

Feature Detection

Deferred

The dispatchEvent function fires an event for an element, resulting in the execution of listeners attached to the specified event.

Syntax

dispatchEvent(el, ev[, evType]);

Examples

API.dispatchEvent(el, 'click');

documentReady

See Also

Feature Detection

Immediate

The documentReady function tests if the document is ready.

Syntax

b = documentReady();

Examples

b = API.documentReady();

Return Value

The function returns a boolean.

documentReadyListener

See Also

Feature Detection

Immediate

The documentReadyListener function is called internally when the document is ready. It is exposed as a method so it can be called by script at the end of the body element, such as the Document Ready add-on.

Syntax

documentReadyListener();

Examples

API.documentReadyListener();

ease

Feature Detection

Deferred

The ease object contains easing functions.

Syntax

p = ease(p);

Examples

API.ease.linear = function(p) {
  return p;
};

...where p is a number from 0 to 1.

effects

Feature Detection

Deferred

The effects object contains effect functions.

Syntax

effect(el, p, scratch[, endCode]);

Examples

API.effects.something = function(el, p, scratch, endCode) {
  switch (endCode) {
  case 1:

    // Store inline styles in scratch

    break;
  case 2:

    // Not normally needed

    break;
  case 3:

    // Restore inline styles from scratch

    break;
  }
};

The endCode argument indicates that the effect should initialize (1), complete early due to interruption (2) or revert back to the initial state (3). For example, the interruption code is passed when an effect timer is stopped prematurely (via its stop method) and the revert code is always passed by showElement on hiding an element so that the effect(s) can reload for subsequent shows. The scratch object is typically used to store (on initialization) and restore (on reverting) inline styles. Effects typically involve mutating styles of the element per the percentage (p).

elementContainedInElement

See Also

Feature Detection

Deferred

The elementContainedInElement determines whether an element is completely contained in another (according to the layout, not the DOM structure).

Syntax

b = elementContainedInElement(el, elContainer);

Examples

b = API.elementContainedInElement(el, elContainer);

Return Value

The function returns a boolean.

elementOverlapsElement

See Also

Feature Detection

Deferred

The elementOverlapsElement determines whether two elements overlap.

Syntax

b = elementOverlapsElement(el, el2);

Examples

b = API.elementOverlaysElement(el, el2);

Return Value

The function returns a boolean.

every

See Also

Feature Detection

Immediate

The every function calls the specified function for each element of the specified array, returning true if every result is true.

Syntax

b = every(a, fn[, context]);

Examples

b = API.every(a, function(el, i) { return true; });
b = API.every(a, function(el, i) { return this[i] == el; }, someObject);

Return Value

The function returns a boolean.

emptyNode

Feature Detection

Immediate

The emptyNode function empties a document or element of nodes.

Syntax

emptyNode(el);

Examples

API.emptyNode(el);
API.emptyNode(doc);

filter

See Also

Feature Detection

Immediate

The filter function calls the specified function for each element of the specified array, returning a new array of only the elements for which the result was true.

Syntax

a = filter(a, fn[, context]);

Examples

a = API.filter(a, function(el, i) { return true; });
a = API.filter(a, function(el, i) { return this[i] == el; }, someObject);

Return Value

The function returns a new array.

FlashVariables

See Also

Feature Detection

Immediate

The FlashVariables method constructs an object representing variables for a Flash movie.

Syntax

vars = new FlashVariables();

Examples

var vars = new API.FlashVariables();
vars.addQuery('name1');
vars.addBookmark('name3');
vars.add('name1', 'Test 1');
vars.add('name2', 'Test 2');
vars.add('name3', 'Test 3');

forEach

See Also

Feature Detection

Immediate

The forEach function calls the specified function for each element of the specified array.

Syntax

forEach(a, fn[, context]);

Examples

API.forEach(a, function(el, i) { el.id = 'test' + i });
API.forEach(a, function(el, i) { el.id = this.id(i) }, someObject);

Note that the forEach function is only to be used with native array objects and does not guarantee order. Never pass host objects. Convert array-like host objects to arrays with toArray.

forEachProperty

See Also

Feature Detection

Immediate

The forEachProperty function calls the specified function for each enumerable property of the specified object.

Note that properties inherited from the object's prototype are excluded.

Syntax

forEachProperty(o, fn[, context]);

Examples

API.forEachProperty(o, function(el, i) { el.id = 'test' + i });
API.forEachProperty(o, function(el, i) { el.id = this.id(i) }, someObject);

Note that the this function is only to be used with native objects. Never pass host objects.

formChanged

See Also

Feature Detection

Immediate

The formChanged function determines if one or more of the controls contained by the specified form have changed.

Syntax

b = formChanged(el);

Examples

b = API.formChanged(el);

fullScreenElement

See Also

Feature Detection

Deferred

The fullScreenElement function displays an element using all of the available space in the viewport, hiding the scrollbars to accomodate.

Syntax

fullScreenElement(el);

Examples

API.fullScreenElement(el);

getAnchor

See Also

Feature Detection

Immediate

The getAnchor function finds an anchor element by name or index.

Syntax

el = getAnchor(i[, docNode]);

Examples

elAnchor = API.getAnchor(0);
elAnchor = API.getAnchor('myanchor');

Return Value

The function returns an anchor element or null if none is found to match the specified name or index.

getAnchors

See Also

Feature Detection

Immediate

The getAnchors function finds all anchor elements in a document.

Syntax

a = getAnchors([docNode]);

Examples

anchors = API.getAnchors();
anchors = API.getAnchors(doc);

Return Value

The function returns an array or array-like object.

Note array-like host objects are live collections, so handle with results with care. Use the toArray function to convert to an array.

getAnElement

See Also

Feature Detection

Immediate

The getAnElement function returns the first element in a document (typically the html element.)

Syntax

el = getAnElement([docNode]);

Examples

el = API.getAnElement('myid');
el = API.getAnElement('yourid', doc);

Return Value

The function returns an element or null if none is found.

getAttribute

See Also

Feature Detection

Immediate

The getAttribute function returns the value of the specified attribute of the specified element.

Syntax

v = getAttribute(el, name);

Examples

c = API.getAttribute(el, 'class');
s = API.getAttribute(el, 'style');

Return Value

The function returns a string or null if the specified attribute does not exist.

getAttributeProperty

See Also

Feature Detection

Immediate

The getAttributeProperty function returns the property value of the specified attribute of the specified element.

Syntax

v = getAttributeProperty(el, name);

Examples

c = API.getAttributeProperty(el, 'class');
b = API.getAttributeProperty(el, 'readonly');

Return Value

The function returns the property value. For boolean properties, a boolean is always returned. For other types, null is returned if the specified attribute is missing.

getBodyElement

See Also

Feature Detection

Deferred

The getBodyElement function returns the body element of a document.

Syntax

el = getBodyElement([docNode]);

Examples

elBody = API.getBodyElement();
elBody = API.getBodyElement(doc);

Return Value

The function returns a body element or null if none is found.

getCascadedStyle

See Also

Feature Detection

Immediate

The getCascadedStyle function returns the named cascaded style of an element.

Note this function is rarely used externally. Use getStyle or getComputedStyle instead.

Syntax

s = getCascadedStyle(el, style);

Examples

s = API.getCascadedStyle(el, 'color');
s = API.getCascadedStyle(el, 'backgroundColor');

Note that as with all style-related functions, the name of the style must be in camel-case.

Return Value

The function returns a string or null.

getChildren

Feature Detection

Immediate

The getChildren function returns all child elements of an element or document.

Syntax

a = getChildren(node);

Examples

c = API.getChildren(el);
c = API.getChildren(doc);

Return Value

The function returns an array.

getComputedStyle

See Also

Feature Detection

Immediate

The getComputedStyle function returns the named computed style of an element.

Syntax

s = getComputedStyle(el, style);

Examples

s = API.getComputedStyle(el, 'color');
s = API.getComputedStyle(el, 'backgroundColor');

Note that as with all style-related functions, the name of the style must be in camel-case.

Return Value

The function returns a string or null.

getCookie

See Also

Feature Detection

Immediate

The getCookie function returns the cookie with the specified name.

Syntax

c = getCookie(name[, defaultValue[, encoded[, docNode]]]);

Examples

c = API.getCookie('test');
c = API.getCookie('test', '');

Return Value

The function returns a string or null if a cookie with the specified name does not exist.

getCookieCrumb

See Also

Feature Detection

Immediate

The getCookieCrumb function returns a portion of a cookie.

Syntax

s = getCookieCrumb(name, crumb[, defaultValue[, docNode]]);

Examples

c = API.getCookieCrumb('test', 'me');
c = API.getCookieCrumb('test', 'me', '');

Return Value

The function returns a string or null if a cookie with the specified name does not exist.

getDocumentWindow

See Also

Feature Detection

Immediate

The getDocumentWindow function returns the containing window of a document.

Syntax

win = getDocumentWindow([docNode]);

Examples

win = API.getDocumentWindow();
win = API.getDocumentWindow(doc);

Return Value

The function returns a window.

getEBI

See Also

Feature Detection

Immediate

The getEBI function returns an element with the specified ID.

Syntax

el = getEBI(id[, docNode]);

Examples

el = API.getEBI('myid');
el = API.getEBI('yourid', doc);

Return Value

The function returns an element with the specified ID or null if not found.

getElementBorder

See Also

Feature Detection

Immediate

The getElementBorder function returns the width of the named border of an element.

Syntax

w = getElementBorder(id, side);

Examples

t = API.getElementBorder(el, 'top');
r = API.getElementBorder(el, 'right');

Return Value

The function returns a number of pixels.

getElementBorders

See Also

Feature Detection

Immediate

The getElementBorders function returns an object containing all border widths of an element.

Syntax

o = getElementBorders(el);

Examples

o = API.getElementBorders(el);
window.alert('Top border is: ' + o.top + ' pixels');

Return Value

The function returns an object with properties named for each side (top, left, bottom and right), containing a number of pixels.

getElementBordersOrigin

See Also

Feature Detection

Immediate

The getElementBordersOrigin function returns an object containing the top and left border widths of an element.

Syntax

o = getElementBordersOrigin(el);

Examples

o = API.getElementBordersOrigin(el);
window.alert('Left border is: ' + o.left + ' pixels');

Return Value

The function returns an object with properties named for each side (top and left), containing a number of pixels.

getEBCN

See Also

Feature Detection

Immediate

The getEBCN function returns elements with the specified class name(s) from an element or document.

Syntax

el = getEBCN(className[, node]);

Examples

els = API.getEBCN('myclass');
els = API.getEBCN('myclass yourclass');
els = API.getEBCN('otherclass');
els = API.getEBCN('otherotherclass', doc);

Return Value

The function returns an array.

getEBCS

See Also

Feature Detection

Immediate

The getEBCS function returns elements that match the specified CSS selector from an element or document.

Syntax

el = getEBCS(selector[, node]);

Examples

els = API.getEBCS('div');
els = API.getEBCS('div div div');
els = API.getEBCS('.myclass');
els = API.getEBCS('#myid');
els = API.getEBCS('#myid p.myclass');
els = API.getEBCS('div:first-child');
els = API.getEBCS('div:only-child');
els = API.getEBCS('div:nth-child(5)');
els = API.getEBCS('h2 + div');
els = API.getEBCS('h2 + div#myid');
els = API.getEBCS('h2 ~ div#myid');

Return Value

The function returns an array.

getEBTN

See Also

Feature Detection

Immediate

The getEBTN function returns elements with the specified tag name from an element or document.

Syntax

el = getEBTN(tag[, node]);

Examples

els = API.getEBTN('div');
els = API.getEBTN('div', el);
els = API.getEBTN('div', doc);

Return Value

The function returns an array or array-like host object.

Note array-like host objects are live collections, so handle with results with care. Use the toArray function to convert to an array.

getEBXP

See Also

Feature Detection

Immediate

The getEBXP function returns elements that match the specified XPath expression from an element or document.

Syntax

el = getEBXP(path[, node]);

Examples

els = API.getEBXP('.//h2/following-sibling::*');
els = API.getEBXP('.//h2/following-sibling::*', el);
els = API.getEBXP('.//h2/following-sibling::*', doc);

Return Value

The function returns an array.

getElementDocument

See Also

Feature Detection

Immediate

The getElementDocument function returns the containing document of an element.

Syntax

el = getElementDocument(el);

Examples

doc = API.getElementDocument(el);

Return Value

The function returns a document or null if the element is part of a fragment.

getElementMargin

See Also

Feature Detection

Immediate

The getElementMargin function returns the width of the named margin of an element.

Syntax

w = getElementMargin(id, side);

Examples

m = API.getElementMargin(el, 'top');

Return Value

The function returns a number of pixels.

getElementMargins

See Also

Feature Detection

Immediate

The getElementMargins function returns an object containing all margin widths of an element.

Syntax

o = getElementMargins(el);

Examples

o = API.getElementMargins(el);

Return Value

The function returns an object with properties named for each side (top, left, bottom and right), containing a number of pixels.

getElementMarginsOrigin

See Also

Feature Detection

Immediate

The getElementMarginsOrigin function returns an object containing the top and left margin widths of an element.

Syntax

o = getElementMargins(el);

Examples

o = API.getElementMarginsOrigin(el);

Return Value

The function returns an object with properties named for each side (top and left), containing a number of pixels.

getElementNodeName

Feature Detection

Immediate

The getElementNodeName function returns the tag name of an element in lower case. In XHTML DOM's, only the default HTML namespace is supported.

Syntax

s = getElementNodeName(el);

Examples

s = API.getElementNodeName(el);

Return Value

The function returns a string.

getElementParentElement

Feature Detection

Immediate

The getElementParentElement function returns the parent element of an element.

Syntax

el = getElementParentElement(el);

Examples

el = API.getElementParentElement(el);

Return Value

The function returns an element or null if the element is has no parent element (e.g. is the child of a document.)

getElementPosition

Feature Detection

Deferred

The getElementPosition function returns the absolute position of an element or the position relative to the specified ancestor.

Syntax

p = getElementPosition(el[, elContainer]);

Examples

p = API.getElementPosition(el);
p = API.getElementPosition(el, elContainer);

Return Value

The function returns an array containing the top and left coordinates.

getElementPositionStyle

See Also

Feature Detection

Deferred

The getElementPositionStyle function returns the CSS top and left positions. For statically positioned elements, it returns the position it would have were it absolutely positioned.

Syntax

p = getElementPositionStyle(el);

Examples

p = API.getElementPositionStyle(el);

Return Value

The function returns an array containing the top and left positions in pixels.

getElementSizeStyle

See Also

Feature Detection

Deferred

The getElementSizeStyle function returns the CSS height and width dimensions.

Syntax

d = getElementSizeStyle(el);

Examples

d = API.getElementSizeStyle(el);

Return Value

The function returns an array containing the height and width in pixels.

getElementText

See Also

Feature Detection

Immediate

The getElementText function returns the text of an element.

Syntax

s = getElementText(el);

Examples

s = API.getElementText(el);

Return Value

The function returns a string.

getDocumentHtml

See Also

Feature Detection

Deferred

The getDocumentHtml function retrieves the inner HTML of a document.

Syntax

s = getDocumentHtml(doc);

Examples

html = API.getDocumentHtml(el);

Return Value

The function returns a string.

getElementHtml

See Also

Feature Detection

Deferred

The getElementHtml function retrieves the inner HTML of an element.

Syntax

s = getElementHtml(el);

Examples

html = API.getElementHtml(el);

Return Value

The function returns a string.

getElementOuterHtml

See Also

Feature Detection

Deferred

The getElementOuterHtml function retrieves the outer HTML of an element.

Syntax

s = getElementOuterHtml(el);

Examples

html = API.getElementOuterHtml(el);

Return Value

The function returns a string.

getEnabledPlugin

Feature Detection

Immediate

The getEnabledPlugin function returns the description of an enabled plugin that matches the specified MIME type or title.

Syntax

p = getEnabledPlugin(mimeType[, title]);

Examples

p = API.getEnabledPlugin('audio/x-wav');

Return Value

The function returns a string or null if an enabled plugin is not found.

getEventTarget

See Also

Feature Detection

Immediate

The getEventTarget function returns the target element of an event.

Syntax

el = getEventTarget(e);

Examples

el = API.getEventTarget(e);

Return Value

The function returns an element.

getEventTargetRelated

See Also

Feature Detection

Immediate

The getEventTarget function returns the related target element of an event. For example, on a mouseover event, the related target is the element the pointer is coming from

Syntax

el = getEventTargetRelated(e);

Examples

el = API.getEventTargetRelated(e);

Return Value

The function returns an element or null if there is no related target.

getForm

See Also

Feature Detection

Immediate

The getForm function finds a form element by name or index.

Syntax

el = getForm(i[, docNode]);

Examples

el = API.getForm(0);
el = API.getForm('myform');
el = API.getForm('yourform', doc);

Return Value

The function returns a form element or null if none is found to match the specified name or index.

getForms

See Also

Feature Detection

Immediate

The getForms function finds all form elements in a document.

Syntax

a = getForms([docNode]);

Examples

els = API.getForms();
els = API.getForms(doc);

Return Value

The function returns an array or array-like object.

Note array-like host objects are live collections, so handle with results with care. Use the toArray function to convert to an array.

getFlashVersion

See Also

Feature Detection

Immediate

The getFlashVersion function returns the installed Flash version if available.

Syntax

ver = getFlashVersion();

Examples

ver = API.getFlashVersion();

Return Value

The function returns an object containing the major (version), minor (versionMinor) and revision (versionRevision) versions as numbers and the full (versionFull) version as a string.

getHeadElement

See Also

Feature Detection

Immediate

The getHeadElement function returns the head element of a document.

Syntax

el = getHeadElement([docNode]);

Examples

el = API.getHeadElement();
el = API.getHeadElement(doc);

Return Value

The function returns a head element or null if none is found.

getFrameById

Feature Detection

Immediate

The getFrameById retrieves a frame (or IFrame) window by name (or ID).

Syntax

frame = getFrameById(id[, win]);

Examples

frame = API.getFrameById('myid');
frame = API.getFrameById('myid', win);

Return Value

The function returns a window object or null if none is found.

getHtmlElement

See Also

Feature Detection

Immediate

The getHtmlElement function returns the html element of a document.

Syntax

el = getHtmlElement([docNode]);

Examples

el = API.getHtmlElement();
el = API.getHtmlElement(doc);

Return Value

The function returns an html element or null if none is found.

getIFrameDocument

Feature Detection

Immediate

The getIFrameDocument function returns the document contained in an iframe element.

Syntax

doc = getIFrameDocument(el[, win]);

Examples

doc = API.getIFrameDocument(el);
doc = API.getIFrameDocument(el, win);

Return Value

The function returns a document.

getImage

See Also

Feature Detection

Immediate

The getImage function finds an image element by name or index.

Syntax

el = getImage(i[, docNode]);

Examples

el = API.getImage(0);
el = API.getImage('testimage');
el = API.getImage(0, doc);

Return Value

The function returns an image element or null if none is found to match the specified name or index.

getImages

See Also

Feature Detection

Immediate

The getImages function finds all image elements in a document.

Syntax

a = getImages([docNode]);

Examples

els = API.getImages();
els = API.getImages(doc);

Return Value

The function returns an array or array-like object.

Note array-like host objects are live collections, so handle with results with care. Use the toArray function to convert to an array.

getKeyboardKey

Feature Detection

Immediate

The getKeyboardKey function returns the code of the keyboard key (or character for keypress events) related to an event.

Syntax

n = getKeyboardKey(e);

Examples

k = API.getKeyboardKey(e);

Return Value

The function returns a number.

getLink

See Also

Feature Detection

Immediate

The getLink function finds a link by name or index.

Syntax

el = getLink(i[, docNode]);

Examples

el = API.getLink(0);
el = API.getLink('testlink');
el = API.getLink(0, doc);

Return Value

The function returns an anchor element or null if none is found to match the specified name or index.

getLinks

See Also

Feature Detection

Immediate

The getLinks function finds all links in a document.

Syntax

a = getLinks([docNode]);

Examples

els = API.getLinks();
els = API.getLinks(doc);

Return Value

The function returns an array or array-like object.

Note array-like host objects are live collections, so handle with results with care. Use the toArray function to convert to an array.

getMouseButtons

Feature Detection

Immediate

The getMouseButtons function returns the state of the mouse buttons during an event.

Syntax

o = getMouseButtons(e);

Examples

o = API.getMouseButtons(e);

Return Value

The function returns a object with boolean left, middle and right properties.

getMousePosition

Feature Detection

Immediate

The getMousePosition function returns the position of the mouse, relative to the document, during an event.

Note that this method may rewrite itself at any time, so always get a fresh reference before calling (or call as a method of API).

Syntax

a = getMousePosition(e);

Examples

a = API.getMousePosition(e);

Return Value

The function returns an array containing the top and left coordinates (in pixels.)

getMousewheelDelta

Feature Detection

Immediate

The getMousewheelDelta function returns the distance and direction traveled by the mousewheel during an event.

Syntax

n = getMousewheelDelta(e);

Examples

n = API.getMousewheelDelta(e);

Return Value

The function returns a number.

getOpacity

See Also

Feature Detection

Immediate

The getOpacity function returns the opacity of an element.

Syntax

o = getOpacity(el);

Examples

o = API.getOpacity(el);

Return Value

The function returns a number from 0 to 1.

getOptionValue

Feature Detection

Immediate

The getOptionValue function returns the value of the specified option element.

Syntax

s = getOptionValue(el);

Examples

s = API.getOptionValue(el);

Return Value

The function returns a string.

getQuery

Feature Detection

Immediate

The getQuery function returns the value of the named search parameter.

Syntax

q = getQuery(name[, defaultValue]);

Examples

q = API.getQuery('testing');
q = API.getQuery('testing', '123');

Return Value

The function returns a string or null.

getScrollPosition

Feature Detection

Deferred

The getScrollPosition function returns the scroll position of a document.

Syntax

a = getScrollPosition([docNode]);

Examples

a = API.getScrollPosition();
a = API.getScrollPosition(doc);

Return Value

The function returns an array containing the top and left scroll positions or null if the position cannot be determined.

Note that this method may rewrite itself at any time, so always get a fresh reference before calling (or call as a method of API).

getStyle

See Also

Feature Detection

Immediate

The getStyle function returns the named style of an element or null if unavailable. The function will attempt to use the getComputedStyle or getCascadedStyle functions and then the inline style if necessary.

Syntax

s = getStyle(el, style);

Examples

s = API.getStyle(el, 'color');
s = API.getStyle(el, 'backgroundColor');

Return Value

The function returns a string or null.

Note that as with all style-related functions, the name of the style must be in camel-case.

getViewportClientRectangle

Feature Detection

Deferred

The getViewportClientRectangle function returns the size and scroll position of the viewport.

Syntax

r = getViewportClientRectangle([docNode]);

Examples

r = API.getViewportClientRectangle();
r = API.getViewportClientRectangle(doc);

Return Value

The function returns an array containing the top, left, height and width of the viewport.

getViewportScrollRectangle

See Also

Feature Detection

Deferred

The getViewportScrollRectangle function returns the top, left, height and width of the top-level rendered element (HTML or body) in a document.

Syntax

r = getViewportScrollRectangle([docNode]);

Examples

r = API.getViewportScrollRectangle();
r = API.getViewportScrollRectangle(doc);

Return Value

The function returns an array containing the top, left, height and width of the top-level rendered element (HTML or body).

getViewportScrollSize

See Also

Feature Detection

Deferred

The getViewportScrollSize function returns the size of the top-level rendered element (HTML or body).

Syntax

s = getViewportScrollSize([docNode]);

Examples

r = API.getViewportScrollSize();
r = API.getViewportScrollSize(doc);

Return Value

The function returns an array containing the height and width of the top-level rendered element (HTML or body) in a document.

getViewportSize

Feature Detection

Deferred

The getViewportSize function returns the size of a viewport for the specified document.

Syntax

s = getViewportSize([window]);

Examples

s = API.getViewportSize(doc);

Return Value

The function returns an array containing the height and width of the viewport.

hasAttribute

See Also

Feature Detection

Immediate

The hasAttribute function tests if the specified element has an attribute with the specified name.

Syntax

b = hasAttribute(el, name);

Examples

b = API.hasAttribute(el, 'id');
b = API.hasAttribute(el, 'for');
b = API.hasAttribute(el, 'rel');

Return Value

The function returns a boolean.

hasClass

See Also

Feature Detection

Immediate

The hasClass function tests if the specified element has the specified CSS class.

Syntax

b = hasClass(el, className);

Examples

b = API.hasClass(el, 'myclass');

Return Value

The function returns a boolean.

importNode

Feature Detection

Deferred

The importNode function imports an element from one document into another.

Syntax

el = importNode(el[, bImportChildren[, docNode]]);

Examples

el = API.importNode(elExport);
el = API.importNode(elExportWithChildren, true);

Return Value

The function returns the imported element.

inherit

See Also

Feature Detection

Immediate

The inherit function creates an inheritance relationship between two constructor functions.

Syntax

inherit(fnSub, fnSuper);

Examples

API.inherit(fnSub, fnSuper);

initiateDrag

See Also

Feature Detection

Deferred

The initiateDrag function starts a drag action.

Syntax

initiateDrag(el[, elHandle]);

Examples

API.initiateDrag(el);
API.initiateDrag(el, elHandle);

inputChanged

See Also

Feature Detection

Immediate

The inputChanged function determines whether a form control has changed.

Syntax

b = inputChanged(el);

Examples

b = API.inputChanged(el);

Return Value

The function returns a boolean.

inputValue

See Also

Feature Detection

Immediate

The inputValue function retrieves the value of a form control.

Syntax

value = inputValue(el[, default]);

Examples

value = API.inputValue(el);
defaultValue = API.inputValue(el, true);

Return Value

The function returns a string or array.

isDescendant

Feature Detection

Immediate

The isDescendant function determines if an element is the ancestor of another.

Syntax

b = isDescendant(elAncestor, elDescendant);

Examples

b = API.isDescendant(elAncestor, elDescendant);

Return Value

The function returns a boolean.

isHostMethod

Feature Detection

Immediate

The isHostMethod function tests if the specified host object property references an object.

If the referenced object will not be called, use isHostObjectProperty.

Allowed properties may be of type function, object (IE and possibly others) or unknown (IE ActiveX methods). Object types exclude null.

This test does not assert that an arbitrary property is callable. Pass only names of properties universally implemented as methods.

This test does not support properties that are methods in some browsers but not others (e.g. childNodes). This test will not discriminate between such implementations and applications should never call such objects.

Syntax

b = isHostMethod(o, p);

Examples

b = API.isHostMethod(el, 'getElementsByTagName');

Return Value

The function returns a boolean.

isHostObjectProperty

Feature Detection

Immediate

The isHostObjectProperty function tests if the specified host object property references an object that is safe to evaluate. ActiveX methods and other properties of type unknown are excluded.

If the referenced object will be called, use isHostMethod.

Allowed properties may be of type function, object (IE and possibly others). Object types exclude null.

Syntax

b = isHostObjectProperty(o, p);

Examples

b = API.isHostObjectProperty(el, 'parentNode');

Return Value

The function returns a boolean.

isOwnProperty

Feature Detection

Immediate

The isOwnProperty function tests if the specified object does not inherit the specified property from its prototype. The property is stipulated to exist. This function is typically used to filter inherited properties within for-in loops.

Note the object must be native, not a host object.

Syntax

b = isOwnProperty(o, p);

Examples

b = API.isOwnProperty(o, 'apples');
b = API.isOwnProperty(o, 'oranges');

Return Value

The function returns a boolean.

isPositionable

Feature Detection

Immediate

The isPositionable function determines if an element is positionable (position style is not static).

Syntax

b = isPositionable(el);

Examples

b = API.isPositionable(el);

Return Value

The function returns a boolean.

isPresent

See Also

Feature Detection

Immediate

The isPresent function determines if an element is part of the layout (display style is not none).

Syntax

b = isPresent(el);

Examples

b = API.isPresent(el);

Return Value

The function returns a boolean.

isRealObjectProperty

Feature Detection

Immediate

The isRealObjectProperty function tests if the specified object property references an object.

Note this function is not for use with host objects.

Syntax

b = isRealObjectProperty(o, p);

Examples

b = API.isRealObjectProperty(obj, 'tree');

Return Value

The function returns a boolean.

isVisible

See Also

Feature Detection

Immediate

The isVisible function determines if an element is visible (according to its style) and part of the layout (display style is not none).

Syntax

b = isVisible(el);

Examples

b = API.isVisible(el);

Return Value

The function returns a boolean.

isXmlParseMode

Feature Detection

Immediate

The isXmlParseMode function tests if a document was parsed as XML. It is not magic as there are certain practices that must be followed to best ensure its accuracy.

You should include an appropriate Content-Type meta in the head of your documents (at least for HTML documents) as this ensures there will not be false positives. Putting an inappropriate Content-Type meta in documents that are to be served with an XML MIME type (e.g. application/xhtml+xml) will cause false negatives in some browsers, so should be avoided. For example, something like this should never appear in an XHTML document served as XML:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

...but something along those lines (minus the slash) should always be present in a document served as HTML.

Note that when serving HTML documents (virtually the only type served on the Web today), to avoid all confusion, you can simply disable this check entirely by setting API.disableXmlParseMode to true (highly recommended). This must be set prior to loading My Library:

var API = { disableXmlParseMode:true };

XHTML support can also be filtered at build time, in which case the above setting is superfluous (XML parse mode will never be detected).

Syntax

b = isXmlParseMode([docNode]);

Examples

b = API.isXmlParseMode();
b = API.isXmlParseMode(doc);

Return Value

The function returns a boolean.

map

See Also

Feature Detection

Immediate

The map function calls the specified function for each element of the specified array, returning a new array of the results.

Syntax

a = map(a, fn[, context]);

Examples

a = map(a, function(el) { return el.id; });
a = map(a, function(el) { return this.fetchId(el); }, someObject);

Return Value

The function returns a new array.

maximizeElement

See Also

Feature Detection

Deferred

The maximizeElement sizes and positions an element to fill its viewport.

Syntax

maximizeElement(el);

Examples

API.maximizeElement(el);

overlayElement

See Also

Feature Detection

Deferred

The overlayElement function positions an element to overlay another, optionally covering it.

Syntax

overlayElement(el, elOver[, cover]);

Examples

API.overlayElement(el, elTarget);
API.overlayElement(el, elTarget, true);

playAudio

Feature Detection

Deferred

The playAudio function plays one or more audio files.

Note that the boolean API.deferAudio property determines whether audio plug-ins are loaded when the document is ready (default) or when the first audio file is played (recommended). The unfortunate default will be changed in the future to defer the loading of plug-ins as plug-ins should not load without an explicit user action.

Syntax

playAudio(files, time[, cb[, ext[, volume]]]);

Examples

API.playAudio('ding.wav', 1000);

playDirectXTransitionFilter

See Also

Feature Detection

Deferred

The playDirectXTransitionFilter function plays a DirectX transition.

Syntax

playDirectXTransitionFilter(el, name);

Examples

API.playDirectXTransitionFilter(el, 'fade');

pop

See Also

Feature Detection

Immediate

The pop function removes the last element from an array and returns that the value of that element.

Syntax

x = pop(a);

Examples

x = API.pop(a);

Return Value

The function returns the value of an array element.

positionElement

Feature Detection

Immediate

The positionElement function positions an element.

Syntax

positionElement(el, top, left[, options[, callback]]);

Examples

API.positionElement(el, 0, 0);
API.positionElement(el, 0, 0, { duration:1000, ease:API.ease.circle });

preloadImage

See Also

Feature Detection

Immediate

The preloadImage function loads and stores the specified image resource.

Syntax

handle = preloadImage(src, h, w);

Examples

handle = API.preloadImage('cinsoft.gif', 100, 100);

Return Value

The function returns a numeric handle to reference the stored image.

presentElement

See Also

Feature Detection

Deferred

The presentElement function adds or removes an element from the layout (e.g. sets its display property).

Syntax

presentElement(el[, b]);

Examples

API.presentElement(el);
API.presentElement(el, false);

push

See Also

Feature Detection

Immediate

The push function apppends elements to an array and returns the new length of the array.

Syntax

push(a, x1[, x2, ..., xN]);

Examples

API.push(a, x);
API.push(a, x, y);
API.push(a, x, y, z);

Return Value

The function returns a number.

removeClass

See Also

Feature Detection

Immediate

The removeClass function removes a CSS class from an element.

Syntax

removeClass(el, className);

Examples

API.removeClass(el, 'testclass');

removeOptions

See Also

Feature Detection

Immediate

The removeOptions function removes all options from a select element.

Syntax

removeOptions(el);

Examples

API.removeOptions(el);

Requester

Feature Detection

Immediate

The Requester function is a constructor that creates an object that simplifies the process of sending Ajax requests.

Syntax

requester = new Requester([sId[, sGroup]]);

Examples

r = API.Requester('id');
r = API.Requester('id', 'groupid');

restoreElement

See Also

Feature Detection

Deferred

The restoreElement function restores the size and position of a previously maximized or full-screen element.

Syntax

restoreElement(el);

Examples

API.restoreElement(el);

serializeFormUrlencoded

See Also

Feature Detection

Immediate

The serializeFormUrlencoded function encodes name/value pairs of a form element according to the specification of the application/x-www-form-urlencoded MIME type.

Syntax

s = serializeFormUrlencoded(form);

Examples

s = API.serializeFormUrlencoded(el);

Return Value

The function returns a string.

setActiveStyleSheet

Feature Detection

Immediate

The setActiveStyleSheet function activates style sheets with the specified ID for a document. Style sheets with ID's other than the one specified are deactivated. This function is typically used to switch between alternate style sheets.

Syntax

setActiveStyleSheet(id[, docNode]);

Examples

API.setActiveStyleSheet('winter');
API.setActiveStyleSheet('summer', doc);

setAttribute

See Also

Feature Detection

Immediate

The setAttribute function sets the value of the specified attribute of the specified element.

Syntax

el = setAttribute(el, name, value);

Examples

el = API.setAttribute(el, 'id', 'myid');
el = API.setAttribute(el, 'style', 'color:red');

Return Value

The function returns an element, which in some cases may be a replacement (e.g. setting the type attribute of an input element in IE.)

setAttributeProperty

See Also

Feature Detection

Immediate

The setAttributeProperty function sets the property value of the specified attribute of the specified element.

Syntax

el = setAttributeProperty(el, name, value);

Examples

el = API.setAttributeProperty(el, 'id', 'myid');
el = API.setAttributeProperty(el, 'readonly', true);

Return Value

The function returns an element, which in some cases may be a replacement (e.g. changing the type attribute of an input element in IE.)

setAttributeProperties

See Also

Feature Detection

Immediate

The setAttributeProperties function sets the property values of the specified attributes of the specified element.

Syntax

el = setAttributeProperties(el, attributes);

Examples

el = API.setAttributeProperties(el, { id:'myid', readonly:true });

Return Value

The function returns an element, which in some cases may be a replacement (e.g. changing the type attribute of an input element in IE.)

setAttributes

See Also

Feature Detection

Immediate

The setAttributes function sets the values of the specified attributes of the specified element.

Syntax

el = setAttributes(el, attributes);

Examples

el = API.setAttributes(el, { id:'myid', 'class':'myclass' });

Return Value

The function returns an element, which in some cases may be a replacement (e.g. changing the type attribute of an input element in IE.)

setCookie

See Also

Feature Detection

Immediate

The setCookie function sets the cookie with the specified name to the specified value.

Syntax

setCookie(name, value[, expires[, path[, secure[, docNode]]]]);

Examples

API.setCookie('myname', 'myvalue');
API.setCookie('myname', 'myvalue', 7); // Expires in 7 days

setCookieCrumb

See Also

Feature Detection

Immediate

The setCookieCrumb function sets a portion of a cookie.

Syntax

setCookieCrumb(name, crumb, value[,path[, docNode]]);

Examples

API.setCookieCrumb('myname', 'mycrumbname', 'myvalue');

setDefaultStatus

See Also

Feature Detection

Immediate

The setDefaultStatus function sets the default status bar text for a window.

Syntax

setDefaultStatus(text[, win]);

Examples

API.setDefaultStatus('My Library rocks!');
API.setDefaultStatus('Definitely!', win);

setElementHtml

See Also

Feature Detection

Deferred

The setElementHtml function sets the inner HTML of an element. The optional parameters are for use with effects modules (e.g. DirectX), which replace the standard function with one that supports progressive rendering.

Syntax

el = setElementHtml(el, html[options[, callback]]);

Examples

API.setElementHtml(el, '<p>This is a test.</p>');

Return Value

The function returns an element, which in some cases may be a replacement (e.g. select elements in IE.)

setElementNodes

See Also

Feature Detection

Deferred

The setElementNodes function replaces the nodes of an element. The optional parameters are for use with effects modules (e.g. DirectX), which replace the standard function with one that supports progressive rendering.

Syntax

setElementNodes(el, elNewNodes[options[, callback]]);

Examples

el = API.setElementNodes(el, elNewNodes);

setElementOuterHtml

See Also

Feature Detection

Deferred

The setElementOuterHtml function sets the outer HTML of an element. The optional parameters are for use with effects modules (e.g. DirectX), which replace the standard function with one that supports progressive rendering.

Syntax

el = setElementOuterHtml(el, html[options[, callback]]);

Examples

el = API.setElementOuterHtml(el, '<p>Testing...</p>');

Return Value

The function returns an element, which is always a replacement.

setElementScript

See Also

Feature Detection

Deferred

The setElementScript function sets the text of a script element.

Syntax

setElementScript(el, text);

Examples

API.setElementScript(el, 'window.alert("Hello world!");');

setElementText

See Also

Feature Detection

Immediate

The setElementText function sets the text of an element.

Syntax

setElementText(el, text);

Examples

API.setElementText(el, 'Hello world!');

setOpacity

See Also

Feature Detection

Immediate

The setOpacity function sets the opacity of an element, specified as a number from 0 (invisible) to 1 (opaque).

Syntax

setOpacity(el, opacity);

Examples

API.setOpacity(el, 0.5);

setScrollPosition

Feature Detection

Deferred

The setScrollPosition function sets the scroll position of a document.

Syntax

setScrollPosition(t, l[, docNode[, isNormalized[, options[, callback]]]]);

Examples

API.setScrollPosition(el, 0, 0);
API.setScrollPosition(el, 0, 0, doc);

setStatus

See Also

Feature Detection

Immediate

The setStatus function sets the status bar text for a window.

Syntax

setStatus(text[, win]);

Examples

API.setStatus(el, 'Hello world!');
API.setStatus(el, 'Hello back!', win);

setStyle

See Also

Feature Detection

Immediate

The setStyle function sets the style of the specified element.

Syntax

setStyle(el, style, rule);

Examples

API.setStyle(el, 'color', '#CCCCCC');
API.setStyle(el, 'backgroundColor', '#333333');

Note that as with all style-related functions, the name of the style must be in camel-case.

setStyles

Feature Detection

Immediate

See Also

The setStyles function sets multiple styles of the specified element.

Syntax

setStyles(el, rules);

Examples

API.setStyles(el, { color: '#CCCCCC', backgroundColor:'#333333' });

Note that as with all style-related functions, the name of the style must be in camel-case.

showElement

See Also

Feature Detection

Deferred

The showElement function shows or hides an element as indicated by the show argument.

Syntax

showElement(el, [show[, options[, callback]]]);

Examples

API.showElement(el);
API.showElement(el, false);
API.showElement(el, false, { removeOnHide: true });
API.showElement(el, false, { effects:API.effects.fade, duration:1000 });

sizeElement

See Also

Feature Detection

Immediate

The sizeElement function sizes an element by setting its height and width styles to the indicated number of pixels.

Syntax

sizeElement(el, h, w[, options[, callback]]);

Examples

API.sizeElement(el, 100, 100);
API.sizeElement(el, 100, 100, { duration:1000, ease:API.ease.circle });

sizeElementOuter

See Also

Feature Detection

Immediate

The sizeElementOuter function sets an element's outer dimensions.

Syntax

sizeElementOuter(el, h, w);

Examples

API.sizeElementOuter(el, 100, 100);

some

See Also

Feature Detection

Immediate

The some function calls the specified function for each element of the specified array, returning true if at least one result is true.

Syntax

b = some(a, fn[, context]);

Examples

b = API.some(a, function(el) { return el.id.indexOf('test') != -1 });
b = API.some(a, fn, someObject);

Return Value

The function returns a boolean.

submitAjaxForm

See Also

Feature Detection

Immediate

The submitAjaxForm function submits a form via Ajax.

Syntax

submitAjaxForm(el[, json[, requester]]);

Examples

API.submitAjaxForm(el);
API.submitAjaxForm(el, true);
API.submitAjaxForm(el, true, requester);

toArray

Feature Detection

Immediate

The toArray function copies an array or array-like object to a new array.

Syntax

a = toArray(c);

Examples

a = API.toArray(el.childNodes);

Return Value

The function returns a array.

toggleElement

See Also

Feature Detection

Deferred

The toggleElement function shows or hides an element.

Syntax

toggleElement(el[, options[, callback]]);

Examples

API.toggleElement(el);
API.toggleElement(el, { removeOnHide:true, effects:API.effects.fade, duration:1000 });

toggleElementPresence

See Also

Feature Detection

Deferred

The toggleElementPresence function adds or removes an element from the layout by changing its display style.

Syntax

toggleElementPresence(el[, display]]);

Examples

API.toggleElementPresence(el);
API.toggleElement(el, 'block');
API.toggleElement(el, 'inline');

urlencode

See Also

Feature Detection

Immediate

The urlencode function encodes a string according to the specification of the application/x-www-form-urlencoded MIME type.

Syntax

s = urlencode(text);

Examples

s = API.urlencode(text);

Return Value

The function returns a string.

Last Modified: 22 Apr 2010 22:29:00 GMT

By David Mark