1domNode(n) domNode(n)
2______________________________________________________________________________
6
8 domNode - Manipulates an instance of a DOM node object
9
11 $nodeObject method arg arg ...
12_________________________________________________________________
13 DESCRIPTION
15 This command manipulates one particular instance of a DOM node object.
16 method indicates a specific method of the node class. These methods
17 should closely conform to the W3C recommendation "Document Object Model
18 (Core) Level 1" (http://www.w3.org/TR/REC-DOM-Level-1/level-one-
19 core.html) as well to parts of the W3C draft "XML Pointer Language
20 (XPointer)" (http://www.w3.org/TR/1998/WD-xptr-19980303). Please note,
21 that the XPointer methods are deprecated. Use DOM methods or XPath
22 expressions instead of them.
23 The selectNodes method implements the "XML Path Language (XPath) Ver‐
25 sion 1.0" W3C recommendation 16 November 1999
26 (http://www.w3.org/TR/1999/REC-xpath-19991116). Look at these documents
27 for a deeper understanding of the functionality.
28 The valid methods are:
30 nodeType
32 Returns the node type of that node object. This can be: ELE‐
33 MENT_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE or PRO‐
34 CESSING_INSTRUCTION_NODE.
35 nodeName
37 Returns the node name of that node object. This is the element
38 (tag) name for element nodes (type ELEMENT_NODE), the process‐
39 ing-instruction target for processing-instructions, "#text" for
40 text node, "#comment" for comment nodes or "#cdata" for cdata
41 section nodes.
42 nodeValue ?newValue?
44 Returns the value of that node object. This is the the text or
45 the data for element nodes of type TEXT_NODE, COMMENT_NODE, PRO‐
46 CESSING_INSTRUCTION_NODE or CDATA_SECTION_NODE). Otherwise it is
47 empty. If the node is a TEXT_NODE, COMMENT_NODE or PROCESS‐
48 ING_INSTRUCTION_NODE and the optional argument newValue is
49 given, the node is set to that value.
50 hasChildNodes
52 Returns 1 if the has children. Otherwise 0 is returned.
53 parentNode ?objVar?
55 Returns the parent node.
56 childNodes
58 Returns a list of direct children node objects.
59 childNodesLive
61 Returns a "live" nodeList object of the child nodes of the node
62 in the sense of the DOM recommendation. This nodeList object is
63 "live" in the sense that, for instance, changes to the children
64 of the node object that it was created from are immediately
65 reflected in the nodes returned by the NodeList accessors; it is
66 not a static snapshot of the content of the node. The both
67 accessors know by the nodeList object are "item <index>", which
68 returns the indexth item in the collection, and "length", which
69 returns the number of nodes in the list.
70 firstChild ?objVar?
72 Returns the first child as a node object.
73 lastChild ?objVar?
75 Returns the last child as a node object.
76 nextSibling ?objVar?
78 Returns the next sibling relativ to the current node as a node
79 object.
80 previousSibling ?objVar?
82 Returns the next sibling relativ to the current node as a node
83 object.
84 getElementsByTagName name
86 Returns a list of all elements in the subtree matching (glob
87 style) name.
88 getElementsByTagNameNS uri localname
90 Returns a list of all elements in the subtree matching (glob
91 style) localname and having the given namespace uri.
92 getElementById id
94 Returns the node having a id attribute with value id or the
95 emtpy string, if no node has an id attribute with that value.
96 hasAttribute attributeName
98 Returns 1 if the object node contains an attribute with name
99 attributeName . Otherwise 0 is returned.
100 getAttribute attributeName ?defaultValue?
102 Returns the value of the attribute attributeName. If attribute
103 is not available defaultValue is returned.
104 setAttribute attributeName newValue ?attributeName newValue ...?
106 Sets the value for one or more attributes. Every attributeName
107 is set to the corresponding newValue. If there isn't an
108 attribute for one or more of the attributeName this will create
109 that attribute.
110 removeAttribute attributeName
112 Removes the attribute attributeName.
113 hasAttributeNS uri localName
115 Returns 1 if the object node contains an attribute with the
116 local name localName within the namespace uri. Otherwise 0 is
117 returned.
118 getAttributeNS uri localName ?defaultValue?
120 Returns the value of the attribute with the local name localName
121 within the namespace URI uri. If the node dosn't have that
122 attribute the defaultValue is returned.
123 setAttributeNS uri qualifiedName newValue ?uri qualifiedName newValue
125 ...?
126 Sets the value for one or more full qualified attributes. Every
129 attribute qualifiedName with the namespace URI uri will be set
130 to newValue. This will create a new attribute, if it wasn't
131 avialble before. If you want to set an attribute within a names‐
132 pace you must specify the attribute name with prefix, even if
133 you want to set an already existing attribute to a new value.
134 While searching, if the attribute already exists, only the given
135 uri and the localname of the qualifiedName is used.
136 $node setAttributeNS "http://some.uri.com/wow" prefix:attr1 attrValue
140 If the uri is the empty string and the attribute name hasn't a
142 prefix, this method has the same effect as the method setAt‐
143 tribute.
144 $node setAttributeNS "" attri "some Value"
148 XML namespace nodes are not in any namespace. Set them this way:
150 $node setAttributeNS "" xmlns:myprefix "myNamespaceURI"
154 $node setAttributeNS "" xmlns "newDefaultNamespace"
155 If your qualifiedName has the prefix "xml" and you give the
157 empty string as uri, the namespace of the attribute defaults to
158 "http://www.w3.org/XML/1998/namespace", as the DOM 2 recommenda‐
159 tion requests. With the exceptions of the special prefixes
160 "xmlns" and "xml" you always must provide a non emtpy uri, if
161 your qualifiedName has a prefix.
162 removeAttributeNS uri localName
164 Removes the attribute with the local name localName within the
165 namespace uri.
166 attributes ?attributeNamePattern?
168 Returns all attributes matching the attributeNamePattern. If
169 attributeNamePattern isn't given all attributes are returned as
170 a Tcl list.
171 appendChild newChild
173 Append newChild to the end of the child list of the node.
174 insertBefore newChild refChild
176 Insert newChild before the refChild into the list of children of
177 node. If refChild is the empty string, insert newChild at the
178 end of the child nodes list of that node.
179 replaceChild newChild oldChild
181 Replace newChild with oldChild in list of children of that node.
182 oldChild will be part of the document fragment list after this
183 operation.
184 removeChild child
186 Removes child from the list of children of that node child will
187 be part of the document fragment list after this operation. It
188 is not physically deleted.
189 delete Deletes the given node and its complete child tree and frees the
191 complete internal memory. The affected nodes are not accessible
192 through the document fragment list.
193 cloneNode ?-deep?
195 Clones this node and adds the new create node into the document
196 fragment list. If the -deep option is specified, all descendant
197 nodes are also cloned.
198 ownerDocument ?domObjVar?
200 Returns the document object of the document this node belongs
201 to.
202 find attrName attrVal ?objVar?
204 Finds the node with the attribute name attrName, and attribute
205 value attrVal in the subtree starting the current node.
206 child number|all type attrName attrValue
208 (XPointer) child
209 descendant number|all type attrName attrValue
211 (XPointer) descendant
212 ancestor number|all type attrName attrValue
214 (XPointer) ancestor
215 fsibling number|all type attrName attrValue
217 (XPointer) fsibling
218 psibling number|all type attrName attrValue
220 (XPointer) psibling
221 root objVar
223 (XPointer) root
224 text Returns all text node children of that current node combined,
226 i.e. appended into one string.
227 target For a processing instruction node the target part is returned.
229 Otherwise an error is generated.
230 data For a processing instruction node the data part is returned. For
232 a text node, comment node or cdata section node the value is
233 returned. Otherwise an error is generated.
234 prefix Returns the namespace prefix.
236 namespaceURI
238 Returns the namespace URI.
239 localName
241 Returns the localName from the tag name of the given node.
242 selectNodes ?-namespaces prefixUriList? ?-cache <boolean>? xpathQuery
244 ?typeVar?
245 Returns the result of applying the XPath query xpathQuery to the
248 subtree. This can be a string/value, a list of strings, a list
249 of nodes or a list of attribute name / value pairs. If typeVar
250 is given the result type name is stored into that variable
251 (empty, bool, number, string, nodes, attrnodes or mixed).
252 The argument xpathQuery has to be a valid XPath expression. How‐
254 ever, there is one exception to that rule. Tcl variable names
255 can appear in the XPath statement at any position where it is
256 legal according to the rules of the XPath syntax to put an XPath
257 variable. The value of the variable is substituted for the vari‐
258 able name. Ignoring the syntax rules of XPath the Tcl variable
259 name may be any legal Tcl var name: local variables, global
260 variables, array entries and so on.
261 The option -namespaces expects a tcl list with prefix / names‐
263 pace pairs as argument. If this option is not given, then any
264 namespace prefix within the xpath expression will be first
265 resolved against the list of prefix / namespace pairs set with
266 the selectNodesNamespaces method for the document, the node
267 belongs to. If this fails, then the namespace definitions in
268 scope of the context node will be used to resolve the prefix. If
269 this option is given, any namespace prefix within the xpath
270 expression will be first resolved against that given list (and
271 ignoring the document global prefix / namespace list). If the
272 list bind the same prefix to different namespaces, then the
273 first binding will win. If this fails, then the namespace defi‐
274 nitions in scope of the context node will be used to resolve the
275 prefix, as usual.
276 If the -cache option is used with a true value, then the xpath‐
278 Query will be looked up in a document specific cache. If the
279 query is found, then the stored pre-compiled query will be used.
280 If the query isn't found, it will be pre-compiled and stored in
281 the cache, for use in further calls. Please notice, that the
282 xpathQuery as given as string is used as key for the cache. This
283 means, that equal XPath expressions, which differ only in white
284 space are treated as different cache entries. Special care is
285 needed, if the XPath expression includes namespace prefixes.
286 During pre-compilation, the prefixes will be resolved first to
287 the prefix / namespace pairs of the -namespaces option, if
288 given, and to the namespaces in scope of the context node at
289 pre-compilation time. If the XPath is found in the cache, nei‐
290 ther the -namespaces option nor the namespaces in scope of the
291 context node will be taken in account but the already resolved
292 (stored) namespaces will be used for the query.
293 Examples:
295 set paragraphNodes [$node selectNodes {chapter[3]//para[@type='warning' or @type='error'} ]
298 foreach paragraph $paragraphNodes {
299 lappend values [$paragraph selectNodes attribute::type]
300 }
301 set doc [dom parse {<doc xmlns="http://www.defaultnamespace.org"><child/></doc>}]
303 set root [$doc documentElement]
304 set childNodes [$root selectNodes -namespaces {default http://www.defaultnamespace.org} default:child]
305 getLine
307 Returns the line number of that node in the orignal parsed XML.
308 getColumn
310 Returns the column number of that node in the orignal parsed
311 XML.
312 asList Returns the DOM substree starting form the current node as a
314 nested Tcl list.
315 asXML ?-indent none/1..8? ?-channel channelId?
317 ?-escapeNonASCII??-escapeAllQuot?
318 Returns the DOM substree starting from the current node as the
319 root node of the result as an (optional indented) XML string or
320 sends the output directly to the given channelId. If the option
321 -escapeNonASCII is given, every non 7 bit ASCII character in
322 attribute values or element PCDATA content will be escaped as
323 character reference in decimal representation. If the option
324 -escapeAllQuot is given, quotation marks will be escaped with
325 " even in text content of elements.
326 asHTML ?-channel channelId? ?-escapeNonASCII? ?-htmlEntities?
328 Returns the DOM substree starting from the current node as the
329 root node of the result serialized acording to HTML rules (HTML
330 elements are recognized regardless of case, without end tags for
331 emtpy HTML elements etc.), as string or sends the output
332 directly to the given channelId. If the option -escapeNonASCII
333 is given, every non 7 bit ASCII character in attribute values or
334 element PCDATA content will be escaped as character reference in
335 decimal representation. If the option -htmlEntities is given, a
336 character is outputed using a HTML 4.01 character entity refer‐
337 ence, if one is defined for it.
338 asText For ELEMENT_NODEs, the asText method outputs the string-value of
340 every text node descendant of node in document order without any
341 escaping. For every other node type, this method outputs the the
342 XPath string value of that node.
343 appendFromList list
345 Parses list , creates an according DOM subtree and appends this
346 subtree to the current node.
347 appendFromScript tclScript
349 Appends the nodes created in the tclScript by Tcl functions,
350 which have been built using dom createNodeCmd, to the given
351 node.
352 insertBeforeFromScript tclScript refChild
354 Inserts the nodes created in the tclScript by Tcl functions,
355 which have been built using dom createNodeCmd, before the
356 refChild into to the list of children of node. If refChild is
357 the empty string, the new nodes will be appended.
358 appendXML XMLstring
360 Parses XMLstring, creates an according DOM subtree and appends
361 this subtree to the current node.
362 simpleTranslate outputVar specifications
364 Translate the subtree starting at the object node according to
365 the specifications in specifications and outputs the result in
366 the variable outputVar . The translation is very similar to Cost
367 Simple mode.
368 toXPath
370 Returns an XPath, which exactly addresses the given node in its
371 document. This XPath is only valid as there are no changes to
372 DOM tree made later one.
373 getBaseURI
375 Returns the baseURI of the node. This method is deprecated in
376 favor of the baseURI method.
377 baseURI ?URI?
379 Returns the present baseURI of the node. If the optional argu‐
380 ment URI is given, sets the base URI of the node and of all of
381 its child nodes out of the same enitity as node to the given
382 URI.
383 disableOutputEscaping ?boolean?
385 This method works only for text nodes; for every other nodes it
386 returns error. Without the optional argument it returns, if dis‐
387 abling output escaping is on. The return value 0 means, the
388 characters of the text node will be escaped, to generate valid
389 XML, if serialized. This is the default for every parsed or cre‐
390 ated text node (with the exception of that text nodes in a
391 result tree of an XSLT transformation, for which disabling out‐
392 put escaping was requested explicitely in the stylesheet). The
393 return value 1 means, that output escaping is disabled for this
394 text node. If such a text node is serialized (with asXML or
395 asHTML), it is literarily written, without escaping of the spe‐
396 cial XML characters. If the optional boolean value boolean is
397 given, the flag is set accordingly. You should not set this flag
398 to 1, until you really know, what you do.
399 precedes refnode
401 Compares the relative order of the node and refnode. Both nodes
402 must be part of the same documents and not out of the fragment
403 list of the document. Returns true, if node is in document order
404 (in the sense of the XPath 1.0 recommendation) before refnode
405 and false otherwise.
406 normalize ?-forXPath?
408 Puts all Text nodes in the full depth of the sub-tree underneath
409 this Node into a "normal" form where only structure (e.g., ele‐
410 ments, comments, processing instructions and CDATA sections)
411 separates Text nodes, i.e., there are neither adjacent Text
412 nodes nor empty Text nodes. If the option -forXPath is given,
413 all CDATA sections in the nodes are converted to text nodes, as
414 a first step before the normalization.
415 xslt ?-parameters parameterList? ?-ignoreUndeclaredParameters?
417 ?-xsltmessagecmd script? stylesheet ?outputVar?
418 Applies an XSLT transformation on the document using the XSLT
419 stylesheet (given as domDoc). Returns a document object contain‐
420 ing the result document of that transformation and stores it in
421 the optional outputVar.
422 The optional -parameters option sets top level <xsl:param> to
424 string values. The parameterList has to be a tcl list consisting
425 of parameter name and value pairs.
426 If the option -ignoreUndeclaredParameters is given, then parame‐
428 ter names in the parameterList given to the -parameters options
429 that are not declared as top-level parameters in the stylesheet
430 are silently ignored. Without this option, an error is raised,
431 if the user tries to set a top-level parameter, which is not
432 declared in the stylesheet.
433 The -xsltmessagecmd option sets a callback for xslt:message ele‐
435 ments in the stylesheet. The actual command consists of the
436 script, given as argument to the option, appended with the XML
437 Fragment from instantiating the xsl:message element content as
438 string (as if the XPath string() function would have been
439 applied to the XML Fragment) and a flag, which indicates, if the
440 xsl:message has an attribute "terminate" with the value "yes".
441 @attrName
443 Returns the value of the attribute attrName. Short cut for
444 getAttribute.
445 Otherwise, if an unknown method name is given, the command with the
447 same name as the given method within the namespace ::dom::domNode is
448 tried to be executed. This allows quick method additions on Tcl level.
449
451 dom, domDoc
452
454 XML, DOM, document, node, parsing
455Tcl domNode(n)