API Documentation

Welcome the XUI documentation. This is generated from inline documentation in the XUI javascript source.

Basics

XUI is available to the entire document as x$. It is a function, that accepts a query selector. The syntax is mostly chainable and should be familiar to anyone who has worked with jQuery.

x$('a.navigation').css({ background:'blue' });

The query selection engine is based on the browser implementation of querySelectorAll so its fast. Real fast. XUI allows for a single expression, an element or an array of elements to be passed

x$(window);                         // The Window
x$(element);                        // An Existing Element  
x$('ul#globalnav li a.selected');   // A CSS3 Selector
x$(['li','div#foo']);               // An Array of Selectors
x$('li','.selected','#some_id');    // A comma list of CSS3 Selectors

Dom

Manipulating the Document Object Model aka the DOM.

For manipulating HTML markup in the DOM.

html

Adds elements or changes the content of an element on a page. This method has shortcut aliases:

inner
outer
top
bottom
before
after
remove

syntax:

    x$(window).html( location, html );

or this method will accept just an html fragment with a default behavior of inner..

    x$(window).html( htmlFragment );

arguments:

location:string can be one of 'inner', 'outer', 'top', 'bottom', 'before', 'after' or 'remove'
html:string any string of html markup or HTMLElement
Note: This method has some magic, if you pass a sting into the top of a list, we assume you want a list item.

example:

x$('#foo').html( 'inner',  '<strong>rock and roll</strong>' );
x$('#foo').html( 'outer',  '<p>lock and load</p>' );
x$('#foo').html( 'top',    '<div>bangers and mash</div>');
x$('#foo').html( 'bottom', '<em>mean and clean</em>');
x$('#foo').html( 'remove'  '<h1>first and last</h1>');

    x$('#foo').html('<p>sweet as honey</p>');

    

x$('#foo').inner('<strong>rock and roll</strong>' );
x$('#foo').outer('<p>lock and load</p>' );
x$('#foo').top('<div>bangers and mash</div>');
x$('#foo').bottom('<em>mean and clean</em>');  
x$('#foo ul li').remove();

Removes all erronious nodes from the DOM.

Event

A good old fashioned event handling system.

on

Registers a callback function to a DOM event on the element collection.

This method has shortcut aliases for:

click
load
touchstart
touchmove
touchend
touchcancel
gesturestart
gesturechange
gestureend
orientationchange

For more information see:

http://developer.apple.com/webapps/docs/documentation/AppleApplications/Reference/SafariWebContent/HandlingEvents/chapter7section1.html#//appleref/doc/uid/TP40006511-SW1

syntax:

    x$('button').on( 'click', function(e){ alert('hey that tickles!') });

or...

    x$('a.save').click(function(e){ alert('tee hee!') });

arguments:

type:string the event to subscribe to click|load|etc
fn:function a callback function to execute when the event is fired

example:

x$(window).load(function(e){
  x$('.save').touchstart( function(evt){ alert('tee hee!') }).css(background:'grey'); 
});

Style

Anything related to how things look. Usually, this is CSS.

Sets a single CSS property to a new value.

setStyle

syntax:

x$(selector).setStyle(property, value);

arguments:

property:string the property to modify
value:string the property value to set

example:

x$('.txt').setStyle('color', '#000');

Retuns a single CSS property. Can also invoke a callback to perform more specific processing tasks related to the property value.

getStyle

syntax:

x$(selector).getStyle(property, callback);

arguments:

property:string a css key (for example, border-color NOT borderColor)
callback:function (optional) a method to call on each element in the collection

example:

x$('ul#nav li.trunk').getStyle('font-size');

x$('a.globalnav').getStyle( 'background', function(prop){ prop == 'blue' ? 'green' : 'blue' });

Adds the classname to all the elements in the collection.

addClass

syntax:

$(selector).addClass(className);

arguments:

className:string the name of the CSS class to apply

example:

$('.foo').addClass('awesome');

Removes the classname from all the elements in the collection.

removeClass

syntax:

x$(selector).removeClass(className);

arguments:

className:string the name of the CSS class to remove.

example:

x$('.bar').removeClass('awesome');

Set a number of CSS properties at once.

css

syntax:

x$(selector).css(object);

arguments:

an object literal of css key/value pairs to set.

example:

x$('h2.fugly').css({ backgroundColor:'blue', color:'white', border:'2px solid red' });

Fx

Animations, transforms and transitions for getting the most out of hardware accelerated CSS.

Tween is a method for transforming a css property to a new value.

tween

syntax:

x$(selector).tween(obj);

arguments:

properties:object an object literal of element css properties to tween or an array containing object literals of css properties to tween sequentially.

example:

x$('#box').tween({ left:100px, backgroundColor:'blue' });

x$('#box').tween([{ left:100px, backgroundColor:'green', duration:.2 }, { right:100px }]);

x$('#box').tween({ left:100px}).tween({ left:100px });

XHR

Remoting methods and utils.

The classic Xml Http Request sometimes also known as the Greek God: Ajax. Not to be confused with AJAX the cleaning agent. This method has a few new tricks. It is always invoked on an element collection. If there no callback is defined the response text will be inserted into the elements in the collection.

xhr

syntax:

    xhr(url, options);

options:

method {String} [get|put|delete|post] Defaults to 'get'.
async {Boolen} Asynchronous request. Defaults to false.
data {String} A url encoded string of parameters to send.
callback {Function} Called on 200 status (success). Defaults to the Style.html method.

example:

x$('#status').xhr('/status.html');
x$('#left-panel).xhr('/panel', {callback:function(){ alert() }});

Another twist on remoting: lightweight and unobtrusive DOM databinding. Since we are often talking to a server with handy JSON objects we added the convienance the map property which allows you to map JSON nodes to DOM elements.

xhrjson

syntax:

    xhrjson(url, options);

example:

The available options are the same as the xhr method with the addition of map.

    x$('#user').xhrjson( '/users/1.json', {map:{'username':'#name', 'image_url':'img#avatar[@src]'} });