jQuery 1.4 DOM Insertion Methods

Exclusive offer: get 50% off this eBook here
jQuery Reference Guide

jQuery Reference Guide — Save 50%

A Comprehensive Exploration of the Popular JavaScript Library

$23.99    $12.00
by Jonathan Chaffer Karl Swedberg | February 2010 | AJAX Open Source Web Development

All of the methods in this article by Karl Swedberg and Jonathan Chaffer, authors of jQuery 1.4 Reference Guide, manipulate the DOM in some manner. In a previous article we saw methods that simply change one of the attributes of an element, while others set an element's style properties. In this article we cover methods for DOM insertion—inside, outside, and around. These methods allow us to insert new content inside and outside an existing element, and also surrounding existing content.

DOM insertion, inside

These methods allow us to insert new content inside an existing element.

.prepend()

Insert content specified by the parameter at the beginning of each element in the set of matched elements.

.prepend(content)
.prepend(function)

Parameters (first version)

  • content: An element, an HTML string, or a jQuery object to insert at the beginning of each element in the set of matched elements

Parameters (second version)

  • function: A function that returns an HTML string to insert at the beginning of each element in the set of matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .prepend() and .prependTo() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .prepend(), the selector expression preceding the method is the container into which the content is inserted. With .prependTo(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly. It is then inserted into the target container.

Consider the following HTML code:

<h2>Greetings</h2>
<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once.

$('.inner').prepend('<p>Test</p>');

Each <div class="inner"> element gets the following new content:

<h2>Greetings</h2>
<div class="container">
<div class="inner">
<p>Test</p>
Hello
</div>
<div class="inner">
<p>Test</p>
Goodbye
</div>
</div>

We can also select an element on the page and insert it into another:

$('.container').prepend($('h2'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned).

<div class="container">
<h2>Greetings</h2>
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

However, if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

.prependTo()

Insert every element in the set of matched elements at the beginning of the target.

.prependTo(target)

Parameters

  • target: A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted at the beginning of the element(s) specified by this parameter

Return value

The jQuery object, for chaining purposes.

Description

The .prepend() and .prependTo() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .prepend(), the selector expression preceding the method is the container into which the content is inserted. With .prependTo(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted into the target container.

Consider the following HTML code:

<h2>Greetings</h2>
<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once.

$('<p>Test</p>').prependTo('.inner');

Each inner <div> element gets the following new content:

<h2>Greetings</h2>
<div class="container">
<div class="inner">
<p>Test</p>
Hello
</div>
<div class="inner">
<p>Test</p>
Goodbye
</div>
</div>

We can also select an element on the page and insert it into another.

$('h2').prependTo($('.container'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned).

<div class="container">
<h2>Greetings</h2>
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

However, if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

.append()

Insert content specified by the parameter at the end of each element in the set of matched elements.

.append(content)
.append(function)

Parameters (first version)

  • content: An element, an HTML string, or a jQuery object to insert at the end of each element in the set of matched elements

Parameters (second version)

  • function: A function that returns an HTML string to insert at the end of each element in the set of matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .append() and .appendTo() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .append(), the selector expression preceding the method is the container into which the content is inserted. With .appendTo(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted into the target container.

Consider the following HTML code:

<h2>Greetings</h2>
<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once.

$('.inner').append('<p>Test</p>');

Each inner <div> element gets the following new content:

<h2>Greetings</h2>
<div class="container">
<div class="inner">
Hello
<p>Test</p>
</div>
<div class="inner">
Goodbye
<p>Test</p>
</div>
</div>

We can also select an element on the page and insert it into another.

$('.container').append($('h2'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned).

<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
<h2>Greetings</h2>
</div>

However, if there is more than one target element, cloned copies of the inserted elements will be created for each target after the first.

.appendTo()

Insert every element in the set of matched elements at the end of the target.

.appendTo(target)

Parameters

  • target: A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted at the end of the element(s) specified by this parameter

Return value

The jQuery object, for chaining purposes.

Description

The .append() and .appendTo() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .append(), the selector expression preceding the method is the container into which the content is inserted. With .appendTo(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted into the target container.

Consider the following HTML code:

<h2>Greetings</h2>
<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once.

$('<p>Test</p>').appendTo('.inner');

Each inner <div> element gets the following new content:

<h2>Greetings</h2>
<div class="container">
<div class="inner">
Hello
<p>Test</p>
</div>
<div class="inner">
Goodbye
<p>Test</p>
</div>
</div>

We can also select an element on the page and insert it into another.

$('h2').append($('.container'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned).

<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
<h2>Greetings</h2>
</div>

However, if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

jQuery Reference Guide A Comprehensive Exploration of the Popular JavaScript Library
Published: July 2007
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:

DOM insertion, outside

These methods allow us to insert new content outside an existing element.

.before()

Insert content specified by the parameter before each element in the set of matched elements.

.before(content)
.before(function)

Parameters (first version)

  • content: An element, an HTML string, or a jQuery object to insert before each element in the set of matched elements

Parameters (second version)

  • function: A function that returns an HTML string to insert before each element in the set of matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .before() and .insertBefore() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .before(), the selector expression preceding the method is the container before which the content is inserted. With .insertBefore(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted before the target container.

Consider the following HTML code:

<div class="container">
<h2>Greetings</h2>
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

We can create content and insert it before several elements at once.

$('.inner').before('<p>Test</p>');

Each inner <div> element gets the following new content:

<div class="container">
<h2>Greetings</h2>
<p>Test</p>
<div class="inner">Hello</div>
<p>Test</p>
<div class="inner">Goodbye</div>
</div>

We can also select an element on the page and insert it before another.

$('.container').before($('h2'));

If an element selected this way is inserted elsewhere, it will be moved before the target (not cloned).

<h2>Greetings</h2>
<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

However, if there is more than one target element, cloned copies of the inserted elements will be created for each target after the first.

.insertBefore()

Insert every element in the set of matched elements before the target.

.insertBefore(target)

Parameters

  • target: A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted before the element(s) specified by this parameter.

Return value

The jQuery object, for chaining purposes.

Description

The .before() and .insertBefore() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .before(), the selector expression preceding the method is the container before which the content is inserted. With .insertBefore(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted before the target container.

Consider the following HTML code:

<div class="container">
<h2>Greetings</h2>
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

We can create content and insert it before several elements at once.

$('<p>Test</p>').insertBefore('.inner');

Each inner <div> element gets the following new content:

<div class="container">
<h2>Greetings</h2>
<p>Test</p>
<div class="inner">Hello</div>
<p>Test</p>
<div class="inner">Goodbye</div>
</div>

We can also select an element on the page and insert it before another.

$('h2').insertBefore($('.container'));

If an element selected this way is inserted elsewhere, it will be moved before the target (not cloned).

<h2>Greetings</h2>
<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

However if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

.after()

Insert content specified by the parameter after each element in the set of matched elements.

.after(content)
.after(function)

Parameters (first version)

  • content: An element, HTML string, or jQuery object to insert after each element in the set of matched elements

Parameters (second version)

  • function: A function that returns an HTML string to insert after each element in the set of matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .after() and .insertAfter() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .after(), the selector expression preceding the method is the container after which the content is inserted. With .insertAfter(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted after the target container.

Consider the following HTML code:

<div class="container">
<h2>Greetings</h2>
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

We can create content and insert it after several elements at once.

$('.inner').after('<p>Test</p>');

Each inner <div> element gets the following new content:

<div class="container">
<h2>Greetings</h2>
<div class="inner">Hello</div>
<p>Test</p>
<div class="inner">Goodbye</div>
<p>Test</p>
</div>

We can also select an element on the page and insert it after another.

$('.container').after($('h2'));

If an element selected this way is inserted elsewhere, it will be moved after the target (not cloned).

<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>
<h2>Greetings</h2>

However, if there are more than one target elements, cloned copies of the inserted element will be created for each target after the first.

.insertAfter()

Insert every element in the set of matched elements after the target.

.insertAfter(target)

Parameters

  • target: A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted after the element(s) specified by this parameter

Return value

The jQuery object, for chaining purposes.

Description

The .after() and .insertAfter() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .after(), the selector expression preceding the method is the container after which the content is inserted. With .insertAfter(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted after the target container.

Consider the following HTML code:

<div class="container">
<h2>Greetings</h2>
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

We can create content and insert it after several elements at once.

$('<p>Test</p>').insertAfter('.inner');

Each inner <div> element gets the following content:

<div class="container">
<h2>Greetings</h2>
<div class="inner">Hello</div>
<p>Test</p>
<div class="inner">Goodbye</div>
<p>Test</p>
</div>

We can also select an element on the page and insert it after another.

$('h2').insertAfter($('.container'));

If an element selected this way is inserted elsewhere, it will be moved after the target (not cloned).

<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>
<h2>Greetings</h2>

However, if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

jQuery Reference Guide A Comprehensive Exploration of the Popular JavaScript Library
Published: July 2007
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:

DOM insertion, around

These methods allow us to insert new content surrounding existing content.

.wrap()

Wrap an HTML structure around each element in the set of matched elements.

.wrap(wrappingElement)
.wrap(wrappingFunction)

Parameters (first version)

  • wrappingElement: An HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the matched elements

Parameters (second version)

  • wrappingFunction: A callback function that generates a structure to wrap around the matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .wrap() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around each of the elements in the set of matched elements.

Consider the following HTML code:

<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

Using .wrap(), we can insert an HTML structure around the inner <div> elements as follows:

$('.inner').wrap('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around each matched element.

<div class="container">
<div class="new">
<div class="inner">Hello</div>
</div>
<div class="new">
<div class="inner">Goodbye</div>
</div>
</div>

The second version of this method allows us to specify a callback function instead. This callback function will be called once for every matched element. It should return a DOM element, a jQuery object, or an HTML snippet in which to wrap the corresponding element. For example:

$('.inner').wrap(function() {
return '<div class="' + $(this).text() + '" />';
});

This will cause each <div> to have a class corresponding to the text it wraps.

<div class="container">
<div class="Hello">
<div class="inner">Hello</div>
</div>
<div class="Goodbye">
<div class="inner">Goodbye</div>
</div>
</div>

.wrapAll()

Wrap an HTML structure around all elements in the set of matched elements.

.wrapAll(wrappingElement)

Parameters

  • wrappingElement: An HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .wrapAll() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around all of the elements in the set of matched elements as a single group.

Consider the following HTML code:

<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

Using .wrapAll(), we can insert an HTML structure around the inner <div> elements as follows:

$('.inner').wrapAll('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around all matched elements.

<div class="container">
<div class="new">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>
</div>

.wrapInner()

Wrap an HTML structure around the content of each element in the set of matched elements.

.wrapInner(wrappingElement)
.wrapInner(wrappingFunction)

Parameters (first version)

  • wrappingElement: An HTML snippet, a selector expression, a jQuery object, or a DOM element specifying the structure to wrap around the content of the matched elements

Parameters (second version)

  • wrappingFunction: A callback function that generates a structure to wrap around the content of the matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .wrapInner() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around the content of each of the elements in the set of matched elements.

Consider the following HTML code:

<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

Using .wrapInner(), we can insert an HTML structure around the content of the inner <div> elements as follows:

$('.inner').wrapInner('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around the content of each matched element.

<div class="container">
<div class="inner"> <div class="new">Hello</div>
</div>
<div class="inner">
<div class="new">Goodbye</div>
</div>
</div>

The second version of this method allows us to specify a callback function instead. This callback function will be called once for every matched element; it should return a DOM element, jQuery object, or HTML snippet in which to wrap the content of the corresponding element. For example:

$('.inner').wrapInner(function() {
return '<div class="' + this.nodeValue + '" />';
});

This will cause each new <div> to have a class corresponding to the text it wraps.

<div class="container">
<div class="inner">
<div class="Hello">Hello</div>
</div>
<div class="inner">
<div class="Goodbye">Goodbye</div>
</div>
</div>

Summary

In this article we have covered DOM manipulation methods for Insertion inside, outside and also surrounding existing content.


If you have read this article you may be interested to view :


About the Author :


Jonathan Chaffer

Jonathan Chaffer is a member of Rapid Development Group, a web development firm located in Grand Rapids, Michigan. His work there includes overseeing and implementing projects in a wide variety of technologies, with an emphasis in PHP, MySQL, and JavaScript. He also leads on-site training seminars on the jQuery framework for web developers.

In the open source community, he has been very active in the Drupal CMS project, which has adopted jQuery as its JavaScript framework of choice. He is the creator of the Content Construction Kit, a popular module for managing structured content on Drupal sites. He is also responsible for major overhauls of Drupal's menu system and developer API reference.

He lives in Grand Rapids with his wife, Jennifer.

Karl Swedberg

Karl Swedberg is a web developer at Fusionary Media in Grand Rapids, Michigan, where he spends much of his time making cool things happen with JavaScript. As a member of the jQuery team, he is responsible for maintaining the jQuery API site at api.jquery.com. He is also a member of jQuery's Board of Advisors and a presenter at workshops and conferences. When he isn't coding, he likes to hang out with his family, roast coffee in his garage, and exercise at the local CrossFit gym.

Books From Packt

jQuery UI 1.7: The User Interface Library for jQuery
jQuery UI 1.7: The User Interface Library for jQuery

jQuery 1.3 with PHP
jQuery 1.3 with PHP

Drupal 6 JavaScript and jQuery
Drupal 6 JavaScript and jQuery

AJAX and PHP: Building Modern Web Applications 2nd Edition
AJAX and PHP: Building Modern Web Applications 2nd Edition

Backbase 4 RIA Development
Backbase 4 RIA Development

CodeIgniter 1.7
CodeIgniter 1.7

TYPO3 4.3 Multimedia Cookbook
TYPO3 4.3 Multimedia Cookbook

Learning jQuery 1.3
Learning jQuery 1.3

No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
E
i
Q
q
A
k
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software