ChocolateChip simplifies inserting content into a document

DOM level 3 has some new ways of injecting content into a document. And on top of that ChocolateChip has its own handy utility methods for inserting content. Here’s the goods:

  1. Element.insertAdjacentText()
  2. Element.insertAdjacentHTML()
  3. Element.insertAdjacentNode()
  4. $.make()
  5. Element.insert()
  6. Element.before()
  7. Element.after()
  8. Element.fill()
  9. Element.prepend()
  10. Element.append()

All three of the insertAdjacent methods take two parameters, the place to insert and the content to insert. Passing in the correct parameter for position is very important for getting your content where you want it. This means that these insert methods do not replace the contents of the element with the content you pass in. Instead they insert it in juxtaposition to the element. You have four options for where you want to insert. IMPORTANT! These arguments must be in quotes or you’ll get an exception.

“beforeBegin”
This inserts the content immediately before the element so that the content become the previous sibling of the element.
“afterBegin”
This inserts the content into the element as its first child. This does not replace any other content already in the element.
“beforeEnd”
This inserts the content into the element as its last child. This does not replace any other content already in the element.
“afterEnd”
This inserts the content immediately after the element so that the content become the next sibling of the element.

Element.insertAdjacentText()

This method insert a string of text at the location passed in.

<p id="description">This is the main section.</p>
$(function() {
	$("#description").insertAdjacentText("beforeBegin", "This is before the description: ");
	$("#description").insertAdjacentText("afterBegin", "This is at the beginning of the description: ");
	$("#description").insertAdjacentText("beforeEnd", "This is at the end of the description: ");
	$("#description").insertAdjacentText("afterEnd", "This is after the end of the description: ");
});

Element.insertAdjacentHTML()

This is similar to the Element.insertAdjacentText() method, except that it creates HTML which it then inserts at the specified locations.

$(function() {
	$("#description").insertAdjacentHTML("beforeBegin", "<p>This is before the description: </p>");
	$("#description").insertAdjacentHTML("afterBegin", "<p>This is at the beginning of the description: </p>");
	$("#description").insertAdjacentHTML("beforeEnd", "<p>This is at the end of the description: </p>");
	$("#description").insertAdjacentHTML("afterEnd", "<p>This is after the end of the description: </p>");	
});

Element.insertAdjacentNode()

Like the previous two methods, this method inserts content into the designated locations, except that it uses existing nodes. You could pluck nodes from elsewhere in a document, or create them on the fly for inserting.

$(function() {
	var a1 = $.make("<p>First Paragraph</p>");
	var a2 = $.make("<p>Second Paragraph</p>");
	var a3 = $.make("<p>Third Paragraph</p>");
	var a4 = $.make("<p>Fourth Paragraph</p>");
	$("#description").insertAdjacentElement("beforeBegin", a1);
	$("#description").insertAdjacentElement("afterBegin", a2);
	$("#description").insertAdjacentElement("beforeEnd", a3);
	$("#description").insertAdjacentElement("afterEnd", a4);	
});

$.make()

$.make() is a method for creating HTML element nodes on the fly. It takes as its argument a string of valid markup. This must be correct syntax for the doctype used by the target document or the browser will not render it properly.

$(function() {
    var content = $.make("<p>This is a paragraph with some <strong>important</strong> and <em>trivial</em> information.</p>");
     var menu = $.make("<ul id="menu"><li>Item One</li><li>Item Two</li><li>Item Three</li></ul>");
});

$.insert()

The method does what the label say. It allows you to insert content into another element. The first argument is the content to insert. The second, optional argument is the position at which to insert the content. If no position is supplied it default to inserting the content at the end. As a convenience you can pass in “first” or “last” for a position. Otherwise a digit starting from 1 to indicate the position at which to insert. 1 is equivalent to “first.” If the numerical position passed as an argument is larger than the number of child nodes in the target element, it will be inserted in the last position. If the content passed in is a string, the method attempts to convert it into HTML nodes before inserting. If the content consists of HTML nodes, the method inserts them at the indicated position.

$(function() {
    // Insert this at the beginning:
    $("#response").insert("<p>A new paragraph.</p>", "first");
    // Insert this at the end:
    $("#response").insert("<p>Another paragraph at the end.</p>", "last");
    // Insert this at position 5, that is, as the fifth child of the element:
    $("#response").insert("<p>An important update.</p>", 5);
});

$.before()

This method inserts content before the target element. The inserted content thus becomes the target’s previous sibling. The content passed in can be a node or an array of nodes.

$(function() {
     var newNode $.make("<h1>An Important Announcement</h1>");
    $("body > p").before(newNode);
});

$.after()

This method inserts content after the target element. Thus the content becomes the next sibling of the target. The content passed in can be a node or an array of nodes.

$(function() {
     var newNode $.make("<li>The last item is always the most important!</li>");
    $("ul#importantList").after(newNode);	
});

$.fill()

This method replaces the contents of the element with the content passed as an argument. Unlike other methods above, this method does not attempt to convert a string into HTML before insertion. Rather it is primarily for replace the text content of an element with the text passed in. However, if a node is passed it, it will insert it into the element. This method always replaces whatever the content of the element is, even if that consists of multiple child nodes.

$(function() {
    $("#update").fill("This page has just been updated");
});

Element.prepend()

As of version 1.1.9 ChocolateChip offers the element.prepend method. This allows you to insert content at the beginning of a collection of nodes. If the parent is empty, the content will simply be inserted. This is just a convenience method to mimic the jQuery equivalent.

$(".menu").prepend("<li>item 1</li><li>item 2</li><li>item3</li>");

Element.append()

As of version 1.1.9 ChocolateChip offers the element.append method. This allows you to insert content at the end of a collection of nodes. If the parent is empty, the content will simply be inserted. This is just a convenience method to mimic the jQuery equivalent.

$(".menu").append("<li>Final item here</li>");
Advertisements