Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
141 lines (99 sloc) 3.93 KB

Docile

Docile makes it easy to store and retrieve data about DOM nodes.

Installation

With NPM

$ npm i -S docile

With Yarn

$ yarn add docile

With a CDN

<script src="https://unpkg.com/docile@latest/dist/docile.js"></script>

With Bower

$ bower install -S docile

Example Usage

<body>
    <div id='foo'>Foo</div>
</body>
var Docile = require('docile');

Docile.set(document.body, {example: ['a', 'b']}); // set data for DOM node (body)
Docile.get(document.body); // get data for DOM node (body)
// -> {example: ['a', 'b']}

Docile.set('foo', {bar: true}); // set data for DOM node with ID 'foo'
Docile.get(document.getElementById('foo')); // get data for DOM node (foo)
// -> {bar: true}

var fooLink = Docile.link('foo'); // get linkInstance for DOM node with ID 'foo'

fooLink.set('baz', document.body); // have baz link to DOM node (body) for DOM node (foo)
fooLink.set({yum: document.body}); // have yum link to DOM node (body) for DOM node (foo)

fooLink.get('yum'); // get the yum link for DOM node (foo)
// -> DOM Node (body)
fooLink.get(); // get all links for DOM node (foo)
// -> {baz: DOM Node (body), yum: DOM Node (body)}

fooLink.getData('yum'); // get the data for the yum link for DOM node (foo)
// -> {example: ['a', 'b']}
fooLink.getData(); // get the data for all links for DOM node (foo)
// -> {baz: {example: ['a', 'b']}, yum: {example: ['a', 'b']}}

Documentation

Docile is super simple to use.

Methods

Docile.set

Purpose: to store information about a node

The set method accepts two parameters: a node and the data to be stored. The node can either be a DOM node, or it can be an ID to a DOM Node.

Docile.set(node, data);

Docile.get

Purpose: to retrieve information about a node

The get method accepts one parameter: a node. The node can either be a DOM node, or it can be an ID to a DOM Node. This method returns the value stored with the set method.

Docile.get(node);

Docile.link

Purpose: to create a linkInstance for a node

The link method accepts one parameter: a node. The node can either be a DOM node, or it can be an ID to a DOM Node. This method returns a link instance.

var linkInstance = Docile.link(node);
linkInstance.set

Purpose: to "link" a given node to other nodes

The set method accepts two parameters: an alias string and a node. The node can either be a DOM node, or it can be an ID to a DOM Node. To set multiple links at one time, the set method also accepts an object with aliases mapped to nodes.

linkInstance.set(alias, node);
// OR
linkInstance.set(aliasToNodeObject);
linkInstance.get

Purpose: to retrieve "links"

The get method accepts one parameter: an alias. It returns a DOM node. If no alias is passed, then an object with aliases mapped to nodes will be returned.

linkInstance.get(alias);
// OR
linkInstance.get();
linkInstance.getData

Purpose: to retrieve data from "links"

The getData method accepts one parameter: an alias. It returns the data from the corresponding link. If no alias is passed, then an object with aliases mapped to data will be returned.

linkInstance.getData(alias);
// OR
linkInstance.getData();

Testing

Docile is tested using Jasmine. The test of the minified packages is available here and the webpack package here.

Big Thanks

Sauce Labs

Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs!

License

MIT (C) Russell Steadman. Learn more in the LICENSE file.

Support Me

Like this project? Buy me a cup of coffee. ☕ Here are more of my projects.