λJS 3.0 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.

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:

Functional programming [top]

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

Runs function fn on all elements of list.
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]

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.getFormElement(form, name)

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

AJS.getBody()

Returns the body DOM element.

AJS.nodeName(element)

Returns the node name of element.
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.isElementHidden(element)

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

AJS.documentInsert(element)

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

AJS.cloner(element)

Returns a function that clones the element.
Example:

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

Append elm1, elm2, elmN to elm.
Shortcut:
AJS.ACN
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.showElement(elm1, elm2, elmN)

Show elm1, elm2, elmN.

AJS.hideElement(elm1, elm2, elmN)

Hide elm1, elm2, elmN.

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.H2
  • 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.getCssDim(dimension)

If dimension is an integer then integer is suffixed with "px". Otherwise dimension is returned unaltered.
Example:

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.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.setHTML(elm1, elm2, elmN, html)

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

AJS.RND(template, name_space, scope)

Render a RND template.
Example:

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:

Effects [top]

AJS.setOpacity(element, p)

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

AJAX [top]

Learn best through examples? Check out:

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.loadJSONDoc(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)
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.callLater(function, interval)

Execute function after interval milliseconds
Example:

Drag and drop [top]

Learn best through examples? Check out:

AJS.drag_obj

When dragging begins this object holds some useful information.
AJS.drag_obj.args:
The args that are passed to AJS.dragAble
AJS.drag_obj.click_elm:
The element that the user has clicked on.
AJS.drag_obj.mouse_pos:
The initial mouse position, as {x: mouse_pos_x, y: mouse_pos_y}.

AJS.drag_elm

The cloned element that is dragged.

AJS.dragAble(element, handler, args)

Make element drag able.
handler:
a DOM element that should handle the dragging. Optional.
args:
All args are optional.
  • move_x: Enable horizontal move. Default true.
  • move_y: Enable vertical move. Default true.
  • moveable: Should the element be moveable. Default false.
  • hide_on_move: Hide the click_elm on drag. Default true.
  • on_mouse_up: Function that is triggered on mouse up.
    Signature of this function is on_mouse_up(click_elm, drag_elm, event).
  • on_drag: A callback that is triggered when a dragable is dragged.
    Signature of this function is on_drag(click_elm, drag_elm, event).
  • cursor: The cursor that should be set on element.
  • max_move: Limit of the move. Default {'top': null, 'left': null}, i.e. no limit.
Example:

AJS.dropZone(element, args)

Make element to a drop zone.
args:
  • on_hover: A callback that is triggered when a dragable is hovering the dropzone.
    Signature of this function is on_hover(drop_zone_elm, click_elm, drag_elm).
  • on_drop: A callback that is triggered when a dragable is dropped on dropzone.
    Signature of this function is on_drop(drop_zone_elm, click_elm, drag_elm).
Example:

Miscellaneous functions [top]

AJS.keys(object)

Returns the keys 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 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.loadJSONDoc 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."