Cashcash NPM | npm.io

CashCash

CashCash is a very small DOM library inspired by jQuery. The project's primary goal is to smooth over some of the rough edges in JavaScript's native DOM querying methods.

Key Features

Uses JavaScript's native querySelectorAll method
Dependency-free
AMD/Node module support

CashCash is also really tiny:

Getting CashCash

Adding CashCash to your project is easy! You've got a couple options:

Download a tagged version from GitHub and do it yourself (old school).
Install via Bower: bower install cashcash
Install via npm: npm install cashcash

Usage

CashCash takes a similar approach to DOM selection as the aforementioned (and insanely popular) jQuery.

CashCash('p');          // select all `<p>`s on a page
CashCash('#main');      // select the element with the ID of `main`
CashCash('p', '#main'); // select all `<p>`s within an element with the ID of `main`

CashCash takes two arguments: a selector (a string) and an optional context (a string or an HTMLElement). For basic DOM selection, you should be fine passing in any supported CSS selector. For more advanced usage, the second context argument might prove useful:

var divs = CashCash('div');              // select all `<div>`s on a page
var paragraphs = CashCash('p', divs[0]); // select all `<p>`s within the first `<div>`

Under the covers, CashCash uses the browser's native querySelectorAll method and therefore supports the same CSS selectors.

When selecting DOM nodes based on the provided selector string, CashCash will store references to those selected DOM elements on itself in an array like fashion for easy access to individual DOM nodes.

Given the following markup:

<p>Paragraph 1</p>
<p>Paragraph 2</p>
<p>Paragraph 3</p>
<p>Paragraph 4</p>
<p>Paragraph 5</p>

You can do the following:

var paragraphs = CashCash('p');

console.log(paragraphs[0]); // logs `<p>Paragraph 1</p>`
console.log(paragraphs[1]); // logs `<p>Paragraph 2</p>`
…
console.log(paragraphs[4]); // logs `<p>Paragraph 5</p>`

Properties and Methods

`length`

For all queries (valid or otherwise), CashCash will return the length (defaulting to 0) of the queried elements.

var thisManyBodyElements = CashCash('body').length; // returns `1`

`toArray()`

JavaScript's native querySelectorAll method returns a NodeList which is like an array, but lacks at least one useful feature of arrays: the forEach method. To ease that particular pain, CashCash objects can be converted to arrays:

var paragraphsArray = CashCash('p').toArray();

You can now use any of JavaScript's native array methods. For instance, you can then iterate over the array of HTMLElements:

CashCash('p').toArray().forEach(function(el) {
    console.log(el);
});

`selector`

As best as possible, CashCash keeps track of the selector used in a given query, making it available to you by calling:

console.log(CashCash('p').selector);                // logs the string `p`
console.log(CashCash('p', '#container').selector);  // logs the string `#container p`
console.log(CashCash('p', document.body).selector); // logs the string `p`

`context`

CashCash makes available a reference to the context for a given query (if one is provided and that context is an HTMLElement). If no context is given (or if the given context is a string), CashCash will default to HTMLDocument.

console.log(CashCash('p').context);                // logs a reference to `HTMLDocument`
console.log(CashCash('p', '#container').context);  // logs a reference to `HTMLDocument`
console.log(CashCash('p', document.body).context); // logs a reference to `<body>`

var container = CashCash('#container');

console.log(CashCash('p', container[0]).context); // logs a reference to `<div id="container">`

Tips and Tricks

Mimicking jQuery

If you want to cut down on some typing (and potentially confuse your teammates), you can reassign CashCash to $ to mimic jQuery:

<script src="./dist/cashcash.js"></script>
<script>
    (function($) {
        var paragraphs = $('p');

        …
    })(CashCash);
</script>

Using with `instanceof`

To determine whether or not a variable is a CashCash object, use instanceof:

var divs = CashCash('div');

console.log(divs instanceof CashCash); // logs `true`

Browser Support

CashCash works in all modern browsers.

It makes use of the querySelectorAll method which first appeared in Internet Explorer in version 8. To avoid throwing JavaScript errors in browsers that don't support this method, you can cut the mustard:

if ('querySelector' in document) {
    // Your scripts here…
}

Acknowledgments

CashCash is inspired by jQuery and the many micro DOM libraries it inspired (like Ken Wheeler's cash, for instance).

CashCash is written and maintained by Jason Garber and is another in a growing line of small, curiously-named JavaScript utilities:

RadioRadio, a very basic PubSub library.
RouterRouter, a routing library extracted from Backbone's Router.

License

CashCash is freely available under The MIT License. Use it, learn from it, fork it, improve it, change it, tailor it to your needs.

@everything-registry/sub-chunk-1297

5 months ago

7 years ago

8 years ago