National Pest Management

    xdom

    0.0.3 • Public • Published

    xdom

    A light, modern, pick-and-choose DOM library.

    Goal

    xdom exposes a functional API very similar to native DOM, which makes it fast, easy to use and keeps it small.

    Some of the stuff it does includes (but is not limited to):

    • some missing features of native DOM: prepend() to an element, live event binding, creating elements from an HTML string, etc.
    • transparently handling collections of DOM elements
    • facilitating the creation of complex DOM trees
    • abstracting away browser discrepancies

    It does all that in just 8.6kB (minified). And using ES6 tree shaking, that number can be brought down a whole lot more.

    Usage

    The dist folder contains all the compiled packages (es5, es6 and minified versions, all in UMD bundles), so you can just drop them into a <script> tag. The global variable (exported if no module system if found) is called $.
    The src folder contains the source code, which you can also import from, using ES6 modules. If you want to use tree shaking, you have to import from src, because the compiled bundles don't use ES6 modules.

    API

    The source code is divided up into different files containing similar functions, e.g. attr.js contains setAttr() and getAttr(). This system is also used in these docs, which is useful for people importing directly from the source. In the bundled versions, however, all the functions are methods on the exported object, e.g. x.getAttr() and x.addClass(). This is also the case when importing src/entry.js.

    Note: the element type refers to a single DOM element, the elements type refers to an array (or array-like structure) of DOM elements and the element(s) type is used where either of them is accepted. Also note that whenever element is specified, you can also pass in an array of elements, in which case the first element will be used, and you can pass 1 element whenever multiple elements are expected, in which case it will be treated as an array of 1 element.

    attr

    Get and set element attributes.

    attr( element(s) $elems, string|object name, [string value] ) : [string value]

    Shortcut for getAttr(), setAttr() and setAttrs(). If name is an object, passes it to setAttrs(). If name is a string and value is defined, calls setAttr(), otherwise calls getAttr().

    setAttr( element(s) $elems, string name, string value )

    Sets the attribute name to value on $elems, just like DOMElement.setAttribute(). If value is falsy, it removes the attribute, if it's true, it uses the attribute name, e.g. disabled="disabled".

    getAttr( element $elem, string name ) : string value

    Gets the attribute name from $elem, like DOMElement.getAttribute().

    setAttrs( element(s) $elems, object attributes )

    Given an attributes object, mapping names to values, calls setAttr() for every attribute.

    rmAttr( element(s) $elems, string|string[] names )

    Shortcut for removeAttr() and removeAttrs(). If attributes is a string, calls removeAttr(), otherwise calls removeAttrs().

    removeAttr( element(s) $elems, string name )

    Removes the attribute called name from $elems.

    removeAttrs( element(s) $elems, string[] names )

    Removes all attributes in names from $elems.

    build

    Edit relations between DOM nodes, i.e. moving, inserting and removing elements.

    append( element(s) $children, element $parent )

    Appends $children to $parent.

    prepend( element(s) $children, element $parent )

    Prepend $children to $parent.

    insertBefore( element(s) $elems, element $sibling )

    Inserts $elems into $sibling's parent, before $sibling.

    insertAfter( element(s) $elems, element $sibling )

    Inserts $elems into $sibling's parent, after $sibling.

    insertAt( element(s) $elems, element $parent, number index )

    Inserts $elems into $parent at index (zero-based).

    remove( element(s) $elems )

    Removes $elems from the DOM.

    removeAt( element $parent, number from, [number to] )

    If to is a number, removes the children from $parent, from index from to index to. Otherwise, removes one child, at from.

    replace( element(s) $new, element $old )

    Replaces $old with $new in the DOM.

    class

    Add, remove and toggle classes.

    addClass( element(s) $elems, string|string[] classes )

    Adds all the classes in classes to $elems. Strings can be a space-seperated list of classes (as you would find them in HTML).

    removeClass( element(s) $elems, string|string[] classes )

    Removes all the classes in classes from $elems. Strings can a space-seperated list of classes (as you would find them in HTML).

    toggleClass( element(s) $elems, string|string[] classes, [boolean|string force = false] )

    For each class in classes this function will toggle the class on each element in $elems. If force is true, the class will always be added, if false, the class will be removed from all elements.
    If force is the string all, the class will be toggled the same way for all elements, according to the first one, e.g. if the first element has the class, but the rest doesn't, it will be added to all elements.

    hasClass( element $elem, string class ) : boolean hasThisClass

    Checks whether $elem has the class class.

    allHaveClass( element(s) $elems, string class ) : boolean hasThisClass

    Checks whether all the $elems have the class class.

    someHaveClass( element(s) $elems, string class ) : boolean hasThisClass

    Checks whether at least one element of $elems has the class class.

    content

    Get and set element's contents.

    html( element(s) $elems, [string html] ) : [string html]

    Shortcut for setHTML() and getHTML().

    getHTML( element $elem ) : string html

    Gets $elem's inner HTML.

    setHTML( element(s) $elems, string html )

    Sets (all) the elements's inner HTML.

    text( elements(s) $elems, [string text] ) : [string html]

    Shortcut for getText() and setText().

    getText( element $elem ) : string text

    Gets $elem's text content.

    setText( element(s) $elems, string text )

    Sets (all) the elements's text content.

    create

    Create DOM elements and trees.

    create( string tag, [object attributes], [string|string[]|element(s)] $children ) : element $newElement

    Creates a new DOM element ith tag name tag. Optionally, you can add some attributes (passed to setAttrs()).
    You can also add some children, as a string or DOM element, or an array of strings and/or DOM elements. Strings will be converted to text nodes.
    This forgiving syntax allows for some pretty great stuff:

    create( "div", { dynamic: true }, [
      create( "h2", "Hello, World!" ),
      create( "p", [
        "How are you on this ",
        create( "span", { "class": "emphasize" }, "FINE"),
        " day?"
      ] )
    ] );

    results in:

    <div dynamic="dynamic">
      <h2>Hello, World!</h2>
      <p>How are you on this <span class="emphasize">FINE</span> day?</p>
    </div>

    createHTML( string html ) : element[] result

    Parses an HTML string and returns a list of DOM elements.

    css

    Edit CSS styles of elements.

    cssNameToJs( string cssName ) : string jsName

    Converts a CSS property name to a JS name, e.g. property-name becomes propertyName.

    jsNameToCss( string jsName ) : string cssName

    Converts a JS name to a CSS property name, e.g. propertyName to property-name.

    style( element(s) $elems, string prop, [any value] ) : [any value]

    Shortcut for setStyle() and getStyle().

    getStyle( element $elem, string property ) : any value

    Gets the value of the CSS property from elem. The property name is converted using cssNameToJs().

    setStyle( element(s) $elems, string property, any value )

    Sets the CSS property to value on $elems. For numeric values, px is added at the end, if you don't want this, use a string. Property names are converted using cssNameToJs().

    setStyles( element(s) $elems, object styles )

    Calls setStyle() for every property: value pair of styles.

    css( element(s) $elems, string|object stylesOrProperty, [any value] ) : [any value]

    Shortcut for setStyles() and style().

    events

    Add and remove event listeners.

    on( element(s) $elems, string event, function listener, [boolean|object options = false] )

    Attaches listener to the event on all $elems. The last argument is the useCapture flag, or an options object for more modern browsers. See the MDN for more info. By default, false is used.

    off( element(s) $elems, string event, function listener, [boolean|object options = false] )

    Removes an event listener. Arguments are the same as for on().

    live( element(s) $elems, string selector, string event, function listener, [boolean|object options = false] ) : function callback

    Adds a listener to all $elems that calls listener whenever the event target matches selector. The actual callback that is registered (i.e. the one that has to be passed to off()) is returned.

    family

    Read out different relationships between DOM elements.

    firstChild( element $parent ) : element firstChild

    Returns $parent's first child.

    lastChild( element $parent ) : element lastChild

    Returns $parent's last child.

    childAt( element $parent, number index ) : element child

    Returns $parent's child at index.

    childrenAt( element $parent, number from, number to ) : element[] children

    Returns $parent's children at indexes from from to to.

    children( element(s) $elems, [string selector] ) : element[] children

    Returns all of $elems's children as 1 array. Optionally filter children with a CSS selector.

    isChild( element $child, element $elem ) : boolean isChild

    Checks whether $child is a child of $elem.

    isChildOfAll( , element $childelement(s) $elems ) : boolean isChild

    Checks whether $child is a child of every element in $elems.

    isChildOfSome( element $child, element(s) $elems ) : boolean isChild

    Check whether $child is a child of at least one of the elements in $elems.

    descendants( element(s) $elems, [string selector], [boolean all] ) : element[] descendants

    Returns all descendants (children, grandchildren...) of $elems. Optionally filter them with a CSS selector. If all is true, include intermediate elements, otherwise only include elements that don't have children themselves (this is the default).

    isDescendant( element $descendant, element $elem, ) : boolean isDescendant

    Checks whether $descendant is a descendant of $elem.

    isDescendantOfAll( element $descendant, element(s) $elems, ) : boolean isDescendant

    Checks whether $descendant is a descendant of every element in $elems.

    isDescendantOfSome( element $descendant, element(s) $elems, ) : boolean isDescendant

    Check whether $descendant is a descendant of at least one of the elements in $elems.

    parent( element(s) $elems, [string selector] ) : element parent

    If a selector is passed, loops through all $elems and returns the first parent that matches selector. Otherwise, returns the parent of the first element.

    parents( element(s) $elems, [string selector] ) : element[] parents

    Returns all the parents of $elems that match selector, or all parents if no selector is passed.

    isParent( element $parent, element $elem ) : boolean isParent

    Checks whether $parent is a parent of $elem.

    isParentOfAll( element $parent, element(s) $elems ) : boolean isParent

    Checks whether $parent is a parent of every element in $elems.

    isParentOfSome( element $parent, element(s) $elems ) : boolean isParent

    Check whether $parent is a parent of at least one of the elements in $elems.

    ancestors( element(s) $elems, [string selector] ) : element[] ancestors

    Returns a list of all $elems's ancestors (parents, grandparents...), optionally filtered with a CSS selector.

    isAncestor( element $ancestor, element $descendant ) : boolean isAncestor

    Checks whether $ancestor is an ancestor of $descendant.

    isAncestorOfAll( element $ancestor, element(s) $descendants ) : boolean isAncestor

    Checks whether $ancestor is an ancestor of all the elements of $descendants.

    isAncestorOfSome( element $ancestor, element(s) $descendants ) : boolean isAncestor

    Checks whether $ancestor is an ancestor of at least one of the elements of $descendants.

    next( element $elem ) : element nextSibling

    Returns $elem's next (element) sibling, i.e. the element right after it.

    prev( element $elem ) : element previousSibling

    Returns $elem's previous (element) sibling, i.e. the element that comes right in front of it.

    siblings( element(s) $elems, [string selector] ) : element[] siblings

    Returns all of $elems's siblings as 1 array, optionally filtered with a CSS selector.

    prevSiblings( element(s) $elems, [string selector] ) : element[] siblings

    For each element in $elems, returns all its siblings in front of it. Results are returned as 1 big array, optionally filtered with a CSS selector.

    nextSiblings( element(s) $elems, [string selector] ) : element[] siblings

    For each element in $elems, returns all its siblings behind it. Results are returned as 1 big array, optionally filtered with a CSS selector.

    index( element $elem ) : number index

    Returns the index of $elem relative to its siblings, e.g. for a parent with 5 children, $elem in the middle, this function would return 2.

    prop

    Get, set and remove properties DOMElement objects.

    prop( element(s) $elems, object|string name, [any value] ) : [any value]

    Shortcut for getProp(), setProp() and setProps().

    setProp( element(s) $elems, string name, any value )

    Sets the property called name to value on all $elems.

    setProps( element(s) $elems, object props )

    Calls setProp() for each property: value pair in props.

    getProp( element $elem, string name ) : any value

    Returns the value of the property called name from $elem.

    rmProp( element(s) $elems, string|string[] names )

    Shortcut for removeProp() and removeProps().

    removeProp( element(s) $elems, string name )

    Removes the property called name from $elems.

    removeProps( element(s) $elems, string[] names )

    Calls removeProp() for every name in names.

    select

    Select DOM elements and check if they match CSS selectors.

    select( [element root = document], string selector, [boolean all = false] ) : element(s)

    The select() function is used to query the DOM, but depending on its arguments, its behavior changes slightly.
    The selector is the only required attribute. If only that is passed, it just queries from the document, if a root is passed, it queries from there, i.e. root.querySelector( selector ). If all is true, it returns all matching elements (as a NodeList, not an Array!), using querySelectorAll().

    Some examples:

    var $main = select( "main" ); // select the <main> tag
    var $articles = select( $main, "article[visible]", true ) // select all the <article>s with a 'visible' attribute in the <main> tag
     
    // Log the title of each article
    for(article in $articles) {
      console.log( select( article, ".title" ).textContent );
    }

    matches( element $elem, string selector ) : boolean match

    Checks whether $elem matches selector.

    match( elements $elems, string selector, [boolean getIndex = false] ) : number|element match

    Returns the first element of $elems that matches selector, or undefined if none match. If getIndex is true, returns the index of that element in the $elems collection, rather than the element itself.

    matchAll( elements $elems, string selector ) : boolean match

    Checks whether all $elems match selector.

    util

    xdom includes (and needs) some utilities in the util directory. The first one, called is, is a small type checking 'library'. The other functions are used to work with arrays and are grouped in array.js. util.js and entry.js export these two as is and array repectively, i.e. xdom.is maps to util/is.js and xdom.array maps to util/array.js.

    util/is

    A simple type checking library. Usually, you just import * as is from "xdom/src/util/is" and just use it like is.string(value), is.arrayLike(value) etc. If you're using ES5 modules or globals, use xdom.is.string(value) etc.
    The following is the documentation for all these test functions. I'll only list their names, without the arguments and return values, because they all follow the same pattern: is.name( any value ) : boolean match, where name is the name of the test, of course.

    string

    Checks if the value is a string.

    number

    Checks if the value is a number.

    bool

    Checks if the value is a boolean.

    object

    Checks if the value is an object, i.e. typeof value === "object".

    element

    Checks if the value is a DOM element.

    node

    Checks if the value is a DOM node.

    document

    Checks if the value is a Date object.

    document

    Checks if the value is the document object.

    array

    Checks if the value is an Array (using Array.isArray(), so make sure to polyfill it!).

    arrayLike

    Checks if the value is an Array-like structure, like a NodeList or a HTMLCollection (or an Array...). It does this by checking that is has a length property and is not a string (which has this property, but is not considered array-like) or a node (which can have a length property if it's a TextNode).

    plainObject

    Checks if the value is a plain object, i.e. if it's an object, but is not a Node, a Date, or array-like.

    defined

    Checks if a value is defined, i.e. it's not undefined or null.

    undef

    The opposite of defined.

    util/array

    All array-related utilities. Many functions in xdom accept a single value, or an array of values; these utilities handle these cases transparently. You can import them directly from the source (e.g. import { each } from "xdom/src/util/array") if you're using ES6 modules, otherwise use xdom.array.each() etc.

    each( any|any[] values, function( any value, number index, any[]|false array ) handler ) : any

    Calls handler for every item in values, be it an array, a single value, or even undefined. If values is array-like, behaves pretty much like Array.forEach(). If values is not array-like, handler is called once for this value. index will be 0, and array will be false. If values is undefined or null, handler is not called and undefined is returned.
    If handler returns anything, the loop breaks and this value is returned.

    reduce( any|any[] values, any start, function( any accumulator, any value, number index, any[]|false array ) ) : any

    Works like Array.reduce(), but with the same safeguards as each().

    flatten( any|any[] arr ) : any[] flattened

    Converts a nested array into a single array, conserving the order of the elements. If arr is just a single value, returns an array containing that value.

    first( any|any[] values ) : any first

    Returns the first element of values if it's array-like, or values itself if it isn't.

    last( any|any[] values ) : any last

    Like first(), but returns the last element.

    slice( any[] arr, number from, [number to] ) : any[] sliced

    Like Array.slice(), but works with array-like objects.

    indexOf( any[] arr, any item ) : number index

    Like Array.indexOf(), but works with array-like objects.

    Keywords

    none

    Install

    npm i xdom

    DownloadsWeekly Downloads

    154

    Version

    0.0.3

    License

    MIT

    Last publish

    Collaborators

    • tuur