A tiny object wrapper around the DOM, targeted at replacing the core of the manipulations found inside jQuery, and providing a collection API on top of it. The hope is that the core DOM manipulations could become popular enough to be incorporated as an abstracted set of DOM manipulations inside jQuery.
An important point of information. The vast majority of the logic that is resides in the DOM manipulations methods provided by Wield is either taken directly from jQuery Core or Sizzle and all credit for the time, effort and code belongs to the contributors to both of those fine projects. The goal here is not to reproduce that effort but rather to abstract it and the value it provides.
The primary goals of this project are to be exceptionally modular with a preference toward building a custom stack as a means to reduce size, fast parsing and method execution from the start, and to keep the collections API separate from the DOM manipulation API.
- Abstraction of collections and DOM manip
- Modularity at the method level (AMD, builder)
- Parsing performance
- Method performance
- Size min'd and gzip'd
- Type checked (closure compiler)
The core of the library is a lightweight object wrapper for DOM elements. The goals for this portion are:
- jQuery Browser support parity
- Pass jQuery's DOM manipulation test suite
- Single invocation pattern per method
Samples of stand alone use:
var div = new Wield.Dom( document.getElementByName("div") ), span = document.createElement( "span" ); div.append( span ); // <div><span></span></div> div.empty(); // <div></div> div.wrap( span ); // <span><div></div></span> // or ... div.append( span ).empty().wrap( span );
Standalone vs Object Receiver
In the interest of facilitating testing with the jquery core test suite each of the manipulation methods can be invoked on a instance of the Dom object constructor and as a standalone function on the prototype. Eg:
var fixture = new Wield.Dom( document.getElementById("foo") ); fixture.remove(); // or ... Wield.Methods.remove( document.getElementById("foo") );
For methods that accept at least one argument,
Wield.Dom methods will accept either DOM or
Wield.Dom objects when invoked with an object receiver and DOM elements when invoked as a function.
var fixture = new Wield.Dom( document.getElementById("foo") ); fixture.append( document.createElement("span") ); // or ... fixture.append( new Wield.Dom(document.createElement("span")) ); // or ... Wield.Methods.append( document.getElementById("foo"), document.createElement("span") );
By defining the
Wield.Dom.finder function (which uses
querySelector by default in browsers that support it), the user can simplify
Wield.Dom object creation, Eg:
var fixture = Wield.Dom.find( "#foo" ); fixture.remove();
Alternatively you could use sizzle for the finder function, eg:
Wield.Dom.finder = window.Sizzle; var fixture = Wield.Dom.find( ":not([that='crazy'])" ); fixture.remove();
The collections portion of the library is meant to be a jQuery-ish usability layer for selection and collection manipulation
- Provide a drop in replacement for jQuery methods that would use the core
- Selector engine abstraction (querySelector/Sizzle)
Wield.finder = document.querySelectorAll; var divs = Wield.find( "body > div" ); divs.addClass( "foo" ); // <div class='foo'></div><div class='foo'></div> Wield.finder = Sizzle; divs = Wield.find( "span:visible" ); divs.addClass( "foo" ); // <span class='foo'></span>
Inevitably users will need or want simple things, like element creation, that are streamlined and cross platform. The goal is to keep this separate.
var newDiv = Wield.create( "<div/>" ); Wield.find( "span" ).append( newDiv );
There are few things that are yet to be decided about how the library should work:
- Should the prototype functions return the element being operated on for the sake of composition?
- Is it worth supporting many invocation patterns (ie, should it just be functions)? More specifically what is the real cost of supporting both?
- Are there other libraries that focus on replacing the browsers DOM manipulation API?
- Is there interest in the library by itself?
There are outstanding items of work that need to be put into place for the project to achieve it's goals:
- Size regression testing
- Performance regression testing
- Cross browser automated testing (testswarm)
- Sample DOM manip
- Node based amd builder
- Sort out build vs amd include issues (eg, excluding returns with pragmas)