@3lessthan/htmltools

Toolkit for interacting with the DOM.

Usage no npm install needed!

<script type="module">
  import 3lessthanHtmltools from 'https://cdn.skypack.dev/@3lessthan/htmltools';
</script>

README

HTMLElement Tools

Simple Toolkit for Interacting with the DOM.

Methods

getElement

  • e {HTMLElement|string}
    • An HTMLElement, or a string that would produce one after being passed to querySelector.
  • (Optional) callback {Function}
    • A callback function that uses the result of this function's coersion. It is passed two arguments; (error, result), following Node.js conventions.

Description:

Given a HTMLElement, or a string representing one after being passed to querySelector or getElementById; coerces it to a single HTMLElement, if necessary. If a node-style callback is provided, it will return the result of it, passing in any errors if encountered, followed by the HTMLElement as arguments. Otherwise, it will either return the HTMLElement or throw an Error.

Note: If a string is passed as e, and it is not a known HTML5 element/tag, and does not begin with . or # - it will be assumed to be an ID.

getElements

  • e {NodeList|string}
    • A NodeList, or a string that would produce one after being passed to querySelectorAll.
  • (Optional) callback {Function}
    • A callback function that uses the result of this function's coersion. It is passed two arguments; (error, result), following Node.js conventions.

Description:

Given a NodeList, or a string representing one after being passed to querySelectorAll or getElementsByClassName; coerces it to an array of, HTMLElements. If a node-style callback is provided, it will return the result of it, passing in any errors if encountered, followed by the array of HTMLElements as arguments. Otherwise, it will return the array of HTMLElements, or throw an Error.

Note: If a string is passed as e, and it is not a known HTML5 element/tag, and does not begin with . or # - it will be assumed to be a class.

eachElement

  • e {HTMLElement[]|NodeList|string}
    • An HTMLElement, an array of HTMLElements, a NodeList, or a string that will produce one of the aforementioned types.
  • callback {Function}
    • A function that will be called on each HTMLElement. The arguments passed are the same as <Array>.forEach: (value, index, array).

Description:

Given one or more HTMLElements, a NodeList, or a string that will produce one of the aforementioned types after being passed to getElements - preforms the provided callback function once on each of the elements.

Custom Error Types

Some custom Error extended classes have been created for convenience. From the main package, they are available under htmltools.err.<error_type>. You can test for them using the instanceof operator.

  • ElementNotFound
  • NodeListNotFound
  • IllegalQuery

Changelog

v0.4.x

  • Added: Test.<Methods>: img, br, hr, li, div, map, mod, pre, area, base, body, data, form, head, html, link, meta, slot, span, time, audio, dList, embed, input, label, media, meter, oList, param, quote, style, table, title, track, uList, video, anchor, button, canvas, dialog, iFrame, legend, object, option, script, select, source, details, heading, picture, dataList, fieldSet, optGroup, progress, tableCol, tableRow, template, textArea, p, tableCell, tableCaption, tableSection

v0.3.x

  • Removed: Method - nodeListToArray
  • Change: Refactored - getElement, getElements, eachElement

v0.2.x

  • Added: Method - test.isElement
  • Added: Method - test.isElements

v0.1.x (Initial Publish)

  • Added: Method - getElement
  • Added: Method - getElements
  • Added: Method - nodeListToArray
  • Added: Method - eachElement
  • Added: Error - ElementNotFound
  • Added: Error - NodeListNotFound
  • Added: Error - IllegalQuery

Todo

  • Add testing suites
  • Correct Illegal Query pattern to allow all query types
  • StringTest should be extended to give getElements a performance boost where possible when a string can and only ever would be a single element.