16 February 2012
- builder
- html
- javascript
- jquery
Which web developer never built DOM elements programmatically? It’s a mess, doesn’t is?
Well, it was a lot worse in the past. When the only way to do that was appending strings or with the standard Document Api (Document#createElement, Document#appendChild …). But In the past few years the things got better. Javascript Frameworks emerged and one of the them was the well know jQuery.
jQuery has a smarter API to build DOM elements. The main advantage of using jQuery is the method chaining. But is out there a better approach ? I was seeking for one and I found just a few projects, one of them was jquery.builder from Jeremy Ruppel, a new but promising project. One week later I was helping her to evolve it.
Usage
To start building, use the build method. You can give this build method a block.
$( '#context' ).build( function( )
{
this.div( 'hello!' );
} );
$( '#context' ).html( ); // = <div>hello!</div>
In this block and any child blocks, this refers to the builder instance. The same builder instance will also be passed to the block if you want to name the reference.
$( '#context' ).build( function( b )
{
b.div( 'hello!' );
} );
The builder object has a method for every common html tag, but you can add your own tag methods easily (more on that later).
For building node hierarchies, you can give any tag method a block and the builder will adjust its scope appropriately:
$( '#context' ).build( function( )
{
this.div( function( )
{
this.div( 'nested' );
} );
this.span( function( )
{
this.a( 'hierarchy' );
} );
} );
$( '#context' ).html( ); // => <div><div>nested</div></div><span><a>hierarchy</a></span>
Scope can be nested as deeply as you want. Go crazy.
You can pass a hash of options to any tag method and those key-value pairs will be added as attributes to the created node.
$( '#context' ).build( function( )
{
this.a( { href : 'github.com' } );
} );
$( '#context' ).html( ); // => <a href="github.com"></a>
The options hash may also be passed after the node text, like:
$( '#context' ).build( function( )
{
this.a( 'github rules', { href : 'github.com' } );
} );
$( '#context' ).html( ); // => <a href="github.com">github rules</a>
If you need the reference to the current scope DOM element you can use the $ variable. For Example, to add a mouse click event to an element:
$( '#context' ).build( function( )
{
this.span(function ( )
{
this.text( 'Click Me' );
this.$.click(function( )
{
alert( 'Hello There!' );
} );
} );
} );
If you’re building XML, you’re going to need some custom tags. jquery.builder can be set up to build any tag that isn’t a reserved word. Just pass your tag name to the build method and it will be available on any new builders.
$( '#context' ).build( 'custom' );
$( '#context' ).build( function( )
{
this.custom( 'sweet' );
} );
$( '#context' ).html( ); // => <custom>sweet</custom>
If at any point you need to reset the tag list to the defaults, just pass false to the build method.
Right now, custom tags are shared between all builder instances regardless of their context node.
Expressions Syntax
Expressions is the easiest way to create nested elements. Using it you don’t need to specify a function to every nested object. You can also mix expressions style with the standard builder style.
$( '#context' ).build( function( )
{
this( 'body div ul', function ( )
{
this( 'li', function ( )
{
this.a( function ( ) { this.text( 'Hello World' ); }, { class: 'text' } );
} );
} );
} );
$( '#context' ).html( ); // <body><div><ul><li><a>Hello World</a></li></ul></div></body>
If the tag name is omitted but a class or id is present it will infer a div element, for example:
$( '#context' ).build( function( )
{
this( '.foo', 'Hello, Foo!!!' );
} );
$( '#context' ).html( ); // <div>Hello, Foo!!!</div>
The source code and documentation is available: on the Github page. Any question or suggestion are welcome.
