1domNode(n)                                                          domNode(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       domNode - Manipulates an instance of a DOM node object
9

SYNOPSIS

11        $nodeObject method  arg arg ...
12_________________________________________________________________
13
14 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
24       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
29       The valid methods are:
30
31       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
36       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
43       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
51       hasChildNodes
52              Returns 1 if the has children. Otherwise 0 is returned.
53
54       parentNode ?objVar?
55              Returns the parent node.
56
57       childNodes
58              Returns a list of direct children node objects.
59
60       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
71       firstChild ?objVar?
72              Returns the first child as a node object.
73
74       lastChild ?objVar?
75              Returns the last child as a node object.
76
77       nextSibling  ?objVar?
78              Returns the next sibling relativ to the current node as  a  node
79              object.
80
81       previousSibling ?objVar?
82              Returns  the  next sibling relativ to the current node as a node
83              object.
84
85       getElementsByTagName name
86              Returns a list of all elements in  the  subtree  matching  (glob
87              style) name.
88
89       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
93       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
97       hasAttribute attributeName
98              Returns  1  if  the  object node contains an attribute with name
99              attributeName . Otherwise 0 is returned.
100
101       getAttribute attributeName  ?defaultValue?
102              Returns the value of the attribute attributeName.  If  attribute
103              is not available defaultValue is returned.
104
105       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
111       removeAttribute attributeName
112              Removes the attribute attributeName.
113
114       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
119       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
124       setAttributeNS uri qualifiedName newValue ?uri  qualifiedName  newValue
125       ...?
126
127
128              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
137
138
139                     $node setAttributeNS "http://some.uri.com/wow" prefix:attr1 attrValue
140
141              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
145
146
147                     $node setAttributeNS "" attri "some Value"
148
149              XML namespace nodes are not in any namespace. Set them this way:
150
151
152
153                     $node setAttributeNS "" xmlns:myprefix "myNamespaceURI"
154                     $node setAttributeNS "" xmlns "newDefaultNamespace"
155
156              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
163       removeAttributeNS uri localName
164              Removes  the  attribute with the local name localName within the
165              namespace uri.
166
167       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
172       appendChild newChild
173              Append newChild to the end of the child list of the node.
174
175       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
180       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
185       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
190       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
194       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
199       ownerDocument ?domObjVar?
200              Returns the document object of the document  this  node  belongs
201              to.
202
203       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
207       child number|all type attrName attrValue
208              (XPointer) child
209
210       descendant number|all type attrName attrValue
211              (XPointer) descendant
212
213       ancestor number|all type attrName attrValue
214              (XPointer) ancestor
215
216       fsibling number|all type attrName attrValue
217              (XPointer) fsibling
218
219       psibling number|all type attrName attrValue
220              (XPointer) psibling
221
222       root  objVar
223              (XPointer) root
224
225       text   Returns all text node children of that  current  node  combined,
226              i.e. appended into one string.
227
228       target For  a  processing instruction node the target part is returned.
229              Otherwise an error is generated.
230
231       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
235       prefix Returns the namespace prefix.
236
237       namespaceURI
238              Returns the namespace URI.
239
240       localName
241              Returns the localName from the tag name of the given node.
242
243       selectNodes ?-namespaces prefixUriList? ?-cache  <boolean>?  xpathQuery
244       ?typeVar?
245
246
247              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
253              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
262              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
277              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
294              Examples:
295
296
297                     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
302                     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
306       getLine
307              Returns the line number of that node in the orignal parsed XML.
308
309       getColumn
310              Returns the column number of that node  in  the  orignal  parsed
311              XML.
312
313       asList Returns  the  DOM  substree  starting form the current node as a
314              nested Tcl list.
315
316       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              &quot; even in text content of elements.
326
327       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
339       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
344       appendFromList list
345              Parses list , creates an according DOM subtree and appends  this
346              subtree to the current node.
347
348       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
353       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
359       appendXML XMLstring
360              Parses XMLstring, creates an according DOM subtree  and  appends
361              this subtree to the current node.
362
363       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
369       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
374       getBaseURI
375              Returns the baseURI of the node. This method  is  deprecated  in
376              favor of the baseURI method.
377
378       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
384       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
400       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
407       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
416       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
423              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
427              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
434              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
442       @attrName
443              Returns the value of the  attribute  attrName.   Short  cut  for
444              getAttribute.
445
446       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

SEE ALSO

451       dom, domDoc
452

KEYWORDS

454       XML, DOM, document, node, parsing
455
456
457
458Tcl                                                                 domNode(n)
Impressum