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 usingdocument.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 <strong> 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".