lfortin edited this page Mar 25, 2012 · 18 revisions
Clone this wiki locally

This is documentation on the Drive jQuery plugin.

How it works

The Drive jQuery plugin allows you to construct the DOM using basic jQuery selectors.
It searches for elements, and if none is found, it attempts to create them. In any cases where elements have been found or created, they are returned.

The plugin officially supports jQuery 1.3.x and later versions.

The plugin supports selectors containing:

  • #id
  • element tag
  • .class
  • .class.class
  • “ancestor descendant” hierarchy
  • “parent > child” hierarchy

$(selector [, context]).drive();

$(…).drive() as a jQuery method, available for jQuery 1.3.x and later versions.

If no element has been found, any selector, and if applicable, context, will be interpreted to create the same elements structure as wanted.

Examples, assuming a default tag = ‘div’:

With $('#some_container > div.any-class').drive();, inside a container with id ‘some_container’, you will obtain a div with class ‘any-class’.

With $('div#div-id .class1.class2 > span.class3').drive();, inside a container div with id ‘div-id’, you will obtain a div with classes ‘class1’ and ‘class2’, and that div will contain a span with class ‘class3’.

With $('.class1', $('#some_container')).drive();, inside a container with id ‘some_container’, you will obtain a div with class ‘class1’.

Found or created elements are always returned at the end so it is possible to do something else after:

Note that ‘context’ parameter can be a selector, a DOM element or a jQuery set. Support for an HTML document as context is planned in a future version.

$(selector [, context]).drive(effect [, arguments]);

Since release 1.1.0, an effect can be called when showing new elements, for example:

// .fadeIn() effect

// with arguments: .fadeIn('slow', callback)
$('.some-message-box').drive('fadeIn', 'slow', callback);

// using a jQuery UI effect (requires the jQuery UI library)
$('.some-message-box').drive('show', 'explode', { }, 3000, callback);

$(selector [, context]).drive(callback);

A callback can also be set to be triggered when new elements have been created, for example:

$('#some_container > div.any-class').drive(function(event) {
  the callback is actually a 'drive:success' custom event,
  so 'this' represents the new element

  return false; // if you want to cancel event bubbling, when many elements have been created

$(selector [, context]).drive(options);

For explicit options, look at bottom of page.

$.drive(selector [, context] [, callback]);

$.drive(…) as a jQuery function, available for all versions of jQuery. Although they are not supported, the plugin offers some backward compatibility for versions earlier than jQuery 1.3.

It works the same way as the jQuery method version.

$.drive('#some_container > div.any-class');

$.drive('div#div-id .class1.class2 > span.class3');

$.drive('#some_container > div.any-class', function() {...});


For explicit options, look at bottom of page.


Here are all the default options that can be changed when using $(...).drive(options) or $.drive(options):

$(selector, context).drive({
    selector: '.selector', // selector (not applicable if using the plugin as a jQuery method)
    context: document, // selector or DOM element or jQuery set (not applicable if using the plugin as a jQuery method)
    defaultTag: 'div', // string. default element tag to use
    inputType: 'text', // string. type to be applied to created inputs
    insertMethod: 'append', // string: 'append', 'prepend'. method to use when inserting new elements
    showMethod: 'show', // string or array: effect to use when showing new elements
    html: [content], // Sets content to innermost created element. Same as jQuery's .html() method.
    attr: { }, // object. attributes to set on each created element
    css: { }, // object. inline styles to set on each created element
    force: false, // boolean. ignore unknown context if set to true
    success: function(event, driveObject){ }, // function. callback triggered on each created element if all went successful
    except: function(error, driveObject){ } // function. callback triggered when a JavaScript error occurs. Mostly for devel/internal use.


It is also possible to define your own default options:

    // example of custom default options
    insertMethod: 'prepend',
    css: {
        backgroundColor: 'blue',
        cursor: 'pointer'
    success: function() {
        alert('element with id ' + this.id + ' was created');
        return false;

Note that $.driveOptions() always returns the current custom default options:

var myDefaultOptions = $.driveOptions();

Using the plugin with Node.js

The plugin can also be used with Node.js, in conjunction with the jsdom module:

Drive jQuery plugin and jsdom can be installed from npm:

npm install jsdom
npm install jquery-drive


var jsdom = require(‘jsdom’),
$ = require(‘jquery-drive’);

// create a new HTML document
var doc = jsdom.jsdom();

// create some stuff into document
$(‘div#container1 span a#link-to-github’, doc).drive({
success: function() {
if($(this).is(‘div’)) {
console.log(‘New div created!’);
if($(this).is(‘span’)) {
console.log(‘New span created!’);
if($(this).is(‘a’)) {
console.log(‘New link created!’);
$(this).attr({’href’: ‘http://www.github.com’});
// more stuff
$(“#container2 form#form1 input#text1”, doc).drive();
$(“form#form1 input#submit1”, doc).drive({inputType: ’submit’});

// inspect document body content
console.log(‘Inside new document:’, $(‘body’, doc).html());