dope

HTML5 dataset/attributes module.

npm install dope
12 downloads in the last week
18 downloads in the last month

dope

dope is cross-browser JavaScript module for working with HTML attributes. It includes an HTML5 dataset API abstraction that adheres to the specification. It works standalone or can integrate into jQuery-compatible hosts. It runs screamin-fast and gzips < 2k. Got data? =)

API (2.2)

In standalone usage, methods are available on the dope namespace. The docs below use $ to denote dope or a host library like jQuery or ender.

dope.dataset(document.body, 'foo', 'bar'); // standalone
$.dataset(document.body, 'foo', 'bar'); // integrated

Chain methods

$.fn.attr()

$(elem).attr(key) // get attribute on elem (or 1st elem in collection)
$(elem).attr(key, value) // set attribute on elem (or on collection)
$(elem).attr(object) // set multiple attributes via key/value pairs

$.fn.removeAttr()

$(elem).removeAttr(keys) // remove 1 or more SSV attributes from elem or collection

$.fn.dataset()

$(elem).dataset() // get all data-* attributes on elem (or 1st elem in collection)
$(elem).dataset(key) // get data-* attribute on elem (or 1st elem in collection)
$(elem).dataset(key, value) // set data-* attribute on elem (or on collection)
$(elem).dataset(object) // set multiple data-* attributes via key/value pairs
$(elem).dataset([key]) // get [exact] data-* attribute (primitives render to correct type)
$(document.body).dataset('movieName', Pulp Fiction) // set <body data-movie-name="Pulp Fiction">
$(document.body).dataset('movieName') // returns "Pulp Fiction"
$('div').dataset('stars', 5) // set <div data-stars="5"> on all matched divs
$('div').dataset('stars') // returns "5"
$('div').dataset(['stars']) // returns 5

$.fn.deletes()

$(elem).deletes(keys) // remove 1 or more SSV data-* attributes from elem or collection
$(document.body).deletes('movieName') // remove [data-movie-name] from the <body> element

Static methods

$.attr()

$.attr(elem, key) // get attribute on elem
$.attr(elem, key, value) // set attribute on elem
$.attr(elem, object) // set multiple attributes via key/value pairs

$.removeAttr()

$.removeAttr(elem, keys) // remove 1 or more SSV attributes from elem (or from collection)

$.dataset()

$.dataset(elem) // get all data-* attrs on elem
$.dataset(elem, key) // get data-* attribute on elem
$.dataset(elem, key, value) // set data-* attribute on elem
$.dataset(elem, object) // set multiple data-* attributes via key/value pairs
$.dataset(elem, [key]) // get [exact] data-* attribute (primitives parse to correct type)
$.dataset(document.body, 'movieName', Pulp Fiction) // set <body data-movie-name="Pulp Fiction">
$.dataset(document.body, 'movieName') // returns "Pulp Fiction"

$.deletes()

$.deletes(elem, keys) // remove 1 or more SSV data-* attributes from elem (or from collection)
$.deletes(document.body, 'movieName') // remove [data-movie-name] from the <body> element

$.queryData()

$.queryData(keys) // get elements by data key (keys can be an array or CSV or SSV string)
$.queryData('miaWallace vincentVega') // Delegate to $("[data-mia-wallace],[data-vincent-vega]")

$.trim()

$.trim(str) // Trim surrounding whitespace.

$.parse()

$.parse(str) // Convert stringified primitives to correct value. Non-strings are unchanged.
$.parseJSON(str) // Parse JSON. Safely wraps `JSON.parse` so that it won't throw an error.

$.parse and $.parseJSON trim "string" inputs before parsing them.

$.parse('yo') // 'yo'
$.parse('10') // 10
$.parse('true') // true
$.parse('null') // null
$.parse('undefined') // undefined
$.parse('Infinity') // Infinity
$.parse('NaN') // NaN

$.camelize()

$.camelize(str) // convert a dashed data- string into camelCase
$.camelize('data-mia-wallace') // 'miaWallace'
$.camelize('mia-wallace') // 'miaWallace'
$.camelize(47) // '47'

$.datatize()

$.datatize(str) // convert a camelized string into a lowercase dashed data- attribute name
$.datatize('miaWallace') // 'data-mia-wallace'
$.datatize(47) // 'data-47'
$.datatize(0) // 'data-0'
$.datatize(null) // ''
$.datatize('') // ''
$.datatize(undefined) // ''

AMD usage

define('dope', function() { 
  return dope; 
});

Compatibility

Supports all major browsers. Tested in Chrome, FF3+, IE7+, Opera, and Safari.

  • atts: attributes module

License

MIT

npm loves you