Peppy - Documentation

The Peppy API:

query( String selector,[String|Element context] ) : Array<Element>

Takes a selector and optionally a context from which to start the search (defaults to window.document), and returns an array of all elements that match the selector. This function handles groups, simple selectors, and combinators. It is the only function in Peppy that handles groups. It dispatches simple selector's into querySelector, and combinators into queryCombinator. For most users, this is probably the one that you will want to use.

$( String selector,[String|Element context] ) : Array<Element>

Alias for query.

querySelector( String simpleSelector,[String|Element context] ) : Array<Element>

Takes a simple selector and optionally a context from which to start the search, and returns an array of all elements that match the selector.

queryCombinator( Array<Element> left,Array<Element> right,String combinator ) : Array<Element>

Takes two lists of elements and a combinator and runs the combinator test for each element in right on each element in left.

Top

Using Peppy:

Peppy is a CSS3 compliant selector engine. This means that it selects Elements from the DOM using CSS3 selectors to describe them.
I will not cover here all of the different selectors, there is an excellent specification that enumerates them and how they function. I will however, discuss many of them and provide examples.

The first thing that you need to do to use peppy is load it into your document:

Here is an example of Peppy in use:

<html>

<head>

window.onload = function() {

var example = $('div.example')[0];
// do some stuff to the node.

}

</script>

</head>
<body>

</body>

</html>

... More to come soon.
Top

Using Peppy with other libraries:

If you intend to use the '$' variable as a shorcut for Peppy beware that Peppy will not overwrite this variable. If Peppy is the only library you are using then this will be fine, Peppy will assign a reference of Peppy.query to '$'. If you are using Peppy with other libraries though, the safest bet is to force an assignment of '$' to Peppy.query after all scripts are loaded.

<html>

<head>

$ = Peppy.query;

</script>

</head>
<body>

...

</body>

</html>

If you wish to use Peppy as the selector engine in your own library you could take a few different approaches. I will reccomend taking the entire source of Peppy and placing it at some point prior to your first intended use. However, another valid approach would be to dissect the source of Peppy and use the parts that you chose. Be aware though that Peppy uses a closure to hide private methods and variables that it does not want exposed, so this is a potential place for hiccups to occur for this approach.

If you wish to use Peppy as the selector engine in another library, I will give you a few helpful suggestions here. I will use jQuery as an example as I have received the most requests for an example of how to do this with jQuery. I should note that this is not supported by the jQuery team and this has been only minimally tested by myself.

The first thing that you need to do is locate the selector engine API in your library. In jQuery (as of v1.2.6 anyway) this is jQuery.find. The next thing to do is overwrite the assignment to jQuery.find with a reference to Peppy.query.

Here is an example:

<html>

<head>

jQuery.find = peppy.query;

</script>

</head>
<body>

example 1

</div>
<div class="example">

example 2

</div>
<div class="example">

example 3

</div>

</body>

</html>

That's it. jQuery will now use Peppy as its selector engine. Now you can do things like:

$('.example').each(function(){
...
});

and you are using Peppy to get the nodes, and jQuery to apply the anonymous function to each element found from the query.
Top

Peppy Documentation ---