create-elms

    1.0.9 • Public • Published

    create-elms

    NPM Build Status Codacy grade Codecov License: MIT Tweet

    Create HTML elements, set attributes, add to other elements, and return an array of DOM nodes or HTML markup in a single function call.



    Features

    • Create elements using strings or objects
    • Append, prepend, and insert elements before or after other elements
    • Return an array of elements or HTML markup
    • UMD and ES6 module available
    • Compatible with modern and legacy browsers (IE9+)
    • Compatible with Node environments using jsdom
    • Lightweight (~1k min+gzip) and dependency-free

    Installation

    NPM:

    npm install create-elms
    // file.js
    import createElms from 'create-elms';
    const elms = createElms(/* ... */);

    Git:

    git clone https://github.com/jhildenbiddle/create-elms.git

    CDN (jsdelivr.com shown, also on unpkg.com):

    <!-- ES5 (latest v1.x.x) -->
    <script src="https://cdn.jsdelivr.net/npm/create-elms@1"></script>
    <script>
      var elms = createElms(/* ... */);
    </script> 
    <!-- ES6 module (latest v1.x.x) -->
    <script type="module">
      import getCssData from 'https://cdn.jsdelivr.net/npm/create-elms@1/dist/create-elms.esm.min.js';
      const elms = createElms(/* ... */);
    </script> 

    Examples

    Render elements using strings and/or objects:

    let elm, elms;
     
    // Create an element from a string
    elm = createElms('<p>Foo</p>'); // => [elm]
     
    // ... or an object
    elm = createElms({
      tag : 'p',
      text: 'Foo'
    }); // => [elm]
     
    // ... or multiple elements from a string
    elms = createElms('<p>Foo</p><p>Bar</p><p>Baz</p>'); // => [elm, elm, elm]
     
    // ... or an array of strings
    elms = createElms([
      '<p>Foo</p>',
      '<p>Bar</p>',
      '<p>Baz</p>'
    ]); // => [elm, elm, elm]
     
    // ... or an array of objects
    elms = createElms([
      { tag: 'p', text: 'Foo' },
      { tag: 'p', text: 'Bar' },
      { tag: 'p', text: 'Baz' }
    ]); // => [elm, elm, elm]
     
    // ... or an array containing strings and objects
    elms = createElms([
      '<p>Foo</p>',
      '<p>Bar</p>',
      { tag: 'p', text: 'Baz' }
    ]); // => [elm, elm, elm]

    Set per-element attributes or shared attributes:

    let elm, elms;
     
    // Set attributes on specific elements...
    elm = createElms({
      tag : 'p',
      text: 'Foo',
      attr: { id: 'foo', class: 'myclass' }
    });
     
    // ... or use the 'sharedOptions' argument for multiple elementData objects
    elms = createElms(
      // elementData
      [
        { text: 'Foo', attr: { id: 'foo' } },
        { text: 'Bar', attr: { id: 'bar' } },
        { text: 'Baz', attr: { id: 'baz' } }
      ],
      // sharedOptions
      {
        tag : 'p',
        attr: { class: 'myclass' }
      }
    );
     
    // ... or to apply options to one-or-more elementData strings
    elms = createElms(
      // elementData
      [
        '<p id="foo">Foo</p>',
        '<p id="bar">Bar</p>',
        '<p id="baz">Baz</p>'
      ],
      // sharedOptions
      {
        class: 'myclass'
      }
    );

    Append, prepend, or insert elements:

    let elm, elms;
     
    // Use CSS selectors, HTMLElement(s) or Node(s)
    elm = createElms({ tag: 'p', appendTo: 'body' });
    elm = createElms({ tag: 'p', appendTo: document.body });
    elm = createElms({ tag: 'p', appendTo: document.querySelector('body') });
    elm = createElms({ tag: 'p', appendTo: document.querySelectorAll('div') });
     
    // ... or an array of CSS selectors, HTMLElements, and/or Nodes
    elm = createElms({
      tag     : 'p',
      appendTo: [
        'body',
        document.querySelectorAll('div')
      ]
    });
     
    // Specify multiple append/prepend/insert points per element
    elms = createElms({
      tag         : 'p',
      appendTo    : 'body',
      prependTo   : document.body,
      insertBefore: document.querySelectorAll('div'),
      insertAfter : document.getElementsByTagName('h1')
    });
     
    // ... or use the 'shadedOptions' argument for multiple elements
    elms = createElms(
      // elementData
      [
        '<p>Text1</p>',
        '<p>Text2</p>'
      ],
      // shadedOptions
      {
        appendTo    : 'body',
        prependTo   : document.body,
        insertBefore: document.querySelectorAll('div'),
        insertAfter : document.getElementsByTagName('h1')
      }
    );

    Have elements returned as HTMLElements or HTML markup:

    // Return as HTML elements (default)
    let elm = createElms({ tag: 'p' });
    // => [elm]
     
    // Return as HTML markup
    let html = createElms({ tag: 'p' }, { returnHtml: true });
    // => '<p></p>'

    Usage

    createElements(elementData, sharedOptions = {}, documentObject = window.document)
    • Returns: Array
      • An array of of elements (default)
      • An array of HTML markup (when returnHtml option is true).

    elementData

    • Type: Object, String, or Array
      • String should be valid HTML markup
      • Object should be an HTMLElement or Node
      • Array should contain HTML markup, HTMLElements, and/or Nodes

    Strings

    • Strings may contain multiple elements
    • Each top-level element in a string will be returned in the return Array
    • Use sharedOptions to apply properties to String elementData
    • If sharedOptions are used, options will be applied to all top-level elements in the string

    Objects

    • The html value will be inserted as HTML content
    • The text value will be inserted as text content. This value is ignored if html is defined.
    • The attr value should contain attribute name/value pairs
    • The appendTo, prependTo, insertBefore and insertAfter properties accept a CSS selector, HTMLElement, HTMLCollection, Node, NodeList, or an Array of these Object types.
    Property Type Description
    tag string Element HTML tag
    attr object Element attributes
    html string Content to append to element(s) as HTML
    text string Content to append to element(s) as text
    appendTo object|string Node(s) to append element(s) to
    prependTo object|string Node(s) to prepend element(s) to
    insertBefore object|string Node(s) to insert element(s) before
    insertAfter object|string Node(s) to insert element(s) after

    Examples

    // String
    let elm1 = createElement('<p id="foo" class="myclass"><a href="/">Home</a>');
    // => [elm] (top-level <p> is returned, not nested <a>)
     
    // String with multiple elements
    let elms1 = createElement('<p>Text1</p><p>Text2</p><p>Text3</p>');
    // => [elm, elm, elm] (all top-level elements returned)
     
    // Object
    let elm2 = createElement({
      tag : 'p',
      html: '<a href="/">Home</a>',
      attr: { id: 'foo', class: 'myclass' }
    });
    // => [elm]
     
    // Array of strings and/or objects
    let elms = createElement([
      '<p>Text</p>',
      { tag: 'p', text: 'Text' }
    ]);
    // => [elm, elm]

    sharedOptions

    • Type: Object
    • Default: {}

    Options are applied to all elementData with the following rules:

    • When applied to an elementData Object, all options are valid.
    • When applied to an elementData String, the tag property is ignored.
    • Existing tags, attributes, HTML and text content will not be replaced by shared options.

    Object properties

    All properties from elementData plus the following:

    Property Type Default Description
    returnHtml Boolean false Return elements as array of HTML markup when true.

    Example

    // Return as HTML markup
    let html = createElms(
      // elementData
      { tag: 'p', text: 'Text' },
      // sharedOptions
      { returnHtml: true }
    );
    // => '<p>Text</p>'

    documentObject

    • Type: Object
    • Default: window.document

    This is the document object on which document.createElement and document.querySelectorAll methods will be called. The default value assumes a browser environment, but passing a reference to a document object created by tools like jsdom allows creating HTML elements and markup in a Node environment (without polluting global variables).

    Example

    const createElms = require('create-elms');
    const jsdom      = require('jsdom');
    const dom        = new JSDOM();
    const jsDocument = dom.window.document;
     
    let elm = createElms({ tag: 'p', {}, dom.window.document)
    // => [elm]
     
    let html = createElms({ tag: 'p', { returnHtml: true }, dom.window.document)
    // => '<p></p>'

    Contact

    License

    This project is licensed under the MIT License. See the LICENSE for details.

    Copyright (c) John Hildenbiddle (@jhildenbiddle)

    Install

    npm i create-elms

    DownloadsWeekly Downloads

    78

    Version

    1.0.9

    License

    MIT

    Unpacked Size

    108 kB

    Total Files

    23

    Last publish

    Collaborators

    • jhildenbiddle