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

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.

russellsteadman / docile