Elementals.js

Latest Version: 3.7 Final 20 December 2018

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. The DOM_JON JSON format was created to expediate the creation of large structures using the DOM.

_.make is probably the most important and powerful of methods provided by elementals.js thanks to the DOM-JON implementation and bypassing of the parser and any security woes that can arise from using innerHTML.

Calling Convention:
_.make(DOM_JON);
_.make(selector);
_.make(selector, DOM_JON);
_.make(selector, attributes);
_.make(selector, contentString);

Passing a DOM-JON Array as the first parameter is new as of 3.6.2

Parameters:
attributes
An Array of attributes and commands as per the DOM-JON specification.
contentString
In either DOM-JON or with _.make when a flat string is passed as a secondary parameter it will be treated as text content to be added and created on the DOM using document.createTextNode.
DOM_JON
This Array parameter if passed conforms to the DSS and/or content array/string/attribute pairings.
selector
A Delimiter Selector String (DSS) as per the DOM-JON documentation. When provided this will be the element returned by _.make.
Returns:
The newly created Element if a Selector is passed. If a DOM-JON Array structure is passed the function will return boolean true. Boolean false should be returned on non-fatal errors, though for the time being there are no such cases..
Modifies:
The _.ids object will have any elements created by _.make or _.Node.write that have ID's appeneded to it with the ID of the element as the index. If you attempt to create a second element with the same ID as an existing one, the existing one will be overwritten in the collection.

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' , { content : [
			[ '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. Quite often -- most of the time in fact -- writing to the live page with innerHTML can introduce large amounts of overhead in processing time and memory footprint as the entire document has to be reparsed as markup with an entirely new re-organized DOM created. Writing directly to the DOM with _.make bypasses this "problem".