OBJECT:  Text

The Text object represents the text of an Element or an Attr object. (In XML this is referred to as character data as opposed to any markup that might be used to modify it.) If the text does contain markup, it is parsed into a list of markup elements with accompanying child text nodes.

When a document is first made available to the DOM, there is only one Text node for each block of text. Users may subsequently add adjacent Text nodes to represent the content of an Element without any intervening markup, but should be aware that there is no way to represent the separations between these nodes in XML or HTML, and that they will not persist between DOM editing sessions.

If you wish to maintain a DOM structure between sessions, it is recommended that you use the Element object's normalize method to combine adjacent Text nodes into one single one.

In the following example we load the 'albums.xml' file and append a new Text child node to the 'title' element of the last album. The code then iterates through that element's children displaying the value of each.

XML:
<Albums>
   <Album ref="CD142" category="Folk">
      <title>Boil The Breakfast Early</title>
      <artist>The Chieftains</artist>
   </Album>
   <Album ref="CD720" category="Pop">
      <title>Come On Over</title>
      <artist>Shania Twain</artist>
   </Album>
   <Album ref="CD024" category="Country">
      <title>Red Dirt Girl</title>
      <artist>Emmylou Harris</artist>
   </Album>
</Albums>

Code (VBScript):
Set objXMLDoc = CreateObject("Microsoft.XMLDOM")
objXMLDoc.async = False
objXMLDoc.load("albums.xml")

Set Elem = objXMLDoc.documentElement.childNodes.item(2).firstChild
Set Text = objXMLDoc.createTextNode("Move along, nothing to see here.")
Elem.appendChild(Text)
numChildren = Elem.childNodes.length

For i = 0 To numChildren-1
   document.write(Elem.childNodes.item(i).nodeValue & "<br>")
Next

Output:
Red Dirt Girl
Move along, nothing to see here.

A Text object is also a Node object, and so inherits various properties and methods from it. For details of the values returned by the nodeName, nodeType and nodeValue properties for a Text object, see the Node object.

denotes a Microsoft extension to the W3C DOM.

PROPERTIES

attributes Property
This is a read-only property that returns an NamedNodeMap for nodes that can have attributes.

Syntax: Node.attributes

baseName Property
This is a read-only property that returns the base name for a node.

Syntax: Node.baseName

childNodes Property
This is a read-only property containing a node list of all children for those elements that can have them.

Syntax: Node.childNodes

data Property
This property contains the data for this node, depending on node type.

Syntax: CharacterData.data

dataType Property
This is a read-only property that specifies the data type for the node.

Syntax: Node.dataType

definition Property
This property returns the definition of the node in the DTD or schema.

Syntax: Node.definition

firstChild Property
This is a read-only property that returns the first child node of a node. If there is none, it returns null.

Syntax: Node.firstChild

lastChild Property
This is a read-only property that returns the last child node of a node. If there is none, it returns null.

Syntax: Node.lastChild

length Property
This property is read-only and contains the length of the data string in characters.

Syntax: CharacterData.length

namespaceURI Property
This property is read-only and returns the URI (Universal Resource Indentifier) of the namespace.

Syntax: Node.namespaceURI

nextSibling Property
This property returns the next node in the parent's child list, or null if there is none or the node is of a type that cannot be a child node (Attr, Document, DocumentFragment).

Syntax: Node.nextSibling

nodeName Property
This property is read-only and contains the name of the node, depending on type.

Syntax: Node.nodeName

nodeType Property
This is a read-only property specifying the type of the node.

Syntax: Node.nodeType

nodeTypedValue Property
This property contains the value of this node expressed in its defined data type.

Syntax: Node.nodeTypedValue

nodeTypeString Property
This property is read-only and returns the node type in string form.

Syntax: Node.nodeTypeString

nodeValue Property
This property contains the value of the node, depending on type.

Syntax: Node.nodeValue

ownerDocument Property
This property returns the Document object to which the node belongs. If the node itself is a document, then it returns null.

Syntax: Node.ownerDocument

parentNode Property
This is a read-only property that returns the parent node of all nodes except Document, DocumentFragment and Attr, which cannot have parent nodes.

Syntax: Node.parentNode

parsed Property
This property returns a boolean value of true if this node and all of its descendants have been parsed and instantiated. Otherwise it returns false.

Syntax: Node.parsed

prefix Property
This property is read-only and returns the namespace prefix, or an empty string if none is specified. For example, it would return 'xxx' for the element <xxx:yyy>.

Syntax: Node.prefix

previousSibling Property
This property returns the previous node in the parent's child list, or null if there is none or the node is of a type that cannot be a child node (Attr, Document, DocumentFragment).

Syntax: Node.previousSibling

specified Property
This property returns a boolean value indicating whether this node (usually an attribute) is explicitly specified or derived from a default value in the DTD or schema.

Syntax: Node.specified

text Property
This property contains the text content of this node and its subtrees.

Syntax: Node.text

xml Property
This property contains the XML representation of this node and its descendants.

Syntax: Node.xml

METHODS

appendChild Method
This method appends a new child node to the list of children for this node.

Syntax: Node.appendChild(tagName)

appendData Method
This method appends the specified string to existing string data.

Syntax: CharacterData.appendData(data)

cloneNode Method
This method creates a clone node which is an exact replica of this node.

Syntax: Node.cloneNode(deep)

deleteData Method
This method is used to remove the specified range of characters from string data.

Syntax: CharacterData.deleteData(offset, count)

hasChildNodes Method
This method is a convenient way to determine whether a node has child nodes, returning true if it has, and false if not.

Syntax: Node.hasChildNodes( )

insertBefore Method
This method is used to insert a new child node before an existing one. If no child node exists, the new child node becomes the first.

Syntax: Node.insertBefore(newChild, refChild)

insertData Method
This method is used to insert a string at the specified offset.

Syntax: CharacterData.insertData(offset, data)

removeChild Method
This method removes the specified node from the list of children and returns it.

Syntax: Node.removeChild(oldChild)

replaceChild Method
This method is used to replace one of a node's children with another. It returns the old child.

Syntax: Node.replaceChild(newChild, oldChild)

replaceData Method
This method replaces the characters from the specified offset with the supplied string data.

Syntax: CharacterData.replaceData(offset, count, data)

selectNodes Method
This method creates a NodeList of all the matching descendant nodes returned by the specified pattern-matching operation.

Syntax: Node.selectNodes(patternString)

selectSingleNode Method
This method returns a Node object for the first descendant node to match the specified pattern.

Syntax: Node.selectSingleNode(patternString)

splitText Method
This method splits a Text node into two at the specified offset. It places all the characters from the offset to the end of the string into a new Text node that immediately follows this one.

Syntax: Text.splitText(offset)

substringData Method
This method returns a substring consisting of the specified range of characters.

Syntax: CharacterData.substringData(offset, count)

transformNode Method
This method processes this node and its descendants using the specified XSL stylesheet, and returns the resulting transformation.

Syntax: Node.transformNode(stylesheet)

transformNodeToObject Method
This method processes this node and its descendants using the specified XSL stylesheet, and returns the resulting transformation in the specified object.

Syntax: Node.transformNodeToObject(stylesheet, outputObject)


Copyright 1999-2001 by Infinite Software Solutions, Inc. All rights reserved.
Trademark Information