Elementals.js

Latest Version: 3.4 PRODUCTION 18 November 2017

Method _.make

Summary:

Creates an element from a CSS style selector, with any desired attributes and placed on the DOM as desired. This is done using DOM creation instead of innerHTML so as to bypass the parser resulting in faster changes and none of the headaches innerHTML can introduce.

Calling Convention:
_.make(selector, attributes)
Parameters:
selector
Attributes for specific tags when using the @ shorthand
tagName attribute
a href
button type
input type
script src
td headers
th scope

In general use this is similar in syntax to a CSS selector, parsed to create the element. When used in this nature the order "tagName#id.className" must be followed. If tagName is not specified a <div> will be created. Multiple classes can be passed delimited by either periods or spaces so long as the first one has a period before it.

Fancier "real" CSS selectors are not supported, though elementals.js provides a number of its own delimiters, psuedo elements, and a special method for quickly creating "text nodes".

@ "special values" delimiter
This allows the remainder of the selector string to be quickly used for an attribute on certain tags without getting the complex attributes object involved. The attached chart shows the element types that accept "special values" at to which attribute they are assigned. It should always be included LAST.
Forward Slash "/" Fast Text Node

Quickly creates a "text node" (aka nodeType = 3) instead of a normal element node (where nodeType = 1). Care should be used when using attributes since "text nodes" do not take the same attributes as "element nodes". MOST of the custom "command attributes" from elementals.js will work, just stay away from "content" and "replace" as things will go bits up face-down fast.

When using the "fast text node" delimiter you cannot specify a tagName (duh), ID, or className since again, text nodes don't have those!

A typical example would be:
_.make('/New Text Here', { last : document.body });

attributes

Can either be a String, or an Object of attributes that also includes a handful of special commands that can be used to place the element on the DOM as well as to specify the contents. If a string is passed it will be treated as if it were a content "command attribute".

The Elementals "command attributes" for make are:

  • after -- The new Element will be placed after the value as a sibling
  • before -- The new Element will be placed before the value as a sibling
  • children -- An array of arrays where the sub-arrays are selector/attribute pairs identical to what you would pass to _.make itself. If no after, before, first, last, or replace are stated each element will be added as last under the current element. This allows you to rapidly nest the creation of full DOM tree's.
  • content -- This value will be inserted inside the new Element
  • first -- The new Element will be placed before the Element.firstChild of the value
  • last -- The new Element will be placed after the Element.lastChild of the value
  • replace -- The new Element will replace the Element stated as the value of this attribute.

For more information on after, before, first, last, and replace see _.nodeAdd.

Any onevent attributes you passed will be parsed so as to be handled by _.eventAdd so that they will function identically across all browsers with the Event object being passed as a parameter to the callback, and Event.target and Event.currentTarget correctly resolving as expected -- even in legacy versions of Internet Explorer that use JScript instead of actual JavaScript / ECMAScript.

Note that you can pass innerHTML to plug in content as well. Whilst normally writing to innerHTML is generally a bad idea and should be avoided, if you do it BEFORE any of the _.nodeAdd methods it will be parsed into the element BEFORE it is added to the live document DOM. As a smaller sub-dom it parses fasteer and will not triggeer a reparse of the entire document, avoiding the headache/woes that normal innerHTML writes can create.

Returns:
The newly created Element.

Example #1

JavaScript

_.make('div#test', {
	content : 'This is a test',
	last : document.body
});

Is roughly equivalent to:

JavaScript

document.body.innerHTML += '<div id="test">This is a test</div>';

Except that it uses the DOM to do it, bypassing the parsing engine.

Example #2

JavaScript

_.make('h2.scriptHeading', {
	content : 'Test',
	after : document.getElementsByTagName('h1')[0];
});

Inserts after the first h1 on the page the equivalent of <h2 class="scriptHeading">Test</h2>, using the DOM instead of browser parsing.

Example #3

JavaScript

_.make('div#test', {
	children : [
		[ 'h2', 'This is a DOM created subsection' ],
		[ 'p', { innerHTML : 'A child paragraph <strong>that can use markup!</strong>' } ],
		[ 'p', [
			[ '/A child paragraph' ],
			[ 'strong', 'that directly assigns the <strong> tag.'],
			['/ Note that markup is escaped when you pass a normal string!' ]
		] ],
		[ 'div.details' , { children : [
			[ 'span' : '13 November 2017' ],
			[ '/ Jason M. Knight' ]
		] } ]
	],
	last : document.body
});

Basically creates the same thing on the DOM at the bottom of document.body as the following markup. (just without the whitespace I've added for clarity.

HTML

<div id="test">
	<h2>This is a DOM created subsection</h2>
	<p>
		A child paragraph <strong>that can use markup!</strong>
	</p>
	<p>
		A child paragraph <strong>that directly assigns the &lt;strong&gt; tag.!</strong> Note that markup is escaped when you pass a normal string!
	</p>
	<div class="details">
		<span>13 November 2017</span>
		Jason M. Knight
	</div>
</div>

Which is very handy when adding large sections of DOM elements and you want to avoid doing an innerHTML directly onto the live document DOM where the massive parsing overhead becomes a performance issue.