Directory listing of http: uap.unnes.ac.id ebook biblebook Visual Basic 6 com & Library Books
21
C H A P T E R
The Document
Object M odel
✦
✦
✦
✦
In This Cha pter
M
ic ro so ft has develo ped a to o l fo r c reating and parsing
XML do c uments c alled MSXML. MSXML implements
the XML Do c ument Objec t Mo del (DOM) as defined by the
Wo rldwide Web Co nso rtium (usually c alled W3C). W3C is an
internatio nal standards bo dy that is respo nsible fo r the standards (suc h as HTML, XML, XSP, and so o n) that are used to
ac c ess the Web.
The DOM sto res an XML do c ument as a series o f o b jec ts that
c an b e easily ac c essed b y an applic atio n pro gram. MSXML
implements DOM as a series o f COM o b jec ts fo r use o n
Windo ws-b ased c o mputers. This means that these o b jec ts
are independent o f any pro gramming language and datab ase
server and c an b e used with Visual Basic , Visual C++, ASP
sc ript files, SQL Server, and Orac le 8i witho ut pro b lems.
In this c hapter, I’ll disc uss ho w to use the Do c ument Objec t
Mo del to c reate and parse XML do c uments.
Note
Basically beta: The version of the Docum ent Object Model
discussed in this book is based on the March 2000 beta
release of MSXML. At the tim e I w rote this chapter, the
W3C hadn’t finalized the specifications for DOM, and as a
consequence, Microsoft’s im plem entation of it in MSXML is
still subject to change.
The Document Object M odel
Mic ro so ft’s implementatio n o f the Do c ument Objec t Mo del
c o nfo rms fairly c lo sely to the W3C’s rec o mmendatio n, but rec o mmendatio ns c an be fairly c o mplex to understand. The DOM
is based o n a hierarc hic al o rganizatio n o f o bjec t no des who se
types vary, as different types o f info rmatio n are sto red in the
Intro ducing the
Do cument O bject
Mo del
Understanding the
do cument hierarchy
Using the DO M
O bjects
✦
✦
✦
✦
456
Part V ✦ The Impact of XM L
do c ument hierarc hy. In additio n, a number o f o ther o bjec ts are sto red there that
c o ntain spec ific piec es o f info rmatio n o r utility func tio ns.
Document hierarchy
The basic DOM hierarc hy is sho wn in Figure 21-1. The ro o t no de o f the hierarc hy
is the DOMDocument o bjec t, whic h enc o mpasses the entire XML do c ument. As yo u
desc end thro ugh the tree struc ture, o ther no des represent a partic ular piec e o f
info rmatio n o r gro up o f info rmatio n in the XML do c ument.
DOM Document
XM LDOM PrecessingInstruction
XM LDOM Text
XM LDOM Element
XM LDOM CDATASection
XM LDOM Element
XM LDOM Text
XM LDOM Comment
XM LDOM DocumentType
XM LDOM Notation
XM LDOM Entity
XM LDOM Comment
XM LDOM Attribute
XM LDOM PrecessingInstruction
XM LDOM EntityReference
XM LDOM EntityReference
Figure 21-1: View ing the Docum ent Object Model object hierarchy
The basic o bjec t is the XMLDOMNode o bjec t, fro m whic h all o f the o ther no des
are derived. In to tal, there are a do zen different types o f no des. Aside fro m the
DOMDocument o bjec t, all o f the o ther o bjec ts begin with XMLDOM.
Chapter 21 ✦ The Document Object M odel
✦ DOMDocument – This is the highest-level o bjec t in the hierarc hy. It enc o mpasses the entire XML do c ument. It also inc ludes additio nal metho ds and
pro perties that c an be used to o btain an XML do c ument o r to c reate o ther
no des.
✦ XMLDOMAttribute – This o bjec t is used to ho ld info rmatio n abo ut a single
attribute in an element. It is no t c o nsidered a true no de value sinc e it is referenc ed thro ugh the attributes pro perty, rather than the childNodes pro perty.
✦ XMLDOMCDATASection – This o bjec t is similar to the IXMLDOMText o bjec t,
exc ept it c o ntains data that was sto red in a CDATA sec tio n in the XML do c ument. The CDATA sec tio n begins with the
string. Any c harac ters in between the two CDATA delimiters are treated as
no rmal text. This lets yo u inc lude any text into a text field, inc luding elements
that wo uld no rmally be pro c essed by the XML parser.
✦ XMLDOMComment – This o bjec t ho lds an XML c o mment element, whic h is the
string o f c harac ters between the .
✦ XMLDOMDocumentType – This o bjec t c o ntains info rmatio n abo ut the Do c ument
Type Dec laratio ns inc luded in an XML do c ument.
✦ XMLDOMElement – This o bjec t c o ntains info rmatio n abo ut a single element in
an XML do c ument. If the element in the do c ument c o ntains o ther, nested elements, then the childNodes pro perty will c o ntain referenc es to these o bjec ts.
The attributes pro perty c an be used to find the IXMLDOMAttribute o bjec ts,
whic h c o ntain info rmatio n abo ut the attributes fo und in this element.
✦ XMLDOMEntity – This o bjec t c o ntains info rmatio n abo ut a parsed o r unparsed
entity in the XML do c ument.
✦ XMLDOMEntityReference – This o bjec t c o ntains info rmatio n abo ut an entity
referenc e in the XML do c ument.
✦ XMLDOMNode – This o bjec t is the fundamental o bjec t o f the Do c ument Objec t
Mo del. All o f the o ther o bjec ts that c an ac t as a no de in the hierarc hy are
derived fro m this o bjec t.
✦ XMLDOMNotation – This o bjec t c o ntains no tatio n info rmatio n fro m a
Do c ument Type Dec laratio n o r a sc hema.
✦ XMLDOMProcessingInstruction – This o bjec t c o ntains pro c essing info rmatio n fo r the XML do c ument. Fo r example, this o bjec t will sto re the info rmatio n
fo und in the tag that is fo und at the start o f mo st
XML do c uments.
✦ XMLDOMText – This o bjec t c o ntains the text value fo und in between the and tags in a do c ument.
457
458
Part V ✦ The Impact of XM L
Note
To IXM LDOM or not to IXM LDOM : Microsoft frequently prefixes the node nam es
w ith an I in their im plem entation of the object m odel. The I prefix is a C+ + convention that indicates that the object is a COM Interface, w hich just another object
to a Visual Basic program m er.
Other objects
Here are a few o ther o bjec ts that yo u may find interesting. These o bjec ts c anno t be
used in plac e o f a no de o bjec t, but o ffer spec ialized suppo rt servic es.
✦ XMLDOMDocumentFragment – This o b jec t is used to sto re part o f an XML
do c ument. Yo u might find it useful if yo u want to restruc ture an XML o b jec t
hierarc hy.
✦ XMLDOMImplementation – This o bjec t allo ws yo u to detec t vario us features
inc luded in a partic ular implementatio n o f the Do c ument Objec t Mo del.
✦ XMLDOMNodeList – This o bjec t is a c o ntainer fo r a c o llec tio n o f no des. This
o bjec t is typic ally returned by several metho ds that yo u c an use to searc h fo r
spec ific elements in the do c ument hierarc hy.
✦ XMLDOMParseError – This o bjec t c o ntains info rmatio n abo ut any erro rs that
o c c urred while parsing yo ur XML do c ument.
✦ XMLHttpRequest – This o bjec t allo ws yo u to send and rec eive info rmatio n
using an HTTP c o nnec tio n.
The XM LDOM Node Object
The XMLDOMNode o bjec t is the fundamental o bjec t in the Do c ument Objec t Mo del. It
fo rms the basis o f all the o ther no de o bjec ts that ho ld yo ur XML do c ument. Eac h o f
tho se o bjec ts will inherit the XMLDOMNode’s pro perties and metho ds, to whic h it
may add unique pro perties, metho ds, and events.
XM LDOM Node object properties
Table 21-1 lists the pro perties asso c iated with the XMLDOMNode o bjec t.
Chapter 21 ✦ The Document Object M odel
Table 21-1
Properties of the XM LDOM Node object
Property
Description
attributes
An object reference to a node containing the attributes.
Returns NULL if this node doesn’t have any attributes.
baseName
A String value containing right side of a fully qualified
nam e of the docum ent.
childNodes
An object reference to one of several different
collections depending on the value of nodeType (see
Table 21-2).
dataType
A Variant value that is either a String containing the
nam e of the data type associated w ith the node or
VT_NULL if no data type is defined.
definition
An object reference to a node in the docum ent type
definition or schem a, if included.
firstChild
An object reference to the first child node of this node.
Returns NULL if this node doesn’t have any children.
lastChild
An object reference to the last child node of this node.
Returns NULL if this node doesn’t have any children.
namespaceURI
A String containing the Universal Resource Identifier
(URI) of the nam espace.
nextSibling
An object reference to the next sibling of this node. If
there are no m ore siblings, then this value is NULL.
nodeName
A String value containing the nam e of the node.
nodeType
An enum erated data type containing the type of the
node (see Table 21-2).
nodeTypedValue
A String value containing the node’s value in its
defined data type.
nodeTypeString
A String value containing a value corresponding to
the value of nodeType. See Table 21-2 for the string
values that correspond to the nodeType value.
nodeValue
A String value containing the text associated w ith
the node.
ownerDocument
An object reference to the root DOMDocument object or
the DOMDocument, w hich created this object.
Continued
459
460
Part V ✦ The Impact of XM L
Table 21-1 (continued)
Property
Description
parentNode
An object reference to the parent object of this node.
parsed
A Boolean w hen True m eans that this node and all of
its descendents have been parsed.
prefix
A String containing the nam espace prefix.
previousSibling
An object reference to the previous sibling of this node.
If this is the first node, then this value w ill be NULL.
specified
A Boolean value w hen True m eans that the value w as
specified, rather than being derived from a default value
in the DTD or schem a.
text
A String containing the text value of the current node
and all of its subtrees.
xml
A String containing the XML statem ents that m ake up
the current docum ent.
XM LDOM Node object methods
The XMLDOMNode o bjec t has a number o f metho ds that are used to manage the c hild
no des asso c iated with it.
Function appendChild (newChild As IXM LDOM Node) as IXM LDOM Node
The appendChild metho d is used to add a no de o bjec t as a c hild o f the c urrent
no de. It returns an o bjec t to the newly added c hild no de. This metho d is the equivalent o f c alling insertBefore ( newChild, NULL). newChild is an o bjec t referenc e to
a no de, whic h will be added as a c hild to the c urrent no de.
Function cloneNode (deep As Boolean) as IXM LDOM Node
The cloneNode metho d is used to c reate a c o py o f the c urrent no de. deep is a
Boolean, when True means that all o f the c hild no des o f the c urrent no de are to be
c lo ned also .
Table 21-2
Values for nodeType
Integer
String
Description
NODE_ELEMENT
1
element
Represents an elem ent. Can be a child of the
Document, DocumentFragment, EntityReference
and Element nodes. Can have one or m ore Element,
Text, Comment, ProcessingInstruction,
CDATASection, and EntityReference nodes as
children.
NODE_ATTRIBUTE
2
attribute
Represents an attribute. Referenced though an Entity
node. Can have the Text and the EntityReference
nodes as children. Technically, an Attribute is not
considered a child of the Element node, since it is
referenced through the attributes property.
NODE_TEXT
3
Text
Represents the text content of a tag. Can be a child of the
Attribute, DocumentFragment, Element, and
EntityReference nodes. Cannot have any child nodes.
NODE_CDATA_SECTION
4
cdatasection
Represents a CDATA section, w hich is used to escape blocks
of text that m ight be recognized as m arkup. Can be a child
of the DocumentFragment, EntityReference, and
Element nodes. Cannot have any child nodes.
NODE_ENTITY_REFERENCE
5
Entityreference
Represents an entity. Can be a child of the Attribute,
DocumentFragment, Element, and EntityReference
nodes. Can have the Element,
ProcessingInstruction, Comment, Text,
CDATASection, and EntityReference nodes
as children.
NODE_ENTITY
6
Entity
Represents an expanded entity. Can be a child of the
DocumentType node. Can have other nodes as child
nodes.
Continued
Chapter 21 ✦ The Document Object M odel
Constant
461
462
Table 21-2 (continued)
Integer
String
Description
NODE_PROCESSING_INSTRUCTION
7
processinginstruction
Can be a child of the Document, Document
Fragment, Element, and EntityReference
nodes. Cannot have any child nodes.
NODE_COMMENT
8
comment
Represents a com m ent. Can be a child of the
Document, DocumentFragment, Element, and
EntityReference nodes. Cannot have any child
nodes.
NODE_DOCUMENT
9
document
Represents an XML docum ent. Cannot be a child
of any other nodes. Can have exactly one child
node, w hich can be an Element, a
ProcessingInstruction, a Comment, or a
DocumentType node.
NODE_DOCUMENT_TYPE
10
Documenttype
Represents a docum ent type declaration. Can be a
child of the Document node. Can have Notation
and Entity nodes as child nodes.
NODE_DOCUMENT_FRAGMENT
11
documentfragment
Represents a node or subtree w ith a docum ent
w ithout being contained w ithin the docum ent.
Cannot be a child of any other nodes. Can have
Element, ProcessingInstruction, Comment,
Text, CDATASection, and EntityReference
nodes as child nodes.
NODE_NOTATION
12
notation
Represents a notation in the docum ent. Can be a
child of the DocumentType node. Cannot have
any child nodes.
Part V ✦ The Impact of XM L
Constant
Chapter 21 ✦ The Document Object M odel
Function hasChildNodes ( ) as Boolean
The hasChildNodes metho d returns True if the c urrent no de has c hildren.
Function insertBefore (newChild As ICM LDOM Node, refChild) as
IXM LDOM Node
The insertBefore metho d is used to add a c hild no de to the c urrent no de. The
no de will be inserted befo re the no de spec ified in refChild. An o bjec t referenc e to
newChild will be returned as the value o f the metho d.
newChild is an o bjec t referenc e to the no de to be added. refChild is an o bjec t referenc e to a no de that is a c hild o f the c urrent no de. If this parameter is NULL, then
the no de will be added to the end o f the c o llec tio n.
Function removeChild (childNode as ICM LDOM Node) as
IXM LDOM Node
The removeChild metho d is used to remo ve the spec ified no de fro m the c urrent
no de’s c hild no des. The no de is no t destro yed, so yo u sho uld set the no de to
Nothing to free the no de’s reso urc es if yo u really want to delete it. An o bjec t referenc e to the remo ved no de will be returned by the metho d. childNode is an o bjec t
referenc e to the no de to be remo ved.
Function replaceChild (newChild As ICM LDOM Node, oldChild As
ICM LDOM Node) as IXM LDOM Node
The removeChild metho d is used to replac e an existing no de with a new no de. The
metho d will return an o bjec t referenc e to the o ld no de.
newChild is an o bjec t referenc e to a new no de. oldChild is an o bjec t referenc e to
o ne o f the c urrent no de’s c hild no des that will be replac ed with newChild.
Function selectNodes (queryString As String) as IXM LDOM NodeList
The selectNodes metho d searc hes the c urrent o b jec t and its c hildren fo r elements that matc h the spec ified XSL pattern string, and returns them as an
IXMLDOMNodeList. queryString is a String value c o ntaining an XSL Pattern
q uery.
Function selectSingleNode (queryString As String) as IXM LDOM Node
The selectSingleNode metho d searc hes the c urrent o bjec t and its c hildren fo r
the first element that matc hes the spec ified XSL pattern string, and returns it as an
IXMLDOMNode. queryString is a String value c o ntaining an XSL Pattern query.
463
464
Part V ✦ The Impact of XM L
Function transformNode (stylesheet As IXM LDOM Node) as String
The transformNode metho d returns a String value c o ntaining a fo rmatted XML
do c ument using the spec ified XSL style sheet. stylesheet is an o bjec t referenc e to
an IXMLDOMNode o bjec t c o ntaining the ro o t o f the XSL style sheet.
Sub transformNodeToObject (stylesheet As IXM LDOM Node,
outputObject)
The transformNodeToObject metho d c reates a DOMDocument struc ture c o ntaining
the fo rmatted XML do c ument using the spec ified XSL style sheet. stylesheet is
an o bjec t referenc e to an IXMLDOMNode o bjec t c o ntaining the ro o t o f the XSL style
sheet. outputObject is an o bjec t referenc e to a DOMDocument o bjec t whic h will
c o ntain the ro o t o bjec t o f the fo rmatted do c ument.
The DOM Document Object
The DOMDocument o bjec t is the fundamental o bjec t in the Do c ument Objec t Mo del.
It represents a single XML do c ument.
DOM Document object properties
The DOMDocument o bjec t has all o f the pro perties o f the XMLDOMNode o bjec t (see
Table 21-1), plus the additio nal o nes listed in Table 21-3.
Table 21-3
Unique Properties of the DOMDocument Object
Property
Description
async
A Boolean value w hen True m eans that the Load m ethod
w ill return control to the caller before the load is com plete.
You m ust use the readyState property or the
onReadyStateChange event to determ ine w hen the load
process is finished.
doctype
An object reference to an XMLDOMDocumentType object
(specified w ith the < !DOCTYPE> tag) containing the
docum ent type definition.
documentElement
An object reference to the root elem ent of the docum ent.
implementation
An object reference to the XMLDOMImplementation object,
w hich contains inform ation about the features that are
supported in this im plem entation of DOM.
Chapter 21 ✦ The Document Object M odel
Note
Property
Description
namespaces
An object reference to an XMLDOMSchemaCache object that
contains the collection of nam espaces used in this XML
docum ent.
ondataavailable
A Boolean value, w hen True m eans that the
ondataavailable event is enabled.
onreadystatechange
A Boolean value, w hen True m eans that the
onreadystatechange event is enabled.
ontransformnode
A Boolean value, w hen True m eans that the
ontransformnode event is enabled.
parseError
An object reference to the XMLDOMParseError object, w hich
contains inform ation about the last parsing error.
preserveWhiteSpace
A Boolean, w hen True m eans that the parsing process w ill
retain the blanks that are included in the XML source
docum ent.
readyState
A Long value describing the state of the docum ent, w hen
loading the docum ent asynchronously (see the async
property). A value of LOADING (1) m eans that the XML source
docum ent is being loaded; a value of LOADED (2) m eans that
the docum ent is loaded, but none of the objects are available
for access; a value of INTERACTIVE (3) m eans that som e
objects are available for use; a value of COMPLETED (4) m eans
that the docum ent has been loaded and all objects are
available for access. Note that a value of COMPLETED doesn’t
im ply that the docum ent loaded successfully.
resolveExternals
A Boolean value, w hen True m eans that external definitions
such as nam espaces, DTD external subsets, and external entity
references should be resolved at parse tim e.
schemas
An object reference to an XMLSchemaCache object containing
a list of schem as that should be used w hen loading an XML
docum ent.
url
A String value containing the URL that w as used to load the
XML docum ent.
validateOnParse
A Boolean, w hen True m eans that the docum ent’s structure
should be validated during parsing.
Enabled, but impossible: Sim ply setting the ondataavailable, onreadystatechange, and ontransformnode properties to True is not sufficient to
enable the corresponding events. You m ust declare the Document object using
the WithEvents keyw ord at the m odule level in your program in order to include
code for the events.
465
466
Part V ✦ The Impact of XM L
DOM Document object methods
The DOMDocument o bjec t has a number o f unique metho ds that are used to c reate
and ac c ess the info rmatio n in an XML do c ument.
Sub Abort ( )
The Abort metho d will c anc el an async hro no us do wnlo ad. This will return an erro r
in the XMLDOMParseError o bjec t indic ating that the do wnlo ad was abo rted.
Function createAttribute (name As String) as IXM LDOM Attribute
The createAttribute metho d c reates an empty attribute o bjec t with the spec ified
name. No te that the newly c reated no de must be added to ano ther no de using the
appendChild metho d. name is a String value c o ntaining the name o f the attribute.
Function createCDATASection (data As String) as
IXM LDOM CDATASection
The createCDATASection metho d c reates an empty IXMLDOMCDATASection
o bjec t with the spec ified data. No te that the newly c reated no de must be added to
ano ther no de using the appendChild metho d. data is a String value that will be
sto red in the new o bjec t’s nodeValue pro perty.
Function createNode (type, name As String, namespaceURI As String)
as IXM LDOM Node
The createNode metho d c reates an empty no de in the do c ument. No te that the
newly c reated no de must be added to ano ther no de using the appendChild
metho d. type is either a String value c o ntaining the type o f the no de o r an
Integer c o ntaining the numeric value c o rrespo nding to the type o f the no de (see
Table 21-2) name is a String value c o ntaining the name o f the no de that will be
sto red in the nodeName pro perty. namespaceURI is a String c o ntaining the URI o f
the namespac e.
Function createProcessingInstruction (target As String, data As String)
as IXM LDOM ProcessingInstruction
The createProcessingInstruction metho d c reates an empty
IXMLDOMProcessingInstruction o bjec t with the spec ified data. No te that the
newly c reated no de must be added to ano ther no de using the appendChild
metho d. target is a String value c o ntaining the name o f the pro c essing instruc tio n. data is a String value that will be sto red in the new o bjec t’s nodeValue
pro perty.
Chapter 21 ✦ The Document Object M odel
Tip
Output version: Use this m ethod to generate the < ?xm l version= ”1.0”?> elem ent
at the start of your XML docum ent. Use xml as target, and version=”1.0” as
data.
Function createTextNode (data As String) as IXM LDOM TextNode
The createTextNode metho d c reates an empty TextNo de o bjec t with the spec ified
data. No te that the newly c reated no de must be added to ano ther no de using the
appendChild metho d. data is a String value that will be sto red in the new
o bjec t’s nodeValue pro perty.
Function getElementsByTagName (tagName As String) as
IXM LDOM NodeList
The getElementsByTagName metho d searc hes the c urrent o bjec t and its c hildren
fo r the spec ified elements and returns them as an IXMLDOMNodeList. tagName is a
String value c o ntaining the element name to be fo und. If yo u spec ify an asterisk
( * ), all elements will be returned.
Function getProperty(name As String)
The getProperty metho d returns a pro perty value set by the setProperty metho d.
name is a String value c o ntaining the name o f the pro perty. SelectionLanguage is
a String value, whic h c an be either Xpath o r XSLPattern. It determines the type o f
query that the user spec ifies in the selectNodes o r selectSingleNode metho ds.
Function load (url As String) as Boolean
The load metho d lo ads the spec ified XML do c ument into the DOMDocument, parses
it, and then c reates the appro priate c hild o bjec ts to represent the XML do c ument. If
the lo ad was suc c essful, this metho d will return True. url is a String value c o ntaining a URL that spec ifies the lo c atio n o f the XML do c ument to be lo aded.
Function loadXM L(xmlString As String) as Boolean
The loadXML metho d lo ads parses and then c reates the appro priate c hild o bjec ts
to represent the XML do c ument spec ified in xmlString. If the lo ad was suc c essful,
this metho d will return True. xmlString is a String value c o ntaining the XML
statements to be lo aded.
Function nodeFromId (idString As String) as IXM LDOM Node
The nodeFromId metho d returns the no de, whic h has an ID attribute with the supplied value. The ID attribute is suppo sed to appear o nly o nc e in an element, and the
value o f eac h ID attribute is suppo sed to be unique within an XML do c ument.
idString is a String value c o ntaining the ID value to be searc hed fo r.
467
468
Part V ✦ The Impact of XM L
Sub save (destination)
The save metho d is used to write the XML to the spec ified lo c atio n. Destination is
a Variant whic h c an be a String value c o ntaining a file name o r an ASP Respo nse
o bjec t, whic h c an be used to send the do c ument o ver the Internet in a VB IIS
Applic atio n.
Sub setProperty(name As String, value)
The setProperty metho d allo ws yo u to set the value o f the SelectionLanguage
pro perty desc ribed earlier in this c hapter under “Func tio n getPro perty(name As
String).” name is a String value c o ntaining the name o f the pro perty, who se value
is to be c hanged with the SelectionLanguage pro perty.. value is the value to be
assigned to the pro perty.
Sub validate( )
The validate metho d verifies the c urrently lo aded do c ument against the c urrently
lo aded DTD o r sc hema. Witho ut a DTD o r sc hema, the validate metho d will c ause a
run-time erro r.
DOM Document object events
The DOMDocument o bjec t is unique in this o bjec t mo del in that it is the o nly o bjec t to
have events. These events assist yo u in pro c essing XML do c uments async hro no usly.
Event ondataavailable ( )
The ondataavailable event is c alled as so o n as the first o bjec t c o ntaining
data is available during an async hro no us lo ad pro c ess. The ondataavailable
event will be c alled as additio nal c hunks o f data bec o me available. No te that the
ondataavailable pro perty must be set to True, and the DOMDocument o bjec t
must be dec lared WithEvents, in o rder fo r the event to be fired.
Event onreadystatechange ( )
The onreadystatechange event is c alled eac h time the readyState pro perty
c hanges value. No te that the onreadystatechange pro perty must be set to True,
and the DOMDocument o bjec t must be dec lared WithEvents, in o rder fo r the event
to be fired.
Event Function ontransformnode (nodeCode, nodeData) As Boolean
The ontransformnode event is c alled befo re eac h no de in the style sheet is applied to
eac h no de in the XML do c ument. If yo u return True, the transfo rmatio n pro c ess will
Chapter 21 ✦ The Document Object M odel
c o ntinue, while returning False will abo rt the transfo rmatio n pro c ess. nodeCode is
an o bjec t referenc e to the c urrent no de in the style sheet. nodeData is an o bjec t referenc e to the c urrent no de in the XML do c ument.
Note
Visual Basic, not: This event is not supported in Visual Basic due to the w ay it w as
im plem ented.
The XM LDOM Attribute object
The XMLDOMAtribute o bjec t ho lds info rmatio n abo ut a spec ific attribute in an element. Unlike the o ther no de o bjec ts, the XMLDOMAttribute no des are referenc ed
thro ugh the attributes pro perty.
XM LDOM Attribute object properties
Table 21-4 lists the unique pro perties asso c iated with the XMLDOMAttribute o bjec t.
All o f the pro perties asso c iated with the XMLDOMNode o bjec t (see Table 21-1) are
also available in this o bjec t.
Table 21-4
Unique Properties of the XM LDOM Node object
Property
Description
Name
A String value containing the nam e of the attribute.
Value
A String containing the attribute’s value.
XM LDOM Attribute object methods
The XMLDOMAttribute o bjec t has no unique metho ds. It inherits all o f the metho ds
fo und in the XMLDOMNode o bjec t.
The XM LDOM CDATASection Object
The XMLDOMComment o bjec t ho lds info rmatio n abo ut a CDATA sec tio n in yo ur XML
do c ument.
469
470
Part V ✦ The Impact of XM L
XM LDOM CDATASection object properties
Table 21-5 lists the unique pro perties asso c iated with the XMLDOMCDATASection
o bjec t. All o f the pro perties listed in the XMLDOMNode o bjec t (see Table 21-1) are
also available fo r this o bjec t.
Table 21-5
Unique Properties of the XM LDOM CDATASection Object
Property
Description
Data
A String value containing the characters from the CDATA section of the
XML docum ent.
Length
A Long value containing the num ber of characters in data.
XM LDOM CDATASection object methods
The XMLDOMCDATASection o bjec t has two unique metho ds that are used to ac c ess
the info rmatio n fro m a CDATA sec tio n in yo ur XML do c ument. All o f the metho ds
fo und in the XMLDOMNode o bjec t are available fo r this o bjec t as well.
Function splitText (offset As Long) as IXM LDOM Text
The splitText metho d splits the no de into two no des at the spec ified o ffset fro m
the beginning o f the text and auto matic ally inserts the new no de into the do c ument
hierarc hy immediately fo llo wing the c urrent no de. offset is a Long value c o ntaining the lo c atio n where the split will take plac e. Spec ifying an o ffset value o f zero will
mo ve all o f the text in the c urrent no de to the new no de.
Function substringData (offset As Long, count As Long) as String
The substringData metho d extrac ts a blo c k o f text fro m the no de. offset is a
Long value c o ntaining the lo c atio n where the extrac tio n will begin. The first c harac ter in the string has an o ffset o f zero . count is a Long c o ntaining the number o f
c harac ters to be extrac ted.
The XM LDOM Comment Object
The XMLDOMComment o b jec t ho lds info rmatio n ab o ut a c o mment in yo ur XML
do c ument.
Chapter 21 ✦ The Document Object M odel
XM LDOM Comment object properties
Table 21-6 lists the pro perties asso c iated with the XMLDOMComment o bjec t. It also
inherits the pro perties fro m the XMLDOMNode o bjec t (see Table 21-1).
Table 21-6
Unique Properties of the XM LDOM Comment Object
Property
Description
Data
A String value containing the characters in the Com m ent section of the
XML docum ent.
Length
A Long value containing the num ber of characters in data.
XM LDOM Comment object methods
The XMLDOMComment o bjec t has a metho d that yo u c an use to extrac t info rmatio n
fro m a Co mment sec tio n in yo ur XML do c ument. The metho ds available in the
XMLDOMNode o bjec t are also available in this o bjec t.
Function substringData (offset As Long, count As Long) as String
The substringData metho d extrac ts a blo c k o f text fro m the no de. offset is a
Long value c o ntaining the lo c atio n where the extrac tio n will begin. The first c harac ter in the string has an o ffset o f zero . count is a Long c o ntaining the number o f
c harac ters to be extrac ted.
The XM LDOM DocumentType Object
The XMLDOMDocumentType o b jec t ho lds info rmatio n ab o ut a do c ument type
dec laratio n.
XM LDOM DocumentType object properties
Table 21-7 lists the unique pro perties asso c iated with the XMLDOMDocumentType
o bjec t.
471
472
Part V ✦ The Impact of XM L
Table 21-7
Unique Properties of the XM LDOM Node Object
Property
Description
Entities
An object reference to an XMLDOMNameNodeMap containing the
collection of entities used in the docum ent type declaration.
Name
A String value containing the nam e of the docum ent type.
Notations
An object reference to an XMLDOMNameNodeMap containing the
collection of XMLDOMNotation objects.
XM LDOM DocumentType object methods
The XMLDOMDocumentType o bjec t has no unique metho ds. It inherits all o f the
metho ds fo und in the XMLDOMNode o bjec t.
The XM LDOM Element Object
The XMLDOMElement o b jec t ho lds info rmatio n ab o ut an entity fro m yo ur XML
do c ument.
XM LDOM Element object properties
The unique pro perty o f the XMLDOMElement o bjec t is tagName, whic h is a String
value c o ntaining the name o f the tag that is used to identify the element. The
XMLDOMElement o bjec t also inherits the pro perties fro m the XMLDOMNode o bjec t
(see Table 21-1).
XM LDOM Element object methods
The XMLDOMElement o bjec t pro vides several metho ds that make it easy to ac c ess
the info rmatio n fro m the attributes asso c iated with this o bjec t. No te that the metho ds available in the XMLDOMNode o bjec t (see Table 21-1) are also available in this
o bjec t.
Function getAttribute (name as String) as Variant
The getAttribute metho d returns a String c o ntaining the value o f the attribute.
An empty string means that the attribute do esn’t have a spec ified o r default value.
name is a String c o ntaining the name o f the attribute.
Chapter 21 ✦ The Document Object M odel
Function getAttributeNode (name as String) as IXM LDOM Attribute
The getAttributeNode metho d returns a referenc e to an XMLDOMAttribute
o bjec t c o ntaining the spec ified attribute. name is a String value c o ntaining the
name o f the attribute.
Sub normalize( )
The normalize metho d c o mbines all o f the text no des belo w this o bjec t into no rmal fo rm, where eac h text no de is separated by an element, a c o mment, a pro c essing instruc tio n, a CDATA sec tio n, o r an entity referenc e. Yo u c an do the same thing
by saving the do c ument to a disk file, deleting all o f the o bjec ts belo w the
DOMDocument o bjec t, and lo ading the do c ument bac k fro m the disk file.
Sub setAttribute (name as String, value)
The setAttribute metho d assigns a new value to an attribute. If the attribute
do esn’t exist, it will auto matic ally be c reated fo r yo u. name is a String value c o ntaining the name o f the attribute. value is a Variant value c o ntaining the value to
be assigned to the attribute.
Function setAttributeNode (DOM Attribute as IXM LDOM Attribute) as
IXM LDOM Attribute
The setAttributeNode metho d is used to c reate o r replac e an attribute no de in
the do c ument hierarc hy. It will return Null if the attribute didn’t exist, o r it will
return an o bjec t po inter to the o ld attribute’s no de. DOMAttribute is an o bjec t referenc e to an XMLDOMAttribute o bjec t that c o ntains the new attribute.
The XM LDOM Entity Object
The XMLDOMEntity o b jec t ho lds info rmatio n ab o ut an entity fro m yo ur XML
do c ument.
XM LDOM Entity object properties
Table 21-8 lists the unique pro perties o f the XMLDOMEntity o bjec t. This o bjec t also
inherits all o f the pro perties fro m the XMLDOMNode o bjec t (see Table 21-1).
473
474
Part V ✦ The Impact of XM L
Table 21-8
Unique Properties of the XM LDOM Entity Object
Property
Description
notationName
A String value containing the nam e of the notation, if the entity is
unparsed or an em pty string once the entity has been parsed.
publicId
A String containing the public identifier associated w ith the entity.
systemId
A String containing the system identifier associated w ith the entity.
If the system identifier isn’t specified, this property w ill contain the
em pty string.
XM LDOM Entity object methods
The XMLDOMEntity o bjec t has no unique metho ds. It inherits all o f the metho ds
fo und in the XMLDOMNode o bjec t.
The XM LDOM EntityReference Object
The XMLDOMEntityReference o b jec t ho lds info rmatio n ab o ut an entity fro m
yo ur XML do c ument. This o b jec t is c reated b ased o n the info rmatio n fro m the
XMLDOMEntity o b jec t. Due to the nature o f the XML parser inc luded in the o b jec t
lib rary, external entities may no t b e parsed and expanded in their o wn o b jec ts
until they are needed, whic h means that two different o b jec ts are needed to ho ld
the info rmatio n.
Note
No difference: The XMLDOMEntityReference object doesn’t have any unique
properties, m ethods, or events, w hen com pared to the XMLDOMNode object. All of
the standard properties and m ethods of the XMLDOMNode object are available in
this object.
The XM LDOM Notation Object
The XMLDOMNotation o bjec t ho lds info rmatio n abo ut a no tatio n that was dec lared
in the data type dec laratio n o r sc hema sec tio n o f yo ur XML do c ument.
Chapter 21 ✦ The Document Object M odel
XM LDOM Notation object properties
Table 21-9 lists the unique pro perties o f the XMLDOMNotation o bjec t. This o bjec t
also inherits all o f the pro perties fro m the XMLDOMNode o bjec t.
Table 21-9
Unique Properties of the XM LDOM Notation Object
Property
Description
publicId
A String value containing the public identifier associated w ith the
notation.
systemId
A String containing the system identifier associated w ith the notation.
If the system identifier isn’t specified, this property w ill contain the
em pty string.
XM LDOM Notation object methods
The XMLDOMNotation o bjec t has no unique metho ds. It inherits all o f the metho ds
fo und in the XMLDOMNode o bjec t (see Table 21-1).
The XM LDOM ProcessingInstruction Object
The XMLDOMProcessingInstruction o bjec t c o ntains pro c essing direc tives, suc h
as the .
XM LDOM ProcessingInstruction object properties
Table 21-10 lists the unique pro perties o f the XMLDOMProcessingInstruction
o bjec t. This o bjec t also inherits all o f the pro perties fro m the XMLDOMNode o bjec t
(see Table 21-1).
XM LDOM ProcessingInstruction object methods
The XMLDOMProcessingInstruction o bjec t has no unique metho ds. It inherits all
o f the metho ds fo und in the XMLDOMNode o bjec t.
475
476
Part V ✦ The Impact of XM L
Table 21-10
Unique Properties of the XM LDOM ProcessingInstruction Object
Property
Description
data
A String value containing the data associated w ith the processing
instruction. In other w ords, this w ould be the version=”1.0” part of
the processing instruction. This value is identical to that in the
nodeValue property.
target
A String containing the application that contains the processing
instruction.
For exam ple, this w ould be xml from the
processing instruction.
The XM LDOM Text Object
The XMLDOMText o bjec t ho lds info rmatio n abo ut the text value asso c iated with an
XMLDOMElement o r XMLDOMAttribute no de.
XM LDOM Text object properties
Table 21-11 lists the unique pro perties asso c iated with the XMLDOMText o bjec t. All
o f the pro perties listed in the XMLDOMNode o bjec t are also available fo r this o bjec t.
Table 21-11
Unique Properties of the XM LDOM Text Object
Property
Description
data
A String value containing the text characters that m ake up the value
of an elem ent or an attribute.
length
A Long value containing the num ber of characters in data.
XM LDOM Text object methods
The XMLDOMText o bjec t inc ludes a ric h set o f metho ds to manipulate the data
sto red in the no de. It also inc ludes all o f the metho ds fo und in the XMLDOMNode
o bjec t.
Chapter 21 ✦ The Document Object M odel
Sub appendData (data as String)
The appendData metho d adds the spec ified string value to the end o f the existing
data already in the no de. data is a String value c o ntaining the new info rmatio n to
be added to the no de’s value.
Sub deleteData (offset as Long, count as Long)
The deleteData metho d remo ves the spec ified number c harac ters fro m the no de
starting with the spec ified lo c atio n. offset is a Long value c o ntaining the lo c atio n
where the c harac ters will be deleted. The first c harac ter in the string has an o ffset
o f zero . count is a Long c o ntaining the number o f c harac ters to be deleted.
Sub insertData (offset as Long, data as String)
The insertData metho d inserts the spec ified data into the data already starting
with the spec ified lo c atio n. offset is a Long c o ntaining the lo c atio n where the
c harac ters will be inserted. The first c harac ter in the string has an o ffset o f zero .
data is a String c o ntaining the c harac ters to be added.
Sub replaceData (offset as Long, count as Long, data as String)
The replaceData metho d deletes the spec ified number o f c harac ters starting at
the spec ified lo c atio n, then inserts the spec ified data starting at the same lo c atio n.
offset is a Long c o ntaining the lo c atio n where the c harac ters will be replac ed. The
first c harac ter in the string has an o ffset o f zero . count is a Long c o ntaining the
number o f c harac ters to be deleted. data is a String c o ntaining the c harac ters to
be added.
Function splitText (offset as Long) as IXM LDOM Text
The splitText metho d splits the no de into two no des at the spec ified o ffset fro m
the beginning o f the text, and auto matic ally inserts the new no de into the do c ument hierarc hy immediately fo llo wing the c urrent no de. offset is a Long c o ntaining the lo c atio n where the split will take plac e. Spec ifying an o ffset value o f zero will
mo ve all o f the text in the c urrent no de to the new no de.
Function substringData (offset as Long, count as Long) as String
The substringData metho d extrac ts a blo c k o f text fro m the no de. offset is a
Long value c o ntaining the lo c atio n where the extrac tio n will begin. The first c harac ter in the string has an o ffset o f zero . count is a Long c o ntaining the number o f
c harac ters to be extrac ted.
477
478
Part V ✦ The Impact of XM L
The XM LDOM ParseError Object
The XMLDOMParseError o bjec t c o ntains info rmatio n abo ut the first erro r enc o untered while parsing yo ur XML do c ument.
XM LDOM ParseError object properties
Table 21-12 lists the pro perties o f the XMLDOMParseError o bjec t.
Table 21-12
Properties of the XM LDOM ParseError object
Property
Description
ErrorCode
A Long value containing the error code.
Filepos
A Long containing the absolute position in the file w here the error
occurred.
Line
A Long containing the line num ber w here the error occurred.
Linepos
A Long containing the position in the line w here the error occurred.
Reason
A String value containing a text description of the error.
SrcText
A String containing the line w ith the error.
url
A String containing the URL of the docum ent w ith the error.
XM LDOM ParseError bject methods
The XMLDOMParseError o bjec t do esn’t have any metho ds.
The XM LHttpRequest Object
The XMLHttpRequest o bjec t allo ws yo u to transfer XML do c uments using HTTP.
This is primarily a c lient-side to o l that c an be used in a JavaSc ript o r VBSc ript Web
page to transmit a request to a server and pro c ess its respo nse. The pro perties and
o bjec ts that return info rmatio n abo ut the result are o nly valid if the send metho d
has c o mpleted suc c essfully.
Chapter 21 ✦ The Document Object M odel
XM LHttpRequest object properties
Table 21-13 lists the pro perties o f the XMLHttpRequest o bjec t.
Table 21-13
Properties of the XM LHttpRequest Object
Property
Description
onreadystatechange
An object reference to an event handler in a scripting language.
readyState
A Long value describing the state of the transport, w hen
loading the docum ent asynchronously (see the async
property). A value of UNINITIALIZED (0) m eans that the
object has been created but nothing has been transferred. A
value of LOADING (1) m eans that the source docum ent is being
loaded; a value of LOADED (2) m eans that the docum ent is
loaded, but none of the objects in the docum ent hierarchy are
available for access; a value of INTERACTIVE (3) m eans that
som e objects are available for use; a value of COMPLETED (4)
m eans that the docum ent has been loaded and all objects are
available for access. Note that a value of COMPLETED doesn’t
im ply that the docum ent loaded successfully.
responseBody
A Variant value containing the response to the HTTP request.
responseStream
An object reference to a Stream object containing the raw data
from the response to the HTTP request.
responseText
A String value containing the response to the HTTP request.
responseXML
An object reference to a DOMDocument object containing the
parsed XML docum ent that w as received in response to the
HTTP request.
status
A Long containing the HTTP status code returned by the HTTP
server.
statusText
A String containing the HTTP line status.
XM LHttpRequest object methods
The XMLHttpRequest o bjec t inc ludes metho ds fo r c reating and sending an HTTP
request to a Web server.
479
480
Part V ✦ The Impact of XM L
Sub abort( )
The abort metho d terminates an ac tive HTTP request.
Function getAllResponseHeaders ( ) as String
The getAllResponseHeaders metho d returns the header info rmatio n fro m the
HTTP result as a single string. Eac h header is separated by a c arriage return/ line
feed pair ( vbCrLf).
Function getResponseHeader (bstrHeader as String) as String
The getResponseHeader metho d returns the spec ified header fro m the HTTP
respo nse where bstrHeader is a String value c o ntaining the partic ular header
yo u wish to retrieve.
Sub open(bstrM ethod as String, bstrUrl As String, [varAsync],
[bstrUser], [bstrPassword])
The open metho d initializes an HTTP request. After the request is initialized, the
send metho d must be used to transfer the do c ument and wait fo r the respo nse.
bstrMethod is a String value that identifies the HTTP transfer metho d. This is
usually o ne o f the fo llo wing: GET, POST, PUT, o r PROPFIND. bstrUrl is a String
c o ntaining the URL that will be used to pro c ess the request. varAsync is a
Boolean value when True means that the c all is async hro no us. If this value isn’t
spec ified, it will default to True. bstrUser is a String c o ntaining the userid to lo g
o nto the Web server. If this parameter is missing and the Web server requires a
userId and passwo rd to lo g o n, the user will be pro mpted fo r this info rmatio n.
bstrPassword is a String c o ntaining the passwo rd asso c iated with bstrUserid.
Sub send ([varBody])
The send metho d transmits the request to the remo te ho st and o ptio nally waits fo r
the ho st’s respo nse if the user spec ified False fo r varAsync o n the open metho d.
varBody is a Variant value c o ntaining the do c ument to be sent. If this parameter
isn’t spec ified, then the c urrent do c ument is transmitted.
Sub setRequestHeader(bstrHeader as String, bstrValue as String)
The setRequestHeader metho d sets the value o f the vario us header fields befo re
the do c ument request is sent. bstrHeader is a String value c o ntaining the header
to be set. No te that the trailing c o lo n (:) o n the header sho uld no t be spec ified.
bstrValue is a String c o ntaining the value to be assigned to the header.
Chapter 21 ✦ The Document Object M odel
Thoughts on the XM L Object M odel
As I said in the previous chapter, XML is far m ore com plex than I have room to cover. This is
really obvious w hen you look at the object m odel. How ever, m uch of the com plexity isn’t
necessary for m ost program m ers. As w ith m ost things in life, the eighty-tw enty rule applies:
eighty percent of the tim e, only tw enty percent of the capabilities are needed or used.
In this case, the object m odel is designed to cover all sorts of situations that m ight not norm ally be encountered in m ost applications. In the next chapter, I’m going to use this object
m odel in a sim ple exam ple that show s you how you can generate an XML request and satisfy it w ith a Web server.
Summary
In this c hapter yo u learned:
✦ abo ut the XML Do c ument Objec t Mo del
✦ ho w an XML do c ument is mapped into the Do c ument Objec t Mo del.
✦
✦
✦
481
C H A P T E R
The Document
Object M odel
✦
✦
✦
✦
In This Cha pter
M
ic ro so ft has develo ped a to o l fo r c reating and parsing
XML do c uments c alled MSXML. MSXML implements
the XML Do c ument Objec t Mo del (DOM) as defined by the
Wo rldwide Web Co nso rtium (usually c alled W3C). W3C is an
internatio nal standards bo dy that is respo nsible fo r the standards (suc h as HTML, XML, XSP, and so o n) that are used to
ac c ess the Web.
The DOM sto res an XML do c ument as a series o f o b jec ts that
c an b e easily ac c essed b y an applic atio n pro gram. MSXML
implements DOM as a series o f COM o b jec ts fo r use o n
Windo ws-b ased c o mputers. This means that these o b jec ts
are independent o f any pro gramming language and datab ase
server and c an b e used with Visual Basic , Visual C++, ASP
sc ript files, SQL Server, and Orac le 8i witho ut pro b lems.
In this c hapter, I’ll disc uss ho w to use the Do c ument Objec t
Mo del to c reate and parse XML do c uments.
Note
Basically beta: The version of the Docum ent Object Model
discussed in this book is based on the March 2000 beta
release of MSXML. At the tim e I w rote this chapter, the
W3C hadn’t finalized the specifications for DOM, and as a
consequence, Microsoft’s im plem entation of it in MSXML is
still subject to change.
The Document Object M odel
Mic ro so ft’s implementatio n o f the Do c ument Objec t Mo del
c o nfo rms fairly c lo sely to the W3C’s rec o mmendatio n, but rec o mmendatio ns c an be fairly c o mplex to understand. The DOM
is based o n a hierarc hic al o rganizatio n o f o bjec t no des who se
types vary, as different types o f info rmatio n are sto red in the
Intro ducing the
Do cument O bject
Mo del
Understanding the
do cument hierarchy
Using the DO M
O bjects
✦
✦
✦
✦
456
Part V ✦ The Impact of XM L
do c ument hierarc hy. In additio n, a number o f o ther o bjec ts are sto red there that
c o ntain spec ific piec es o f info rmatio n o r utility func tio ns.
Document hierarchy
The basic DOM hierarc hy is sho wn in Figure 21-1. The ro o t no de o f the hierarc hy
is the DOMDocument o bjec t, whic h enc o mpasses the entire XML do c ument. As yo u
desc end thro ugh the tree struc ture, o ther no des represent a partic ular piec e o f
info rmatio n o r gro up o f info rmatio n in the XML do c ument.
DOM Document
XM LDOM PrecessingInstruction
XM LDOM Text
XM LDOM Element
XM LDOM CDATASection
XM LDOM Element
XM LDOM Text
XM LDOM Comment
XM LDOM DocumentType
XM LDOM Notation
XM LDOM Entity
XM LDOM Comment
XM LDOM Attribute
XM LDOM PrecessingInstruction
XM LDOM EntityReference
XM LDOM EntityReference
Figure 21-1: View ing the Docum ent Object Model object hierarchy
The basic o bjec t is the XMLDOMNode o bjec t, fro m whic h all o f the o ther no des
are derived. In to tal, there are a do zen different types o f no des. Aside fro m the
DOMDocument o bjec t, all o f the o ther o bjec ts begin with XMLDOM.
Chapter 21 ✦ The Document Object M odel
✦ DOMDocument – This is the highest-level o bjec t in the hierarc hy. It enc o mpasses the entire XML do c ument. It also inc ludes additio nal metho ds and
pro perties that c an be used to o btain an XML do c ument o r to c reate o ther
no des.
✦ XMLDOMAttribute – This o bjec t is used to ho ld info rmatio n abo ut a single
attribute in an element. It is no t c o nsidered a true no de value sinc e it is referenc ed thro ugh the attributes pro perty, rather than the childNodes pro perty.
✦ XMLDOMCDATASection – This o bjec t is similar to the IXMLDOMText o bjec t,
exc ept it c o ntains data that was sto red in a CDATA sec tio n in the XML do c ument. The CDATA sec tio n begins with the
string. Any c harac ters in between the two CDATA delimiters are treated as
no rmal text. This lets yo u inc lude any text into a text field, inc luding elements
that wo uld no rmally be pro c essed by the XML parser.
✦ XMLDOMComment – This o bjec t ho lds an XML c o mment element, whic h is the
string o f c harac ters between the .
✦ XMLDOMDocumentType – This o bjec t c o ntains info rmatio n abo ut the Do c ument
Type Dec laratio ns inc luded in an XML do c ument.
✦ XMLDOMElement – This o bjec t c o ntains info rmatio n abo ut a single element in
an XML do c ument. If the element in the do c ument c o ntains o ther, nested elements, then the childNodes pro perty will c o ntain referenc es to these o bjec ts.
The attributes pro perty c an be used to find the IXMLDOMAttribute o bjec ts,
whic h c o ntain info rmatio n abo ut the attributes fo und in this element.
✦ XMLDOMEntity – This o bjec t c o ntains info rmatio n abo ut a parsed o r unparsed
entity in the XML do c ument.
✦ XMLDOMEntityReference – This o bjec t c o ntains info rmatio n abo ut an entity
referenc e in the XML do c ument.
✦ XMLDOMNode – This o bjec t is the fundamental o bjec t o f the Do c ument Objec t
Mo del. All o f the o ther o bjec ts that c an ac t as a no de in the hierarc hy are
derived fro m this o bjec t.
✦ XMLDOMNotation – This o bjec t c o ntains no tatio n info rmatio n fro m a
Do c ument Type Dec laratio n o r a sc hema.
✦ XMLDOMProcessingInstruction – This o bjec t c o ntains pro c essing info rmatio n fo r the XML do c ument. Fo r example, this o bjec t will sto re the info rmatio n
fo und in the tag that is fo und at the start o f mo st
XML do c uments.
✦ XMLDOMText – This o bjec t c o ntains the text value fo und in between the and tags in a do c ument.
457
458
Part V ✦ The Impact of XM L
Note
To IXM LDOM or not to IXM LDOM : Microsoft frequently prefixes the node nam es
w ith an I in their im plem entation of the object m odel. The I prefix is a C+ + convention that indicates that the object is a COM Interface, w hich just another object
to a Visual Basic program m er.
Other objects
Here are a few o ther o bjec ts that yo u may find interesting. These o bjec ts c anno t be
used in plac e o f a no de o bjec t, but o ffer spec ialized suppo rt servic es.
✦ XMLDOMDocumentFragment – This o b jec t is used to sto re part o f an XML
do c ument. Yo u might find it useful if yo u want to restruc ture an XML o b jec t
hierarc hy.
✦ XMLDOMImplementation – This o bjec t allo ws yo u to detec t vario us features
inc luded in a partic ular implementatio n o f the Do c ument Objec t Mo del.
✦ XMLDOMNodeList – This o bjec t is a c o ntainer fo r a c o llec tio n o f no des. This
o bjec t is typic ally returned by several metho ds that yo u c an use to searc h fo r
spec ific elements in the do c ument hierarc hy.
✦ XMLDOMParseError – This o bjec t c o ntains info rmatio n abo ut any erro rs that
o c c urred while parsing yo ur XML do c ument.
✦ XMLHttpRequest – This o bjec t allo ws yo u to send and rec eive info rmatio n
using an HTTP c o nnec tio n.
The XM LDOM Node Object
The XMLDOMNode o bjec t is the fundamental o bjec t in the Do c ument Objec t Mo del. It
fo rms the basis o f all the o ther no de o bjec ts that ho ld yo ur XML do c ument. Eac h o f
tho se o bjec ts will inherit the XMLDOMNode’s pro perties and metho ds, to whic h it
may add unique pro perties, metho ds, and events.
XM LDOM Node object properties
Table 21-1 lists the pro perties asso c iated with the XMLDOMNode o bjec t.
Chapter 21 ✦ The Document Object M odel
Table 21-1
Properties of the XM LDOM Node object
Property
Description
attributes
An object reference to a node containing the attributes.
Returns NULL if this node doesn’t have any attributes.
baseName
A String value containing right side of a fully qualified
nam e of the docum ent.
childNodes
An object reference to one of several different
collections depending on the value of nodeType (see
Table 21-2).
dataType
A Variant value that is either a String containing the
nam e of the data type associated w ith the node or
VT_NULL if no data type is defined.
definition
An object reference to a node in the docum ent type
definition or schem a, if included.
firstChild
An object reference to the first child node of this node.
Returns NULL if this node doesn’t have any children.
lastChild
An object reference to the last child node of this node.
Returns NULL if this node doesn’t have any children.
namespaceURI
A String containing the Universal Resource Identifier
(URI) of the nam espace.
nextSibling
An object reference to the next sibling of this node. If
there are no m ore siblings, then this value is NULL.
nodeName
A String value containing the nam e of the node.
nodeType
An enum erated data type containing the type of the
node (see Table 21-2).
nodeTypedValue
A String value containing the node’s value in its
defined data type.
nodeTypeString
A String value containing a value corresponding to
the value of nodeType. See Table 21-2 for the string
values that correspond to the nodeType value.
nodeValue
A String value containing the text associated w ith
the node.
ownerDocument
An object reference to the root DOMDocument object or
the DOMDocument, w hich created this object.
Continued
459
460
Part V ✦ The Impact of XM L
Table 21-1 (continued)
Property
Description
parentNode
An object reference to the parent object of this node.
parsed
A Boolean w hen True m eans that this node and all of
its descendents have been parsed.
prefix
A String containing the nam espace prefix.
previousSibling
An object reference to the previous sibling of this node.
If this is the first node, then this value w ill be NULL.
specified
A Boolean value w hen True m eans that the value w as
specified, rather than being derived from a default value
in the DTD or schem a.
text
A String containing the text value of the current node
and all of its subtrees.
xml
A String containing the XML statem ents that m ake up
the current docum ent.
XM LDOM Node object methods
The XMLDOMNode o bjec t has a number o f metho ds that are used to manage the c hild
no des asso c iated with it.
Function appendChild (newChild As IXM LDOM Node) as IXM LDOM Node
The appendChild metho d is used to add a no de o bjec t as a c hild o f the c urrent
no de. It returns an o bjec t to the newly added c hild no de. This metho d is the equivalent o f c alling insertBefore ( newChild, NULL). newChild is an o bjec t referenc e to
a no de, whic h will be added as a c hild to the c urrent no de.
Function cloneNode (deep As Boolean) as IXM LDOM Node
The cloneNode metho d is used to c reate a c o py o f the c urrent no de. deep is a
Boolean, when True means that all o f the c hild no des o f the c urrent no de are to be
c lo ned also .
Table 21-2
Values for nodeType
Integer
String
Description
NODE_ELEMENT
1
element
Represents an elem ent. Can be a child of the
Document, DocumentFragment, EntityReference
and Element nodes. Can have one or m ore Element,
Text, Comment, ProcessingInstruction,
CDATASection, and EntityReference nodes as
children.
NODE_ATTRIBUTE
2
attribute
Represents an attribute. Referenced though an Entity
node. Can have the Text and the EntityReference
nodes as children. Technically, an Attribute is not
considered a child of the Element node, since it is
referenced through the attributes property.
NODE_TEXT
3
Text
Represents the text content of a tag. Can be a child of the
Attribute, DocumentFragment, Element, and
EntityReference nodes. Cannot have any child nodes.
NODE_CDATA_SECTION
4
cdatasection
Represents a CDATA section, w hich is used to escape blocks
of text that m ight be recognized as m arkup. Can be a child
of the DocumentFragment, EntityReference, and
Element nodes. Cannot have any child nodes.
NODE_ENTITY_REFERENCE
5
Entityreference
Represents an entity. Can be a child of the Attribute,
DocumentFragment, Element, and EntityReference
nodes. Can have the Element,
ProcessingInstruction, Comment, Text,
CDATASection, and EntityReference nodes
as children.
NODE_ENTITY
6
Entity
Represents an expanded entity. Can be a child of the
DocumentType node. Can have other nodes as child
nodes.
Continued
Chapter 21 ✦ The Document Object M odel
Constant
461
462
Table 21-2 (continued)
Integer
String
Description
NODE_PROCESSING_INSTRUCTION
7
processinginstruction
Can be a child of the Document, Document
Fragment, Element, and EntityReference
nodes. Cannot have any child nodes.
NODE_COMMENT
8
comment
Represents a com m ent. Can be a child of the
Document, DocumentFragment, Element, and
EntityReference nodes. Cannot have any child
nodes.
NODE_DOCUMENT
9
document
Represents an XML docum ent. Cannot be a child
of any other nodes. Can have exactly one child
node, w hich can be an Element, a
ProcessingInstruction, a Comment, or a
DocumentType node.
NODE_DOCUMENT_TYPE
10
Documenttype
Represents a docum ent type declaration. Can be a
child of the Document node. Can have Notation
and Entity nodes as child nodes.
NODE_DOCUMENT_FRAGMENT
11
documentfragment
Represents a node or subtree w ith a docum ent
w ithout being contained w ithin the docum ent.
Cannot be a child of any other nodes. Can have
Element, ProcessingInstruction, Comment,
Text, CDATASection, and EntityReference
nodes as child nodes.
NODE_NOTATION
12
notation
Represents a notation in the docum ent. Can be a
child of the DocumentType node. Cannot have
any child nodes.
Part V ✦ The Impact of XM L
Constant
Chapter 21 ✦ The Document Object M odel
Function hasChildNodes ( ) as Boolean
The hasChildNodes metho d returns True if the c urrent no de has c hildren.
Function insertBefore (newChild As ICM LDOM Node, refChild) as
IXM LDOM Node
The insertBefore metho d is used to add a c hild no de to the c urrent no de. The
no de will be inserted befo re the no de spec ified in refChild. An o bjec t referenc e to
newChild will be returned as the value o f the metho d.
newChild is an o bjec t referenc e to the no de to be added. refChild is an o bjec t referenc e to a no de that is a c hild o f the c urrent no de. If this parameter is NULL, then
the no de will be added to the end o f the c o llec tio n.
Function removeChild (childNode as ICM LDOM Node) as
IXM LDOM Node
The removeChild metho d is used to remo ve the spec ified no de fro m the c urrent
no de’s c hild no des. The no de is no t destro yed, so yo u sho uld set the no de to
Nothing to free the no de’s reso urc es if yo u really want to delete it. An o bjec t referenc e to the remo ved no de will be returned by the metho d. childNode is an o bjec t
referenc e to the no de to be remo ved.
Function replaceChild (newChild As ICM LDOM Node, oldChild As
ICM LDOM Node) as IXM LDOM Node
The removeChild metho d is used to replac e an existing no de with a new no de. The
metho d will return an o bjec t referenc e to the o ld no de.
newChild is an o bjec t referenc e to a new no de. oldChild is an o bjec t referenc e to
o ne o f the c urrent no de’s c hild no des that will be replac ed with newChild.
Function selectNodes (queryString As String) as IXM LDOM NodeList
The selectNodes metho d searc hes the c urrent o b jec t and its c hildren fo r elements that matc h the spec ified XSL pattern string, and returns them as an
IXMLDOMNodeList. queryString is a String value c o ntaining an XSL Pattern
q uery.
Function selectSingleNode (queryString As String) as IXM LDOM Node
The selectSingleNode metho d searc hes the c urrent o bjec t and its c hildren fo r
the first element that matc hes the spec ified XSL pattern string, and returns it as an
IXMLDOMNode. queryString is a String value c o ntaining an XSL Pattern query.
463
464
Part V ✦ The Impact of XM L
Function transformNode (stylesheet As IXM LDOM Node) as String
The transformNode metho d returns a String value c o ntaining a fo rmatted XML
do c ument using the spec ified XSL style sheet. stylesheet is an o bjec t referenc e to
an IXMLDOMNode o bjec t c o ntaining the ro o t o f the XSL style sheet.
Sub transformNodeToObject (stylesheet As IXM LDOM Node,
outputObject)
The transformNodeToObject metho d c reates a DOMDocument struc ture c o ntaining
the fo rmatted XML do c ument using the spec ified XSL style sheet. stylesheet is
an o bjec t referenc e to an IXMLDOMNode o bjec t c o ntaining the ro o t o f the XSL style
sheet. outputObject is an o bjec t referenc e to a DOMDocument o bjec t whic h will
c o ntain the ro o t o bjec t o f the fo rmatted do c ument.
The DOM Document Object
The DOMDocument o bjec t is the fundamental o bjec t in the Do c ument Objec t Mo del.
It represents a single XML do c ument.
DOM Document object properties
The DOMDocument o bjec t has all o f the pro perties o f the XMLDOMNode o bjec t (see
Table 21-1), plus the additio nal o nes listed in Table 21-3.
Table 21-3
Unique Properties of the DOMDocument Object
Property
Description
async
A Boolean value w hen True m eans that the Load m ethod
w ill return control to the caller before the load is com plete.
You m ust use the readyState property or the
onReadyStateChange event to determ ine w hen the load
process is finished.
doctype
An object reference to an XMLDOMDocumentType object
(specified w ith the < !DOCTYPE> tag) containing the
docum ent type definition.
documentElement
An object reference to the root elem ent of the docum ent.
implementation
An object reference to the XMLDOMImplementation object,
w hich contains inform ation about the features that are
supported in this im plem entation of DOM.
Chapter 21 ✦ The Document Object M odel
Note
Property
Description
namespaces
An object reference to an XMLDOMSchemaCache object that
contains the collection of nam espaces used in this XML
docum ent.
ondataavailable
A Boolean value, w hen True m eans that the
ondataavailable event is enabled.
onreadystatechange
A Boolean value, w hen True m eans that the
onreadystatechange event is enabled.
ontransformnode
A Boolean value, w hen True m eans that the
ontransformnode event is enabled.
parseError
An object reference to the XMLDOMParseError object, w hich
contains inform ation about the last parsing error.
preserveWhiteSpace
A Boolean, w hen True m eans that the parsing process w ill
retain the blanks that are included in the XML source
docum ent.
readyState
A Long value describing the state of the docum ent, w hen
loading the docum ent asynchronously (see the async
property). A value of LOADING (1) m eans that the XML source
docum ent is being loaded; a value of LOADED (2) m eans that
the docum ent is loaded, but none of the objects are available
for access; a value of INTERACTIVE (3) m eans that som e
objects are available for use; a value of COMPLETED (4) m eans
that the docum ent has been loaded and all objects are
available for access. Note that a value of COMPLETED doesn’t
im ply that the docum ent loaded successfully.
resolveExternals
A Boolean value, w hen True m eans that external definitions
such as nam espaces, DTD external subsets, and external entity
references should be resolved at parse tim e.
schemas
An object reference to an XMLSchemaCache object containing
a list of schem as that should be used w hen loading an XML
docum ent.
url
A String value containing the URL that w as used to load the
XML docum ent.
validateOnParse
A Boolean, w hen True m eans that the docum ent’s structure
should be validated during parsing.
Enabled, but impossible: Sim ply setting the ondataavailable, onreadystatechange, and ontransformnode properties to True is not sufficient to
enable the corresponding events. You m ust declare the Document object using
the WithEvents keyw ord at the m odule level in your program in order to include
code for the events.
465
466
Part V ✦ The Impact of XM L
DOM Document object methods
The DOMDocument o bjec t has a number o f unique metho ds that are used to c reate
and ac c ess the info rmatio n in an XML do c ument.
Sub Abort ( )
The Abort metho d will c anc el an async hro no us do wnlo ad. This will return an erro r
in the XMLDOMParseError o bjec t indic ating that the do wnlo ad was abo rted.
Function createAttribute (name As String) as IXM LDOM Attribute
The createAttribute metho d c reates an empty attribute o bjec t with the spec ified
name. No te that the newly c reated no de must be added to ano ther no de using the
appendChild metho d. name is a String value c o ntaining the name o f the attribute.
Function createCDATASection (data As String) as
IXM LDOM CDATASection
The createCDATASection metho d c reates an empty IXMLDOMCDATASection
o bjec t with the spec ified data. No te that the newly c reated no de must be added to
ano ther no de using the appendChild metho d. data is a String value that will be
sto red in the new o bjec t’s nodeValue pro perty.
Function createNode (type, name As String, namespaceURI As String)
as IXM LDOM Node
The createNode metho d c reates an empty no de in the do c ument. No te that the
newly c reated no de must be added to ano ther no de using the appendChild
metho d. type is either a String value c o ntaining the type o f the no de o r an
Integer c o ntaining the numeric value c o rrespo nding to the type o f the no de (see
Table 21-2) name is a String value c o ntaining the name o f the no de that will be
sto red in the nodeName pro perty. namespaceURI is a String c o ntaining the URI o f
the namespac e.
Function createProcessingInstruction (target As String, data As String)
as IXM LDOM ProcessingInstruction
The createProcessingInstruction metho d c reates an empty
IXMLDOMProcessingInstruction o bjec t with the spec ified data. No te that the
newly c reated no de must be added to ano ther no de using the appendChild
metho d. target is a String value c o ntaining the name o f the pro c essing instruc tio n. data is a String value that will be sto red in the new o bjec t’s nodeValue
pro perty.
Chapter 21 ✦ The Document Object M odel
Tip
Output version: Use this m ethod to generate the < ?xm l version= ”1.0”?> elem ent
at the start of your XML docum ent. Use xml as target, and version=”1.0” as
data.
Function createTextNode (data As String) as IXM LDOM TextNode
The createTextNode metho d c reates an empty TextNo de o bjec t with the spec ified
data. No te that the newly c reated no de must be added to ano ther no de using the
appendChild metho d. data is a String value that will be sto red in the new
o bjec t’s nodeValue pro perty.
Function getElementsByTagName (tagName As String) as
IXM LDOM NodeList
The getElementsByTagName metho d searc hes the c urrent o bjec t and its c hildren
fo r the spec ified elements and returns them as an IXMLDOMNodeList. tagName is a
String value c o ntaining the element name to be fo und. If yo u spec ify an asterisk
( * ), all elements will be returned.
Function getProperty(name As String)
The getProperty metho d returns a pro perty value set by the setProperty metho d.
name is a String value c o ntaining the name o f the pro perty. SelectionLanguage is
a String value, whic h c an be either Xpath o r XSLPattern. It determines the type o f
query that the user spec ifies in the selectNodes o r selectSingleNode metho ds.
Function load (url As String) as Boolean
The load metho d lo ads the spec ified XML do c ument into the DOMDocument, parses
it, and then c reates the appro priate c hild o bjec ts to represent the XML do c ument. If
the lo ad was suc c essful, this metho d will return True. url is a String value c o ntaining a URL that spec ifies the lo c atio n o f the XML do c ument to be lo aded.
Function loadXM L(xmlString As String) as Boolean
The loadXML metho d lo ads parses and then c reates the appro priate c hild o bjec ts
to represent the XML do c ument spec ified in xmlString. If the lo ad was suc c essful,
this metho d will return True. xmlString is a String value c o ntaining the XML
statements to be lo aded.
Function nodeFromId (idString As String) as IXM LDOM Node
The nodeFromId metho d returns the no de, whic h has an ID attribute with the supplied value. The ID attribute is suppo sed to appear o nly o nc e in an element, and the
value o f eac h ID attribute is suppo sed to be unique within an XML do c ument.
idString is a String value c o ntaining the ID value to be searc hed fo r.
467
468
Part V ✦ The Impact of XM L
Sub save (destination)
The save metho d is used to write the XML to the spec ified lo c atio n. Destination is
a Variant whic h c an be a String value c o ntaining a file name o r an ASP Respo nse
o bjec t, whic h c an be used to send the do c ument o ver the Internet in a VB IIS
Applic atio n.
Sub setProperty(name As String, value)
The setProperty metho d allo ws yo u to set the value o f the SelectionLanguage
pro perty desc ribed earlier in this c hapter under “Func tio n getPro perty(name As
String).” name is a String value c o ntaining the name o f the pro perty, who se value
is to be c hanged with the SelectionLanguage pro perty.. value is the value to be
assigned to the pro perty.
Sub validate( )
The validate metho d verifies the c urrently lo aded do c ument against the c urrently
lo aded DTD o r sc hema. Witho ut a DTD o r sc hema, the validate metho d will c ause a
run-time erro r.
DOM Document object events
The DOMDocument o bjec t is unique in this o bjec t mo del in that it is the o nly o bjec t to
have events. These events assist yo u in pro c essing XML do c uments async hro no usly.
Event ondataavailable ( )
The ondataavailable event is c alled as so o n as the first o bjec t c o ntaining
data is available during an async hro no us lo ad pro c ess. The ondataavailable
event will be c alled as additio nal c hunks o f data bec o me available. No te that the
ondataavailable pro perty must be set to True, and the DOMDocument o bjec t
must be dec lared WithEvents, in o rder fo r the event to be fired.
Event onreadystatechange ( )
The onreadystatechange event is c alled eac h time the readyState pro perty
c hanges value. No te that the onreadystatechange pro perty must be set to True,
and the DOMDocument o bjec t must be dec lared WithEvents, in o rder fo r the event
to be fired.
Event Function ontransformnode (nodeCode, nodeData) As Boolean
The ontransformnode event is c alled befo re eac h no de in the style sheet is applied to
eac h no de in the XML do c ument. If yo u return True, the transfo rmatio n pro c ess will
Chapter 21 ✦ The Document Object M odel
c o ntinue, while returning False will abo rt the transfo rmatio n pro c ess. nodeCode is
an o bjec t referenc e to the c urrent no de in the style sheet. nodeData is an o bjec t referenc e to the c urrent no de in the XML do c ument.
Note
Visual Basic, not: This event is not supported in Visual Basic due to the w ay it w as
im plem ented.
The XM LDOM Attribute object
The XMLDOMAtribute o bjec t ho lds info rmatio n abo ut a spec ific attribute in an element. Unlike the o ther no de o bjec ts, the XMLDOMAttribute no des are referenc ed
thro ugh the attributes pro perty.
XM LDOM Attribute object properties
Table 21-4 lists the unique pro perties asso c iated with the XMLDOMAttribute o bjec t.
All o f the pro perties asso c iated with the XMLDOMNode o bjec t (see Table 21-1) are
also available in this o bjec t.
Table 21-4
Unique Properties of the XM LDOM Node object
Property
Description
Name
A String value containing the nam e of the attribute.
Value
A String containing the attribute’s value.
XM LDOM Attribute object methods
The XMLDOMAttribute o bjec t has no unique metho ds. It inherits all o f the metho ds
fo und in the XMLDOMNode o bjec t.
The XM LDOM CDATASection Object
The XMLDOMComment o bjec t ho lds info rmatio n abo ut a CDATA sec tio n in yo ur XML
do c ument.
469
470
Part V ✦ The Impact of XM L
XM LDOM CDATASection object properties
Table 21-5 lists the unique pro perties asso c iated with the XMLDOMCDATASection
o bjec t. All o f the pro perties listed in the XMLDOMNode o bjec t (see Table 21-1) are
also available fo r this o bjec t.
Table 21-5
Unique Properties of the XM LDOM CDATASection Object
Property
Description
Data
A String value containing the characters from the CDATA section of the
XML docum ent.
Length
A Long value containing the num ber of characters in data.
XM LDOM CDATASection object methods
The XMLDOMCDATASection o bjec t has two unique metho ds that are used to ac c ess
the info rmatio n fro m a CDATA sec tio n in yo ur XML do c ument. All o f the metho ds
fo und in the XMLDOMNode o bjec t are available fo r this o bjec t as well.
Function splitText (offset As Long) as IXM LDOM Text
The splitText metho d splits the no de into two no des at the spec ified o ffset fro m
the beginning o f the text and auto matic ally inserts the new no de into the do c ument
hierarc hy immediately fo llo wing the c urrent no de. offset is a Long value c o ntaining the lo c atio n where the split will take plac e. Spec ifying an o ffset value o f zero will
mo ve all o f the text in the c urrent no de to the new no de.
Function substringData (offset As Long, count As Long) as String
The substringData metho d extrac ts a blo c k o f text fro m the no de. offset is a
Long value c o ntaining the lo c atio n where the extrac tio n will begin. The first c harac ter in the string has an o ffset o f zero . count is a Long c o ntaining the number o f
c harac ters to be extrac ted.
The XM LDOM Comment Object
The XMLDOMComment o b jec t ho lds info rmatio n ab o ut a c o mment in yo ur XML
do c ument.
Chapter 21 ✦ The Document Object M odel
XM LDOM Comment object properties
Table 21-6 lists the pro perties asso c iated with the XMLDOMComment o bjec t. It also
inherits the pro perties fro m the XMLDOMNode o bjec t (see Table 21-1).
Table 21-6
Unique Properties of the XM LDOM Comment Object
Property
Description
Data
A String value containing the characters in the Com m ent section of the
XML docum ent.
Length
A Long value containing the num ber of characters in data.
XM LDOM Comment object methods
The XMLDOMComment o bjec t has a metho d that yo u c an use to extrac t info rmatio n
fro m a Co mment sec tio n in yo ur XML do c ument. The metho ds available in the
XMLDOMNode o bjec t are also available in this o bjec t.
Function substringData (offset As Long, count As Long) as String
The substringData metho d extrac ts a blo c k o f text fro m the no de. offset is a
Long value c o ntaining the lo c atio n where the extrac tio n will begin. The first c harac ter in the string has an o ffset o f zero . count is a Long c o ntaining the number o f
c harac ters to be extrac ted.
The XM LDOM DocumentType Object
The XMLDOMDocumentType o b jec t ho lds info rmatio n ab o ut a do c ument type
dec laratio n.
XM LDOM DocumentType object properties
Table 21-7 lists the unique pro perties asso c iated with the XMLDOMDocumentType
o bjec t.
471
472
Part V ✦ The Impact of XM L
Table 21-7
Unique Properties of the XM LDOM Node Object
Property
Description
Entities
An object reference to an XMLDOMNameNodeMap containing the
collection of entities used in the docum ent type declaration.
Name
A String value containing the nam e of the docum ent type.
Notations
An object reference to an XMLDOMNameNodeMap containing the
collection of XMLDOMNotation objects.
XM LDOM DocumentType object methods
The XMLDOMDocumentType o bjec t has no unique metho ds. It inherits all o f the
metho ds fo und in the XMLDOMNode o bjec t.
The XM LDOM Element Object
The XMLDOMElement o b jec t ho lds info rmatio n ab o ut an entity fro m yo ur XML
do c ument.
XM LDOM Element object properties
The unique pro perty o f the XMLDOMElement o bjec t is tagName, whic h is a String
value c o ntaining the name o f the tag that is used to identify the element. The
XMLDOMElement o bjec t also inherits the pro perties fro m the XMLDOMNode o bjec t
(see Table 21-1).
XM LDOM Element object methods
The XMLDOMElement o bjec t pro vides several metho ds that make it easy to ac c ess
the info rmatio n fro m the attributes asso c iated with this o bjec t. No te that the metho ds available in the XMLDOMNode o bjec t (see Table 21-1) are also available in this
o bjec t.
Function getAttribute (name as String) as Variant
The getAttribute metho d returns a String c o ntaining the value o f the attribute.
An empty string means that the attribute do esn’t have a spec ified o r default value.
name is a String c o ntaining the name o f the attribute.
Chapter 21 ✦ The Document Object M odel
Function getAttributeNode (name as String) as IXM LDOM Attribute
The getAttributeNode metho d returns a referenc e to an XMLDOMAttribute
o bjec t c o ntaining the spec ified attribute. name is a String value c o ntaining the
name o f the attribute.
Sub normalize( )
The normalize metho d c o mbines all o f the text no des belo w this o bjec t into no rmal fo rm, where eac h text no de is separated by an element, a c o mment, a pro c essing instruc tio n, a CDATA sec tio n, o r an entity referenc e. Yo u c an do the same thing
by saving the do c ument to a disk file, deleting all o f the o bjec ts belo w the
DOMDocument o bjec t, and lo ading the do c ument bac k fro m the disk file.
Sub setAttribute (name as String, value)
The setAttribute metho d assigns a new value to an attribute. If the attribute
do esn’t exist, it will auto matic ally be c reated fo r yo u. name is a String value c o ntaining the name o f the attribute. value is a Variant value c o ntaining the value to
be assigned to the attribute.
Function setAttributeNode (DOM Attribute as IXM LDOM Attribute) as
IXM LDOM Attribute
The setAttributeNode metho d is used to c reate o r replac e an attribute no de in
the do c ument hierarc hy. It will return Null if the attribute didn’t exist, o r it will
return an o bjec t po inter to the o ld attribute’s no de. DOMAttribute is an o bjec t referenc e to an XMLDOMAttribute o bjec t that c o ntains the new attribute.
The XM LDOM Entity Object
The XMLDOMEntity o b jec t ho lds info rmatio n ab o ut an entity fro m yo ur XML
do c ument.
XM LDOM Entity object properties
Table 21-8 lists the unique pro perties o f the XMLDOMEntity o bjec t. This o bjec t also
inherits all o f the pro perties fro m the XMLDOMNode o bjec t (see Table 21-1).
473
474
Part V ✦ The Impact of XM L
Table 21-8
Unique Properties of the XM LDOM Entity Object
Property
Description
notationName
A String value containing the nam e of the notation, if the entity is
unparsed or an em pty string once the entity has been parsed.
publicId
A String containing the public identifier associated w ith the entity.
systemId
A String containing the system identifier associated w ith the entity.
If the system identifier isn’t specified, this property w ill contain the
em pty string.
XM LDOM Entity object methods
The XMLDOMEntity o bjec t has no unique metho ds. It inherits all o f the metho ds
fo und in the XMLDOMNode o bjec t.
The XM LDOM EntityReference Object
The XMLDOMEntityReference o b jec t ho lds info rmatio n ab o ut an entity fro m
yo ur XML do c ument. This o b jec t is c reated b ased o n the info rmatio n fro m the
XMLDOMEntity o b jec t. Due to the nature o f the XML parser inc luded in the o b jec t
lib rary, external entities may no t b e parsed and expanded in their o wn o b jec ts
until they are needed, whic h means that two different o b jec ts are needed to ho ld
the info rmatio n.
Note
No difference: The XMLDOMEntityReference object doesn’t have any unique
properties, m ethods, or events, w hen com pared to the XMLDOMNode object. All of
the standard properties and m ethods of the XMLDOMNode object are available in
this object.
The XM LDOM Notation Object
The XMLDOMNotation o bjec t ho lds info rmatio n abo ut a no tatio n that was dec lared
in the data type dec laratio n o r sc hema sec tio n o f yo ur XML do c ument.
Chapter 21 ✦ The Document Object M odel
XM LDOM Notation object properties
Table 21-9 lists the unique pro perties o f the XMLDOMNotation o bjec t. This o bjec t
also inherits all o f the pro perties fro m the XMLDOMNode o bjec t.
Table 21-9
Unique Properties of the XM LDOM Notation Object
Property
Description
publicId
A String value containing the public identifier associated w ith the
notation.
systemId
A String containing the system identifier associated w ith the notation.
If the system identifier isn’t specified, this property w ill contain the
em pty string.
XM LDOM Notation object methods
The XMLDOMNotation o bjec t has no unique metho ds. It inherits all o f the metho ds
fo und in the XMLDOMNode o bjec t (see Table 21-1).
The XM LDOM ProcessingInstruction Object
The XMLDOMProcessingInstruction o bjec t c o ntains pro c essing direc tives, suc h
as the .
XM LDOM ProcessingInstruction object properties
Table 21-10 lists the unique pro perties o f the XMLDOMProcessingInstruction
o bjec t. This o bjec t also inherits all o f the pro perties fro m the XMLDOMNode o bjec t
(see Table 21-1).
XM LDOM ProcessingInstruction object methods
The XMLDOMProcessingInstruction o bjec t has no unique metho ds. It inherits all
o f the metho ds fo und in the XMLDOMNode o bjec t.
475
476
Part V ✦ The Impact of XM L
Table 21-10
Unique Properties of the XM LDOM ProcessingInstruction Object
Property
Description
data
A String value containing the data associated w ith the processing
instruction. In other w ords, this w ould be the version=”1.0” part of
the processing instruction. This value is identical to that in the
nodeValue property.
target
A String containing the application that contains the processing
instruction.
For exam ple, this w ould be xml from the
processing instruction.
The XM LDOM Text Object
The XMLDOMText o bjec t ho lds info rmatio n abo ut the text value asso c iated with an
XMLDOMElement o r XMLDOMAttribute no de.
XM LDOM Text object properties
Table 21-11 lists the unique pro perties asso c iated with the XMLDOMText o bjec t. All
o f the pro perties listed in the XMLDOMNode o bjec t are also available fo r this o bjec t.
Table 21-11
Unique Properties of the XM LDOM Text Object
Property
Description
data
A String value containing the text characters that m ake up the value
of an elem ent or an attribute.
length
A Long value containing the num ber of characters in data.
XM LDOM Text object methods
The XMLDOMText o bjec t inc ludes a ric h set o f metho ds to manipulate the data
sto red in the no de. It also inc ludes all o f the metho ds fo und in the XMLDOMNode
o bjec t.
Chapter 21 ✦ The Document Object M odel
Sub appendData (data as String)
The appendData metho d adds the spec ified string value to the end o f the existing
data already in the no de. data is a String value c o ntaining the new info rmatio n to
be added to the no de’s value.
Sub deleteData (offset as Long, count as Long)
The deleteData metho d remo ves the spec ified number c harac ters fro m the no de
starting with the spec ified lo c atio n. offset is a Long value c o ntaining the lo c atio n
where the c harac ters will be deleted. The first c harac ter in the string has an o ffset
o f zero . count is a Long c o ntaining the number o f c harac ters to be deleted.
Sub insertData (offset as Long, data as String)
The insertData metho d inserts the spec ified data into the data already starting
with the spec ified lo c atio n. offset is a Long c o ntaining the lo c atio n where the
c harac ters will be inserted. The first c harac ter in the string has an o ffset o f zero .
data is a String c o ntaining the c harac ters to be added.
Sub replaceData (offset as Long, count as Long, data as String)
The replaceData metho d deletes the spec ified number o f c harac ters starting at
the spec ified lo c atio n, then inserts the spec ified data starting at the same lo c atio n.
offset is a Long c o ntaining the lo c atio n where the c harac ters will be replac ed. The
first c harac ter in the string has an o ffset o f zero . count is a Long c o ntaining the
number o f c harac ters to be deleted. data is a String c o ntaining the c harac ters to
be added.
Function splitText (offset as Long) as IXM LDOM Text
The splitText metho d splits the no de into two no des at the spec ified o ffset fro m
the beginning o f the text, and auto matic ally inserts the new no de into the do c ument hierarc hy immediately fo llo wing the c urrent no de. offset is a Long c o ntaining the lo c atio n where the split will take plac e. Spec ifying an o ffset value o f zero will
mo ve all o f the text in the c urrent no de to the new no de.
Function substringData (offset as Long, count as Long) as String
The substringData metho d extrac ts a blo c k o f text fro m the no de. offset is a
Long value c o ntaining the lo c atio n where the extrac tio n will begin. The first c harac ter in the string has an o ffset o f zero . count is a Long c o ntaining the number o f
c harac ters to be extrac ted.
477
478
Part V ✦ The Impact of XM L
The XM LDOM ParseError Object
The XMLDOMParseError o bjec t c o ntains info rmatio n abo ut the first erro r enc o untered while parsing yo ur XML do c ument.
XM LDOM ParseError object properties
Table 21-12 lists the pro perties o f the XMLDOMParseError o bjec t.
Table 21-12
Properties of the XM LDOM ParseError object
Property
Description
ErrorCode
A Long value containing the error code.
Filepos
A Long containing the absolute position in the file w here the error
occurred.
Line
A Long containing the line num ber w here the error occurred.
Linepos
A Long containing the position in the line w here the error occurred.
Reason
A String value containing a text description of the error.
SrcText
A String containing the line w ith the error.
url
A String containing the URL of the docum ent w ith the error.
XM LDOM ParseError bject methods
The XMLDOMParseError o bjec t do esn’t have any metho ds.
The XM LHttpRequest Object
The XMLHttpRequest o bjec t allo ws yo u to transfer XML do c uments using HTTP.
This is primarily a c lient-side to o l that c an be used in a JavaSc ript o r VBSc ript Web
page to transmit a request to a server and pro c ess its respo nse. The pro perties and
o bjec ts that return info rmatio n abo ut the result are o nly valid if the send metho d
has c o mpleted suc c essfully.
Chapter 21 ✦ The Document Object M odel
XM LHttpRequest object properties
Table 21-13 lists the pro perties o f the XMLHttpRequest o bjec t.
Table 21-13
Properties of the XM LHttpRequest Object
Property
Description
onreadystatechange
An object reference to an event handler in a scripting language.
readyState
A Long value describing the state of the transport, w hen
loading the docum ent asynchronously (see the async
property). A value of UNINITIALIZED (0) m eans that the
object has been created but nothing has been transferred. A
value of LOADING (1) m eans that the source docum ent is being
loaded; a value of LOADED (2) m eans that the docum ent is
loaded, but none of the objects in the docum ent hierarchy are
available for access; a value of INTERACTIVE (3) m eans that
som e objects are available for use; a value of COMPLETED (4)
m eans that the docum ent has been loaded and all objects are
available for access. Note that a value of COMPLETED doesn’t
im ply that the docum ent loaded successfully.
responseBody
A Variant value containing the response to the HTTP request.
responseStream
An object reference to a Stream object containing the raw data
from the response to the HTTP request.
responseText
A String value containing the response to the HTTP request.
responseXML
An object reference to a DOMDocument object containing the
parsed XML docum ent that w as received in response to the
HTTP request.
status
A Long containing the HTTP status code returned by the HTTP
server.
statusText
A String containing the HTTP line status.
XM LHttpRequest object methods
The XMLHttpRequest o bjec t inc ludes metho ds fo r c reating and sending an HTTP
request to a Web server.
479
480
Part V ✦ The Impact of XM L
Sub abort( )
The abort metho d terminates an ac tive HTTP request.
Function getAllResponseHeaders ( ) as String
The getAllResponseHeaders metho d returns the header info rmatio n fro m the
HTTP result as a single string. Eac h header is separated by a c arriage return/ line
feed pair ( vbCrLf).
Function getResponseHeader (bstrHeader as String) as String
The getResponseHeader metho d returns the spec ified header fro m the HTTP
respo nse where bstrHeader is a String value c o ntaining the partic ular header
yo u wish to retrieve.
Sub open(bstrM ethod as String, bstrUrl As String, [varAsync],
[bstrUser], [bstrPassword])
The open metho d initializes an HTTP request. After the request is initialized, the
send metho d must be used to transfer the do c ument and wait fo r the respo nse.
bstrMethod is a String value that identifies the HTTP transfer metho d. This is
usually o ne o f the fo llo wing: GET, POST, PUT, o r PROPFIND. bstrUrl is a String
c o ntaining the URL that will be used to pro c ess the request. varAsync is a
Boolean value when True means that the c all is async hro no us. If this value isn’t
spec ified, it will default to True. bstrUser is a String c o ntaining the userid to lo g
o nto the Web server. If this parameter is missing and the Web server requires a
userId and passwo rd to lo g o n, the user will be pro mpted fo r this info rmatio n.
bstrPassword is a String c o ntaining the passwo rd asso c iated with bstrUserid.
Sub send ([varBody])
The send metho d transmits the request to the remo te ho st and o ptio nally waits fo r
the ho st’s respo nse if the user spec ified False fo r varAsync o n the open metho d.
varBody is a Variant value c o ntaining the do c ument to be sent. If this parameter
isn’t spec ified, then the c urrent do c ument is transmitted.
Sub setRequestHeader(bstrHeader as String, bstrValue as String)
The setRequestHeader metho d sets the value o f the vario us header fields befo re
the do c ument request is sent. bstrHeader is a String value c o ntaining the header
to be set. No te that the trailing c o lo n (:) o n the header sho uld no t be spec ified.
bstrValue is a String c o ntaining the value to be assigned to the header.
Chapter 21 ✦ The Document Object M odel
Thoughts on the XM L Object M odel
As I said in the previous chapter, XML is far m ore com plex than I have room to cover. This is
really obvious w hen you look at the object m odel. How ever, m uch of the com plexity isn’t
necessary for m ost program m ers. As w ith m ost things in life, the eighty-tw enty rule applies:
eighty percent of the tim e, only tw enty percent of the capabilities are needed or used.
In this case, the object m odel is designed to cover all sorts of situations that m ight not norm ally be encountered in m ost applications. In the next chapter, I’m going to use this object
m odel in a sim ple exam ple that show s you how you can generate an XML request and satisfy it w ith a Web server.
Summary
In this c hapter yo u learned:
✦ abo ut the XML Do c ument Objec t Mo del
✦ ho w an XML do c ument is mapped into the Do c ument Objec t Mo del.
✦
✦
✦
481