Hosted on Github

Voyeur.js

Taking a closer look at the document's body.

Voyeur is a tiny Javascript library that lets you traverse and manipulate the DOM the way it should have been. Voyeur.min.js (1.2kb)

Transverse.the.DOM

Voyeur allows you to traverse the DOM via the dot operator like you would any Javascript object. This makes for a streamlined and native experience like it always should have been.

Element creation

One of the most useful components of Voyeur is its element creation interface. Using some Javascript getter magic, you can create and append elements by simply naming and chaining them.

Always an element

Whenever you're dealing with Voyeur, it's always a node or an array of nodes. One of the main goals of Voyeur was to abstract as little as possible from the DOM and keep things clean.


FAQ

Which browsers does Voyeur support?

Voyeur is tested in and supports all the latest, major browsers (IE10, Chrome, Firefox, Safari, Opera).

How does it work?

Voyeur works by utilizing object getter functions to expose an element's children via their tag names on itself.

What?! You expose every element's children onto itself?

Nope! An element's children is only exposed when it's required so only the elements used will be Voyeur'fied.

Does that pollute the element's object with lots of properties?

You'd be surprised at how little overhead there is left on the elements. When used correctly, Voyeur's footprint on an element can be reduced significantly (and it's not very hard to use it right).

Why should I use this instead of, say, jQuery?

Personally, I usually avoid huge libraries because I never use half of the great tools provided. Voyeur does one job and it does it well, in a friendly way too which is always a plus.

Where can I get code?

Voyeur is hosted on Github. Feel free to fork and create a pull request!

I have a suggestion, where do I put it?

Awesome! I'd love to hear it. You can email me, tweet it to me or create an issue on Github.


API

Voyeur document.body

The global Voyeur is the document body and all element tags queried via the dot operator are descendants. It acts as the root Voyeur.

Voyeur.tag.. HTMLElement|Array

Voyeur allows you to access document nodes via their tag name. If multiple elements of the same tag list exist, an native array of elements is returned otherwise a HTMLElement (or node) is returned. Chaining is acceptable and encouraged.

Voyeur.div.h1; //body>div>h1. Returns h1 element.
Voyeur.div.h1.innerHTML = "wobblewobble"; //..

Voyeur.find( selector ) HTMLElement|Array

Voyeur.find acts as a proxy for querySelectorAll and returns a Voyeur'ified node or array of nodes.

Voyeur.find("#example"); //Single node returned
Voyeur.find(".example"); //Array of nodes returned if more than one, otherwise a node
Voyeur.find("#example").h1.em; //Chaining acceptable

Voyeur.tag...find( selector ) HTMLElement|Array

Scoped find's are also acceptable.

Voyeur.div.find(".example"); //Scoped query selector all

Voyeur.tag...use( callback(element) ) Root HTMLElement

Use a the current node or array of nodes within a closure. Returns the root node.

Voyeur.div.ul.li; //Returns a list of list items
Voyeur.div.ul.li.use(); //Returns div element
Voyeur.div.ul.li.use(function(li, i) {
	//Loop over the list items
	li.textContext = "List item #" + i;
});

Voyeur.div.ul.use(function(ul) {
	ul.style.background = "blue";

	//Continue using the ul
	ul.li; //..
});

Voyeur.tag...eq( begin , end ) HTMLElement|Array

When an array of elements is returned, eq allows you to operate on a single element in a list or a range of elements.

Voyeur.ul.li; //List of 10 li elements
Voyeur.ul.li.eq(3).innerText = "Fourth li element!";

Voyeur.ul.li.eq(3, 9).use(function(li, i) {
	li.create.em.innerText = "Emphasized text!";
});

//Alternatively use forEach, remember it's a native array!
Voyeur.ul.li.eq(3, 9).forEach(function() { ... });

Voyeur.create.tag.. HTMLElement|Array

The root Voyeur.create object. Any valid HTML tag can be queried via the dot operator on this object and an element of that tag will be created. Note: Elements created here will not be appended into the root. They are orphans. It's up to you to place them.

Voyeur.create.div; //Returns a div element
Voyeur.create.div.h1; //Returns a h1 element with div parent
Voyeur.create.div.h1.em; //etc

Voyeur.create.tag...mult( factor ) Array

During the creation process you may want more than one element. mult allows you to multiply the current node by a factor.

Voyeur.create.ul.li.mult(10).use(function(li, i) {
	li.innerHTML = "Created list items!";
});

//Use in conjuction with eq
Voyeur.create.ul.li.mult(10).eq(5).innerHTML = "The 6th item.";

Voyeur.create.special( tag ) HTMLElement

Due to some namespace clashes, some tag names had to be moved to a function. These tag names include: script and style.

Voyeur.create.special("style"); //Returns style element

Voyeur.tag...create.tag.. HTMLElement|Array

Elements can also be created within a scope. Whenever create is used on an element, any elements created are appended into this element as a parent. All of the above functions apply.

Voyeur.div.create.h1.innerHTML = "Hello world!"; //Create a h1 and appends it into the div

Voyeur.div.create.ul.li.mult(10).use(function(li, i) {
	li.innerHTML = "wtf is with the li elements";
});