Elementals.js

Latest Version: 3.7 Final 20 December 2018

Method _.Node.write

Summary:

Allows you to write new text content or a new Element to an existing DOM Element.

In practice you are likely better off just using _.make to perform this operation using the DOM-JON Placement Commands, however this function would still exist internally as _.make calls it. If it's going to be there anyways, why not expose it user-side?

Calling Convention:
_.Node.write(Element, DOM_JON[, place]);
_.Node.write(Element, attributes[, place]);
_.Node.write(Element, contentString[, place]);
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 parameter if passed conforms to the complete DOM-JON specification.. Basically this should be an Array pairing of DSS and/or content array/string/attributes.
Element
The target Element to which the content is added to or placed around.
place (optional)
Where to place the new content in relation to the target Element. This string can be any one of the Placement Commands from the DOM-JON specification. If omitted, "last" is assumed.
Returns:
Nothing
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.

JSON content

When an array is passed as content it is assumed to be a list of text and DOM elements to be created. Each outer array entry can be either a string containing an immediate new textNode, or it can contain an array where each entry is a selector/attribute pairing identical to the parameters you would pass to _.make. This behavior is the same as what happens if you pass an Array instead of Object to _.make or the behavior of that method's "content" pseudo-attribute.

Since it is identical to _.make's attribute parameter, it is possible to create a JSON structure containing a very deeply nested markup tree.

Example #1

HTML

<h1>Test</h1>

JavaScript

var
	h1 = document.getElementsByTagName('h1')[0],
	h2 = document.createElement('h2');
_.Node.write(h1, "\r\nAdded after the H1\r\n", 'after');
_.Node.write(h1, "Added before the H1\r\n", 'before');
_.Node.write(h1, "\r\nAdded before H1 content\r\n", 'first');
_.Node.write(h1, h2, 'after');
_.Node.write(h1, "\r\nAdded after H1 content\r\n", 'last');
_.Node.write(h2, 'Second Heading');
_.Node.write(h2, [
	[ 'p~Dynamically added paragraph after the second heading' ],
	[ 'p.test', [
		content : [
			'Another way of adding a paragraph, this time with a class ',
			[ 'a', { content : 'and an anchor!', href : '/' } ]
		]
	] ]
], 'after');

RESULT HTML (equivalent)

Added before the h1
<h1>
Added before H1 content
Test
Added after H1 content
</h1>
Added after the H1
<h2>Second Heading</h2>
<p>Dynamically added paragraph after the second heading</p>
<p class="test">Another way of adding a paragraph, this time with a class <a href="/">and an anchor!</a></p>

In practice much of the above would actually be coded using _.make. In fact, several of _.make's attributes Object properties call this method and vice-versa.