Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/foxbunny/justils

Justils are just some utils for working with DOM, DOM events, and related API.
https://github.com/foxbunny/justils

Last synced: 28 days ago
JSON representation

Justils are just some utils for working with DOM, DOM events, and related API.

Awesome Lists containing this project

README 

        
# Justils



Justils are just some utils for working with DOM, DOM events, and related API.



## Features



Justils have the following features:



 + Curried functions

 + No unnecessary fixes or enahncements to vanilla DOM API

 + Lightweight

 + Modular (supports AMD loaders)

 + MIT-licensed



### Curried functions



Most functions are [curried](http://en.wikipedia.org/wiki/Currying). This means

you can quickly whip up new functions that have some of the arguments

rememebered (a.k.a. 'partial application of arguments')and use them as your

custom library. For example:



    var getSelected = just.byClass('selected');

    getSelected(myDOMNode); // Gets all .selected elements under myDOMNode



This design comes from my personal desire to reduce the amount of boilerplate

while still being flexible enough to add new features and shortcuts as I go.

The obvious lack of different functions in Justils comes from the fact that

it's super-easy to create new ones on the fly.



### No unnecessary fixes or enhancements



Justils is designed to be as close to DOM API as possible. Except for event

handling (still work in progress), it does not add polyfills, shims, or other

fixes to make the API work the same way across all platforms. For example, if

the native implementation returns a `NodeList`, that is what you will get. If 

it returns a `StaticNodeList`, again, that is what you will get. It

doesn't try to wrap them in a complex object to normalize the API.



### Lightweight



Justils is made lightweight by throwing away things for which there are better

alternatives. It doesn't do AJAX, or animation.



It's just over 8kb (at the moment) with no compression or gzipping.



### Modular



Although the `helpers` module is required by some of the other modules, you can

use most of the modules stand-alone. If you don't need DOM traversing

functions, simply omit that module. The modules are all loadable using AMD

loaders such as [RequireJS](http://requirejs.org/).



### MIT-licensed



Justils are licensed under MIT license. See the `LICENSE` file in the sources

for more information.



## Browser support



Currently known to work with IE8+, newer versions of FireFox, Chrome, and

Opera. If you find something that doesn't work, please run the unit tests (you

need Testem).



## When/why should I use Justils?



Jutils requires you to know the DOM API in order to take full advantage of it.

It does not abstract all of the API (e.g., it doesn't even have an alias for

`querySelector` and `querySelectorAll`, which has decent cross-browser support

within Justils' support target). It is also good in scenarios where bundling

over 100kb of libraries just to do basic things in your application is not an 

option. Other than that, it's a new library, so it still hasn't proved its

versatility. All I can say is: it works for me. :)



## Basic usage



All Justils functions are housed under the `just` global (or whatever variable

you assign it to when using AMD loaders).



### Selecting DOM nodes by some id



    // traverse module

    var myNode = just.byId('some-id');



### Selecting DOM nodes under some node by some class



    // traverse module

    var myNodes = just.byClass('some-class', myNode);



### Selecting DOM nodes under some node by some tag name



    // traverse module

    var myInputs = just.byTag('input', myNode);



### Filtering nodes



    // filter module

    var disabled = just.matchAttr('disabled', 'disabled');

    var notHidden = function (el) {

        return !just.matchAttr('type', 'hidden');

    };

    var disabledInputs = just.filter([disabled, notHidden], myInputs);



### Manipulating the CSS



    // manipuate module

    just.css('display', 'none', myNode);



    // Or with currying

    var hide = just.css('display', 'none');

    hide(myNode);



### Manipulate classes



    // manipulate module

    just.addClass('active', myNode);

    

    var isActive = just.hasClass('active');

    isActive(myNode);  // == true



    var deactivate = just.removeClass('active');

    deactivate(myNode);



### Manipulate attributes



    // manipulate module

    just.attr('title', myNode'); // == myNode's title attribute value

    just.setAttr('title', 'awesome', myNode);

    just.hasAttr('title', myNode); // == true



### Attach event listener



    // events module

    var click = just.addListener('click');

    var listener = function () { console.log('clicked an element'); };

    click(myNode, listener);



### Remove event listener



    // events module

    just.removeListener('click', myNode, listener);



### Trigger an event



    // events module

    just.trigger('click', myNode);



### Normalize event object



    // events module

    var preventDefault = true;

    var listener = function (e) {

        e = just.evt(e, preventDefault);

        // Default is automatically prevented by passing `true` as second

        // argument. You can also just call `e.preventDefault()` as usual, and

        // that works on IE8 as well.



        var target = e.target; // works on IE8 as well

    };



## That's it?



Yes, more or less. There are a few little things left out for brevity's sake.

Full API documentation in narrative form is being planned for future releases,

so bear with me and read the code. 



There are two major reasons why there aren't many utiltiy functions. First,

Justils support currying, so it's really easy to create new utility functions

without having to 'program' anything. Also, because Justils only contain things

that its author and contributors actually needed more than just once, not

everything some theretical user could possibly need. So even if something is a

really neat idea, there's a good chance it won't make it into Justils

(someone's gotta maintain it, right?).



And if you _do_ need something, and think it'd be worth our time and energy and

increased size of the lbirary, let me know by [filing a feature

request](https://bitbucket.org/brankovukelic/justils/issues/new). ;)



## Roadmap



 + **1.0** Stable release with complete API freeze



## Running unit tests



Because it's always good to know _what_ doesn't work, please take the time to

run the unit tests before filing a bug report. To run unit tests, install

[Testem](https://npmjs.org/package/testem) using NPM, and run the tests with

this command:



    testem -f conf/testem.yml



Then connect the browser in which Justils are broken, by pointing it to

[localhost:7357](http://localhost:7537/).



## Bugs?



Yes, of course it has them. This library was craeted just the other day (pun

intentional), so it probably doesn't work always. Report all my bugs to the

BitBucket [issue tracker](https://bitbucket.org/brankovukelic/justils/issues).