#sdm
"simple dom module" for selecting and making dom elements. it exposes two globals in the window namespace $ and $$
api:
// NOTE: all functions either return the element or an array
// no NodeLists, so you can call `forEach` and friends directly
// $$ returns arrays, $ returns single elements
$$(selector [, parent = document])
// returns array of elements matching selector, from the document, or the parent element if passed
$$.cl(className [, parent = document])
// getElementsByClassName
$$.nam(name [, parent = document])
// getElementsByName
$$.tag(tagName [, parent = document])
// getElementsByTagName
$$.attr(attributeName [, value, parent])
// returns array of elements which have the given attribute
// if value is passed, it will return elements which have attribute set to that value
$$.data(datasetName [, value, parent])
// returns array of elements which have the given data attribute set
// if value is passed, it will return elements which have that data attribute set to the value
$(selector [, parent])
// alias to querySelector
$.id(id [, parent])
// getElementById
// parent must be a DocumentFragment or Document or it will throw, since getElementById is not generic (and it shouldn't be)
$.cl(className [, parent])
// like $.id, for classes
$.nam(name [, parent])
// returns first element from $$.nam
$.tag(tagName [, parent])
// first element from $$.tag
$.attr(attributeName [, value, parent])
// guess what
$.data(datasetName [, value, parent])
// simple as that
$.apply(element, options)
/*
this function modifies the passed dom element according to the options object
the signature of the options object looks like this:
*/
options = {
style: {
camelCasedStyleName: valueMapping
},
dataset: {
datasetNames: andValueMapping
},
classList: ['array', 'of', 'class', 'names'],
childNodes: [/* array of dom elements to append */],
on: {
'eventName': eventHandler<callback>,
'or': [
/* array of event handlers iteratively passed to addEventListener */
],
'for using useCapture': [
handlerA,
[handlerB, useCapture<boolean>]
]
},
anyOtherThing: youWantToAssignToElementLike,
textContent: 'foo bar',
innerHTML: 'tis bad practice to use innerHTML mmkay',
etc: 'you get the point?'
}
// these properties are applied to the passed element
// and the element is returned
$.make([tagName || element] [, options])
/*
this function creates a new dom element, and applies the options object to it like $.apply
first parameter can either be the tagName of the element to be created, or an element which will be cloned and used as a template.
if the first parameter is a DOM element to be cloned, whether it will be cloned plainly by default. i.e. child nodes will not be cloned. if you pass a property `deep: true` with the options object, it will be deep cloned.
if the tagName is passed as "#text", it returns a `textNode` of text value passed as the second parameter.
*/
$.append(element, referenceElement [, position = "bottom"])
// appends the element to the referenceElement by default
// position can be: "top", "bottom" (default), "before", "after", "replace"
// quite self explanatory, I guess?
$.remove(node)
// node could be a selector
// or a dom element
// if it is a selector, the first element matching it in document will be removed
// else the passed element will be
// genius!note that this module internally uses the standard dom apis only, and doesn't shim things like addEventListener, querySelector or querySelectorAll. (For converting to array, Array.prototype.slice is used instead of Array.from though, for maximum browser compatibility).
the aim of this module is to make DOM code slightly easier to read and to work with. reason why arrays are returned directly instead of NodeLists.
powerful functions can be made by the use of $.make (and calling $.make inside $.make(..., { childNodes: [/*here*/], ...})) for creating components etc.
you might ask why does $.id exist when I can do $('#' + id). it exists because it makes code easier to read. it is way too easy to miss a # when writing a selector causing silly time taking bugs, but if you know that you want to select via id, $.id is more readable and suitable. $.attr and $.data are convenience function that we need pretty much everyday. the flexible function signatures make stuff easy.
#License - WTFPL
- made by awalGarg - https://github.com/awalGarg