λJS 4.5 API reference
Legend: Optional parameters, Function shortcut

Table of contents

General accessor functions [top]

AJS.getQueryArgument(var_name)

Returns the value of var_name from URL (e.g. http://domain.com/?var_name=value).
Example:

AJS.isIe()

Returns true if the current browser is Internet Explorer. Else false is returned.

AJS.isNetscape7()

Returns true if the current browser is Netscape 7. Else false is returned.

AJS.isSafari()

Returns true if the current browser is Apple Safari. Else false is returned.

AJS.isOpera()

Returns true if the current browser is Opera. Else false is returned.

AJS.isMozilla()

Returns true if the current browser is Mozilla. Else false is returned.

AJS.isMac()

Returns true if the current system is Mac OS X. Else false is returned.

Array functions [top]

AJS.createArray(v)

Takes a value v and returns [v]. v is returned as is if it already is an array.
Shortcut:
AJS.$A
Example:

AJS.forceArray(array)

Returns a true array. This method is useful to force arguments to act as an array instead of an object.

AJS.join(delim, list)

Puts all the elements of list into a string. The elements are separated by the specified delimiter delim.
Example:

AJS.isIn(element, list)

Returns true if the element is found in list, otherwise false is returned.
Example:

AJS.getIndex(element, list, eval_fn)

Returns index of element in list. If the element isn't found -1 is returned.
An optional function eval_fn(list_elm) → boolean can be sent to evalute the element.
Example:

AJS.getFirst(list)

Returns the first element of list. If the list is empty null is returned.
Example:

AJS.getLast(list)

Returns the last element of list. If the list is empty null is returned.
Example:

AJS.update(list1, list2)

Extends list1 with keys and values from list2.
Example:

AJS.flattenList(list)

Flats out list and returns the result. See the example.
Example:

AJS.flattenElmArguments(args)

Flats out [[elm1, ..., elmN], valX] and returns the [elm1, ..., elmN, valX].
Example:

Functional programming [top]

AJS.map(list, fn, start_index, end_index)

Runs function fn on all elements of list. Signature of fn is: fn(element, index).
Example:

AJS.rmap(list, fn)

Runs function fn on all elements of list in reversed order. Signature of fn is: fn(element, index).
Example:

AJS.filter(list, fn, start_index, end_index)

Runs function fn on all elements of list and returns all the elements of list where fn(elm) equals true.
Example:

AJS.partial(fn, args)

Return a partially applied function. See example.
Example:

DOM functions [top]

Accessors

AJS.getElement(id)

Returns the DOM element with the id="id".
Shortcut:
AJS.$
Example:

AJS.getElements(id1, id2, idN)

Returns a list of DOM elements with id1, id2, idN.
Shortcut:
AJS.$$

AJS.getElementsByTagAndClassName(tag_name, class_name, parent)

Returns a list of DOM elements. If you want to ignore the tag_name or class_name then set them to null. The whole document is searched, if parent isn't set.
Shortcut:
AJS.$bytc
Example:

AJS.nodeName(element)

Returns the node name of element.
Example:

AJS.getParentBytc(element, tag_name, class_name)

Look on element's parents and return the first match.
Example:

AJS.hasParent(element, parent_to_consider, max_look_up)

Returns true if the element has a parent, false otherwise. max_look_up specifies how many parents to consider. parent_to_concider is the parent we are looking for.
Example:

AJS.getPreviousSiblingBytc(element, tag_name, class_name)

Look on element's previous siblings and return the first match.
Example:

AJS.getNextSiblingBytc(element, tag_name, class_name)

Look on element's next siblings and return the first match.
Example:

AJS.getBody()

Returns the body DOM element.

Form related

AJS.getFormElement(form, name)

Returns a form element with the specified name.
Shortcut:
AJS.$f
Example:

AJS.formContents(form)

Returns a JSON representation of form's contents. Really useful for AJAX calls.
Example:

DOM related

AJS.documentInsert(element)

Append a DOM element using document.writeln.
Shortcut:
AJS.DI
Example:

AJS.appendChildNodes(elm, elm1, elm2, elmN)

Append elm1, elm2, elmN to elm.
Shortcut:
AJS.ACN
Example:

AJS.appendToTop(elm, elm1, elm2, elmN)

Append elm1, elm2, elmN to the top of elm.
Example:

AJS.replaceChildNodes(elm, elm1, elm2, elmN)

Replace elm's child nodes with elm1, elm2, elmN.
Shortcut:
AJS.RCN
Example:

AJS.insertAfter(element, reference_elm)

Insert element after reference_elm.
Example:

AJS.insertBefore(element, reference_elm)

Insert element before reference_elm.
Example:

AJS.swapDOM(elm_to_replace, new_elm)

Replace the DOM of elm_to_replace with the DOM of new_elm.
Example:

AJS.removeElement(elm1, elm2, elmN)

Remove elm1, elm2, elmN.

AJS.createDOM(name, attrs)

Create a new DOM element with tag name. attrs should be an array.
Example:

AJS.createDOM shortcuts

You can use shortcuts to speed up creation of elements.
Example:
Current shortcuts:
  • AJS.UL
  • AJS.LI
  • AJS.TD
  • AJS.TR
  • AJS.TH
  • AJS.TBODY
  • AJS.TABLE
  • AJS.INPUT
  • AJS.SPAN
  • AJS.B
  • AJS.A
  • AJS.DIV
  • AJS.IMG
  • AJS.BUTTON
  • AJS.H1
  • AJS.h3
  • AJS.H3
  • AJS.BR
  • AJS.TEXTAREA
  • AJS.FORM
  • AJS.P
  • AJS.SELECT
  • AJS.OPTION
  • AJS.TN
  • AJS.IFRAME
  • AJS.SCRIPT
  • AJS.CENTER
  • AJS.DL
  • AJS.DT
  • AJS.DD
  • AJS.SMALL

AJS.setHTML(elm1, elm2, elmN, html)

Set the innerHTML of elm1, elm2, elmN to html.

CSS related

AJS.showElement(elm1, elm2, elmN)

Show elm1, elm2, elmN.

AJS.hideElement(elm1, elm2, elmN)

Hide elm1, elm2, elmN.

AJS.isElementShown(element)

Returns true if the element is shown, false otherwise. CSS visibility and display is considered.

AJS.isElementHidden(element)

Returns true if the element is hidden, false otherwise. CSS visibility and display is considered.

AJS.setStyle(elm1, ..., elmN, property, new_value)

Set CSS property of elm1, ..., elmN to new_value. new_value can be {top: 50, left: 40}

AJS.setWidth(elm1, elm2, elmN, width)

Set the width of elm1, elm2, elmN to width. width should be an integer.
Example:

AJS.setHeight(elm1, elm2, elmN, height)

Set the height of elm1, elm2, elmN to height. height should be an integer.

AJS.setLeft(elm1, elm2, elmN, left)

Set the left coordinate of elm1, elm2, elmN to left. left should be an integer.

AJS.setRight(elm1, elm2, elmN, right)

Set the right coordinate of elm1, elm2, elmN to right. right should be an integer.

AJS.setTop(elm1, elm2, elmN, top)

Set the top coordinate of elm1, elm2, elmN to top. top should be an integer.

AJS.setClass(elm1, elm2, elmN, className)

Set the class name of elm1, elm2, elmN to className.

AJS.addClass(elm1, elm2, elmN, className)

Add the className to elm1, elm2, elmN.

AJS.removeClass(elm1, elm2, elmN, className)

Remove the className from elm1, elm2, elmN.

AJS.setOpacity(element, p)

Set the opacity of element to p. p should be 0.50 if you want 50% transparency.
Example:

Misc

AJS.HTML2DOM(html, first_child)

Return a DOM of html. If first_child is set to true then the first child from the html will be returned.
Example:

AJS.preloadImages(img_src1, img_src2, img_srcN)

Preloads images when the window is loaded.
Example:

AJAX [top]

AJS.BASE_URL

If this is set, then you can use relative paths.
Example:

AJS.getXMLHttpRequest()

Returns a new XMLHTTPRequest.
Example:

AJS.getRequest(url, data, type)

Perform a XMLHttpRequest to url and wrap it in a deferred.
data could be a JSON object. type could be GET (POST is default). Both data and type are optional.
Example with del.icio.us:
Example with a GET request:
Example with addCallbacks:

AJS.serializeJSON(object)

Serialize the object to a JSON string.
Example:

AJS.loadJSON(url)

Do a simple XMLHttpRequest to url and get the response as a JSON object.
Example with Yahoo image search:

AJS.evalScriptTags(html)

Evaluate the script tags inside the html.

AJS.evalTxt(js_txt)

Evaluates js_txt.
Example:

Position and size [top]

AJS.getMousePos(event)

Returns {x: mouse_pos_x, y: mouse_pos_y}

AJS.getScrollTop()

Returns the current page scroll top as integer.

AJS.absolutePosition(element)

Returns the absolute position of a DOM element as {x: elm_left, y: elm_top}.
Example:

AJS.getWindowSize()

Returns {w: window_width, h: window_height}.

AJS.isOverlapping(elm1, elm2)

Returns true if elm1 and elm2 overlap each other, otherwise false is returned.

Events [top]

AJS.getEventElm(event)

Returns the DOM element that triggered the event.

AJS.addEventListener(element, type, fn, listen_once, cancle_bubble)

Add an event listener of type on the element.
fn:
the function that is going to be triggered. Signature is fn(event).
event.key denotes the ASCII key if event type is keypress, keydown or keyup.
type can be:
  • "click"
  • "mouseover"
  • "mousemove"
  • "mouseout"
  • "load"
  • ...
listen_once:
a boolean that specifies if the event should only listen once. Optional.
cancle_bubble:
a boolean that specifies if bubbling should be disabled. Optional.
Shortcut:
AJS.AEV
Example:

AJS.removeEventListener(element, type, fn, cancle_bubble)

Remove an event listener from element.
Shortcut:
AJS.REV
Example:

AJS.bind(fn, scope, extra_args)

Bind function fn to scope.
extra_args:
an array of extra parameters that should be sent to fn. Optional.
Shortcut:
AJS.$b
Example:

AJS.bindMethods(obj)

Binds every method of obj to itself. Very useful for Ajax programming.
Example:

AJS.callLater(function, interval)

Execute function after interval milliseconds
Example:

Miscellaneous functions [top]

AJS.keys(object)

Returns the keys of the object as an array.
Example:

AJS.values(object)

Returns the values of the object as an array.
Example:

AJS.urlencode(string)

URL-encodes string.
Example:

AJS.isDefined(object)

Returns true if object is defined. Else false is returned.
Example:

AJS.isArray(object)

Returns true if object is an array. Else false is returned.

AJS.isString(object)

Returns true if object is a string. Else false is returned.

AJS.isNumber(object)

Returns true if object is a number. Else false is returned.

AJS.isObject(object)

Returns true if object is a object. Else false is returned.

AJS.isDict(object)

Returns true if object is a dict (JSON). Else false is returned.
Example:

AJS.exportToGlobalScope(scope)

Export AJS to global scope if scope is null. Else export AJS to scope.

AJS.withScope(scope, fn)

Exectue function fn with scope.
Example:

AJS deferred [top]

A deferred gives the option to chain functions. I borrowed this idea from MochiKit that borrowed it from Twisted. My implementation is SUPER simple and is way off the initial idea of a deferred - but it's still useful and beautiful.

When you call AJS.getRequest or AJS.loadJSON you get a deferred object. This object has following methods:

addCallback(fn):
Add the function fn to the end of the callback sequence.
addErrback(fn):
Add the function fn to the end of the errorback sequence.
addCallbacks(callback, errback):
Add function callback to the end of the callback sequence.
Add function errback to the end of the errback sequence.
sendReq(data):
Send the actual request. data should be a JSON object.

If no error is encountered the callback sequence will be executed. If an error is encountered then the errback sequence will be executed.

The idea is best showed by an example:

var d = AJS.getRequest("http://del.icio.us/feeds/json/amix")

d.addCallback(function(res_txt, req) {
    //Eval response text to get a Delicious object
    AJS.evalTxt(res_txt);
    return Delicious;
})
d.addCallback(function(o, req) {
    //o is now Delicious object
    alert('Total length of posts: ' + o.posts.length);
})

d.addErrback(function(res_txt, req) { alert("Error encountered.") })
d.addErrback(function(res_txt, req) {
     alert("In here we could have some clean up code.")
})
d.sendReq()
Run this example? Deferred example with Deli.cio.us.

If the request is made without errors then following text will be alerted:
"Request complete!"
"... a lot of data ..."
If an error is encountered then following text will be alerted:
"Error encountered."
"Must clean up this mess."