@projectDescription XUI JavaScript library for mobile web applications.
@author Rob Ellis rob.ellis@nitobi.com @author Brian LeRoux brian.leroux@westcoastlogic.com @author Brock Whitten brock@sintaxi.com
@version 0.1
We hear your words. Why another JavaScript framework?! When development of PhoneGap was under way we noticed slow load times for modern JavaScript frameworks (such as Prototype, MooTools, YUI, Ext and (yes) even jQuery. A big reason why these libraries are so big is because is mostly they contain a great deal of cross browser compatability code. The mobile space has less browser implementations (so far) and different needs. Thus XUI.
XUI strives to be a framework for first class mobile device browsers such as WebKit, Fennec and Opera with future support under consideration for IE Mobile and BlackBerry.
- Rob Ellis
- Brock Whitten
- Brian LeRoux
Minified code is less than 6k!
Clone the source from GitHub:
git clone git://github.com/brianleroux/xui.git
To build xui: run rake in the shell of your choice from the root of the project directory. (This requires Ruby.)
There are other tasks for code minification, running the specs and generating docs. Run rake -T to see them all.
Check out the example directory for a comprehensive example application. Specs are in the spec directory.
Welcome the XUI documentation. This is generated from inline documentation in the XUI javascript source.
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);
x$('ul#globalnav li a.selected');
x$(['li', 'div#foo']);
Returns the first element in the collection.
@return {Element} Returns a single DOM element.
@namespace {Dom} @example
Manipulating the Document Object Model aka the DOM.
For manipulating HTML markup in the DOM.
@method @param {location} [inner|outer|top|bottom|remove] @param {html} A string representation of HTML markup. @return {Element Collection} @example
Adds elements or changes the content of an element on a page. This method has shortcut aliases:
- inner
- outer
- top
- bottom
- 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
- html:string any string of html markup or HTMLElement
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>');
or
x$('#foo').html('<p>sweet as honey</p>');
Removes all erronious nodes from the DOM.
@method @return {Element Collection} @example
Walks the Element Collection removing empty nodes and whitespace.
syntax:
x$(selector).clean();
example:
x$(window).clean();
@namespace {Event} @example
A good old fashioned event handling system.
Register callbacks to DOM events.
@method @param {Event} The event identifier as a string. @param {Function} The callback function to invoke when the event is raised. @return {Element Collection} @example
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:
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');
});
@namespace {Style} @example
Anything related to how things look. Usually, this is CSS.
Sets a single CSS property to a new value.
@method @param {String} The property to set. @param {String} The value to set the property. @return {Element Collection} @example
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.
@method @param {String} The property to retrieve. @param {Function} A callback function to invoke with the property value. @return {Element Collection} @example
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.
@method @param {String} The class name. @return {Element Collection} @example
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.
@method @param {String} The class name. @return {Element Collection} @example
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.
@method @param {Object} An object literal of CSS properties and corosponding values. @return {Element Collection} @example
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' });
@namespace {Fx} @example
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.
@method @param {Object} [Array|Object] @return {Element Collection} @example
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 });
@namespace {Xhr} @example
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.
@method @param {String} The URL to request. @param {Object} The method options including a callback function to invoke when the request returns. @return {Element Collection} @example
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(e){ alert(e) }});
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.
@method @param {String} The URL to request. @param {Object} The method options including a callback function to invoke when the request returns. @return {Element Collection} @example
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]'} });
- xui-app merge
- look into extend method buggyness
- get jslint passing
- look into activejs doc build system and enhance to generate side by side code like ubiquity
- generators
- canvas progressive enhancement
- prop should be js property insted of a css property
feb 04, 2009
- started scriptdoc
- added Dom.html method alias shortcuts for: inner, outer, top, bottom and remove
jan 30, 2009
- Fixed bug in html.wrap private - createAttributes was broken
jan 22, 2009
- Full support for HTMLElement in DOM.html()
jan 21, 2009
- fixed DOM
- added remove
Jan 18, 2009
- more documentation for core, etc
- after cat getting out of the bag on ajaxian we're working furiously to get this production ready
Jan 13, 2009
- merged robs fixes and cleanup
Jan 11, 2009
- added mobile safari events (these will need testing in android, etc)
- cleaned up Dom.html and documented
- documented event a little
Jan 10, 2009
- removed Dom.clean for now
- made Dom.getTag and Dom.wrap private
- documented Dom
- more Dom tests
Jan 9, 2009
- more docs for xui core, xhr, style and fx
Jan 7, 2009
- style spec passing
- xui app phase one
- testing approch resolved
- hasClass now private
Jan 6, 2009
- rock out with renewed authority
- better docs we promise
- create doc/index.html from markdown
Copyright (c) 2008 Brian LeRoux, Brock Whitten, Rob Ellis
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.