JavaScript: The Definitive Guide, Fourth Edition

Name

Range.surroundContents( ) — surround range contents with the specified node

Availability

DOM Level 2 Range

Synopsis

void surroundContents(Node newParent)
    throws RangeException, 
           DOMException;

Arguments

newParent

The node that is to become the new parent of the contents of this range.

Throws

This method throws a DOMException or RangeException with one of the following code values in the following circumstances:

DOMException.HIERARCHY_REQUEST_ERR

The container node of the start of the range does not allow children or does not allow children of the type of newParent, or newParent is an ancestor of that container node.

DOMException.NO_MODIFICATION_ALLOWED_ERR

An ancestor of a boundary point of the range is read-only and does not allow insertions.

DOMException.WRONG_DOCUMENT_ERR

newParent and this range were created using different Document objects.

RangeException.BAD_BOUNDARYPOINTS_ERR

The range partially selects a node (other than a Text node), so the region of the document it represents cannot be surrounded.

RangeException.INVALID_NODE_TYPE_ERR

newParent is a Document, DocumentFragment, DocumentType, Attr, Entity, or Notation node.

Description

This method reparents the contents of this range to newParent and then inserts newParent into the document at the start position of the range. It is useful to place a region of document content within a <b> or <span> element, for example.

If newParent is already part of the document, it is first removed from the document and any children ...