Skip to content

Implementation of and polyfill for DOMTokenList

Notifications You must be signed in to change notification settings

medialize/tokenlist

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

TokenList.js

This module is an implementation of the DOMTokenList Interface based on jwilsson/domtokenlist and bkardell/tokenListFor.

This module was created to optimize Brian's initial implementation and investigate further application for DOMTokenList (as Brian's tokenListFor does).

The TokenList interface

The DOMTokenList interface does not specify any constructors. This implementation accepts callback functions to read and write tokens, thereby decoupling itself from the DOM:

var element = document.body;

var classList = TokenList(
  // callback used to read the current serialized presentation of the DOMTokenList
  function readString() { return element.getAttribute('class'); },
  // callback used to store the modified serialized presentation of the DOMTokenList
  function writeString(value) { element.setAttribute('class', value); }
);

classList.add('gustav');
classList.contains('gustav') === true;
classList.remove('gustav');

Supported tokens

Some DOMTokenLists may know the accepted ("supported") tokens, which can be provided to TokenList via an optional callback, as shown here for the <iframe>'s sandbox attribute:

var element = document.getElementById('iframe');

var sandboxValues = [
  'allow-modals',
  'allow-orientation-lock',
  'allow-pointer-lock',
  'allow-popups', that functionality will silently fail.
  'allow-popups-to-escape-sandbox',
  'allow-same-origin',
  'allow-scripts',
  'allow-top-navigation',
];

var sandboxList = TokenList(
  // callback used to read the current serialized presentation of the DOMTokenList
  function readString() { return element.getAttribute('sandbox'); },
  // callback used to store the modified serialized presentation of the DOMTokenList
  function writeString(value) { element.setAttribute('sandbox', value); },

  // [optional] callback to verify if a token is to be considered supported
  // defaults to null, causing TokenList#supported() to throw an appropriate error
  function supported(token) { return sandboxValues.indexOf(token) !== -1; }
);

sandboxList.add('allow-modals');
sandboxList.contains('allow-modals') === true;
sandboxList.remove('allow-modals');

sandboxList.supports('allow-modals') == true;
sandboxList.supports('not-supported-token-value') === false;

// NOTE: unsupported values are still added to the list
sandboxList.add('not-supported-token-value');

Encoded token values

As tokens may represent entities, their values can be encoded and decoded via optional callbacks, as shown here for the aria-labelledby attribute:

var element = document.getElementById('target');

var labelledByList = TokenList(
  // callback used to read the current serialized presentation of the DOMTokenList
  function readString() { return element.getAttribute('aria-labelledby'); },
  // callback used to store the modified serialized presentation of the DOMTokenList
  function writeString(value) { element.setAttribute('aria-labelledby', value); },

  // ignore supported()
  null,

  // [optional] callback used to decode a token (string) to another object
  function decode(token) { return token ? document.getElementById(token) : null; },
  // [optional] callback used to encode an object to a string token
  function encode(input) { return input ? input.id : null; }
);

var label = document.getElementById('label');
labelledByList.add(label);
labelledByList.contains(label) === true;
labelledByList.remove(label);

The prollyfill

Based on WICG tokenListFor() proposal this package provides Element.prototype._tokenListFor() and Element.prototype._referenceListFor().

var element = document.body;

// standard way to obtain the classList:
var tokenlist = element.classList
tokenlist.contains('some-class');

// prollyfill way to option the classlist:
var tokenlist = element._tokenListFor('class');
tokenlist.contains('some-class');

// resolving ID-References
var labels = element._referenceListFor('aria-labelledby');
labels.contains(document.getElementById('some-label'));

Other implementations

License

TokenList.js is published under the MIT License.

About

Implementation of and polyfill for DOMTokenList

Resources

Stars

Watchers

Forks

Packages

No packages published