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

NAME

8       domDoc - Manipulates an instance of a DOM document object
9

SYNOPSIS

11       domDocObjCmd method ?arg arg ...?
12_________________________________________________________________
13

DESCRIPTION

15       This  command manipulates one particular instance of a document object.
16       method indicates a specific method of the document 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).  Look  at these documents for a deeper understanding of the
20       functionality.
21
22       The valid methods are:
23
24       documentElement ?objVar?
25              Returns the top most element in the document (the root element).
26
27       getElementsByTagName name
28              Returns a list of all elements in the  document  matching  (glob
29              style) name.
30
31       getElementsByTagNameNS uri localname
32                Returns  a  list of all elements in the subtree matching (glob
33              style) localname and having the given namespace uri.
34
35       createElement tagName ?objVar?
36              Creates (allocates) a new element node with node  name  tagName,
37              append it to the hidden fragment list in the document object and
38              returns the node object.  If objVar is given the new node object
39              store in this variable.
40
41       createElementNS url tagName ?objVar?
42              Creates (allocates) a new element node within a namespace having
43              uri as the URI and node name tagName, which  could  include  the
44              namespace  prefix,  append it to the hidden fragment list in the
45              document object and returns the node object.  If objVar is given
46              the new node object store in this variable.
47
48       createTextNode text ?objVar?
49              Creates  (allocates)  a  new  text  node  with  node value text,
50              appends it to the hidden fragment list in  the  document  object
51              and  returns  the node object.  If objVar is given, the new node
52              object is stored in this variable.
53
54       createComment text ?objVar?
55              Creates (allocates) a new comment node with value text,  appends
56              it  to  the  hidden  fragment  list  in  the document object and
57              returns the node object.  If objVar is given,  the  new  comment
58              node object is stored in this variable.
59
60       createCDATASection data ?objVar?
61              Creates  (allocates)  a  new  CDATA  node  with node value data,
62              appends it to the hidden fragment list in  the  document  object
63              and  returns  the node object.  If objVar is given, the new node
64              object is stored in this variable.
65
66       createProcessingInstruction target data ?objVar?
67              Creates a process instruction, appends it to the hidden fragment
68              list  in  the  document  object and returns the node object.  If
69              objVar is given, the new node object is stored in this variable.
70
71       delete Explicitly deletes the document, including  the  associated  Tcl
72              object  commands  (for  nodes,  fragment/new nodes, the document
73              object itself) and the underlying DOM tree.
74
75       getDefaultOutputMethod
76              Returns the default output method of the document. This is  usu‐
77              ally a result of a XSLT transformation.
78
79       asXML ?-indent none/1..8? ?-channel channelId? ?-escapeNonASCII? ?-doc‐
80       typeDeclaration <boolean>? ?-escapeAllQuot?
81              Returns the DOM tree as an (optional  indented)  XML  string  or
82              sends  the output directly to the given channelId. If the option
83              -escapeNonASCII is given, every non 7  bit  ASCII  character  in
84              attribute  values  or  element PCDATA content will be escaped as
85              character reference in decimal representation.  The  flag  -doc‐
86              typeDeclaration determines, whether there will be a DOCTYPE dec‐
87              laration emitted before the first  node  of  the  document.  The
88              default  is, to do not. The DOCTYPE name will always be the ele‐
89              ment name of the document element. An external  entity  declara‐
90              tion of the external subset is only emitted, if the document has
91              a system identifier. If the option -escapeAllQuot is given, quo‐
92              tation marks will be escaped with &quot; even in text content of
93              elements.
94
95       asHTML ?-channel channelId?  ?-escapeNonASCII?  ?-htmlEntities?  ?-doc‐
96       typeDeclaration <boolean>?
97              Returns  the  DOM  tree  serialized acording to HTML rules (HTML
98              elements are recognized regardless of case, without end tags for
99              emtpy  HTML  elements  etc.),  as  string  or  sends  the output
100              directly to the given channelId. If the  option  -escapeNonASCII
101              is given, every non 7 bit ASCII character in attribute values or
102              element PCDATA content will be escaped as character reference in
103              decimal  representation. If the option -htmlEntities is given, a
104              character is outputed using a HTML 4.01 character entity  refer‐
105              ence,  if  one  is  defined for it. The flag -doctypeDeclaration
106              determines, whether there will be a DOCTYPE declaration  emitted
107              before  the  first  node  of the document. The default is, to do
108              not. The DOCTYPE name will always be the  element  name  of  the
109              document  element without case normalization. An external entity
110              declaration of the external subset is only emitted, if the docu‐
111              ment  has  a  system identifier. The doctype declaration will be
112              written from the avaliable informations, without check, if  this
113              is  a  known  (w3c)  HTML version information or if the document
114              confirms to the given HTML version.
115
116       asText The asText method outputs the  result  tree  by  outputting  the
117              string-value  of  every text node in the result tree in document
118              order without any escaping. In effect, this  is  what  the  xslt
119              output  method  "text"  (XSLT  1.0 recommendation, section 16.3)
120              does.
121
122       publicId ?publicId?
123              Returns the public identifier of the doctype declaration of  the
124              document,  if there is one, otherwise the empty string. If there
125              is a value given to the method, the  public  identifier  of  the
126              document is set to this value.
127
128       systemId ?systemId?
129              Returns  the system identifier of the doctype declaration of the
130              document, if there is one, otherwise the empty string. If  there
131              is  a  value  given  to the method, the system identifier of the
132              document is set to this value.
133
134       internalSubset ?internalSubset?
135              Returns the internal subset of the doctype  declaration  of  the
136              document,  if there is one, otherwise the empty string. If there
137              is a value given to the method, the internal subset of the docu‐
138              ment  is set to this value. Note, that none of the parsing meth‐
139              ods preserve the internal subset of a document; a freshly parsed
140              document  will  always have an empty internal subset. Also note,
141              that the method doesen't do any syntactical  check  on  a  given
142              internal subset.
143
144       cdataSectionElements (?URI:?localname|*) ?<boolean>?
145              This  method allows to control, for which element nodes the text
146              node childs will be serialized as CDATA sections  (this  affects
147              only  serialization  with  the  asXML  method,  no  text node is
148              altered in any way by this method). IF the method is called with
149              an  element name as first argument and a boolean with value true
150              as second argument, every text node child of every element  node
151              in the document with the same name as the first argument will be
152              serialized as CDATA section. If the second argument is a boolean
153              with  value  false, all text nodes of all elements with the same
154              name as the first argument will be serialized as  usual.  Names‐
155              paced   element   names   have  to  given  in  the  form  names‐
156              pace_URI:localname, not in the otherwise usual  prefix:localname
157              form.  With  two  arguments  called, the method returns the used
158              boolean value. If the method is  called  with  only  an  element
159              name,  it  will  return a boolean value, indicating, if the text
160              nodes childs of all elements with that name in the document will
161              be  serialized as CDATA section elements (return value 1) or not
162              (return value 0). If the method is called with only one argument
163              and  that argument is an asterisk ('*'), then the method returns
164              an unordered list of all element  names  of  the  document,  for
165              which  the  text node childs will be serialized as CDATA section
166              nodes.
167
168       selectNodesNamespaces ?prefixUriList?
169              This method allows to control a document global prefix to names‐
170              pace  URI  mapping,  which  will  be used for selectNodes method
171              calls (on document as well as on all nodes, which belongs to the
172              document),  if  it  is  not overwritten by using the -namespaces
173              option of the selectNodes method. Any namespace prefix within an
174              xpath  expression  will  be first resolved against this list. If
175              the list bind the same prefix to different namespaces, then  the
176              first  binding  will win. If a prefix could not resolved against
177              the document global prefix / namespaces list, then the namespace
178              definitions in scope of the context node will be used to resolve
179              the prefix, as usual. If the optional argument prefixUriList  is
180              given,  then  the  global prefix / namespace list is set to this
181              list and returns it. Without the optional  argument  the  method
182              returns the current list. The default is the empty list.
183
184       xslt    ?-parameters    parameterList?    ?-ignoreUndeclaredParameters?
185       ?-xsltmessagecmd script? stylesheet ?outputVar?
186              Applies an XSLT transformation on the whole document of the node
187              object  using  the  XSLT stylesheet (given as domDoc). Returns a
188              document object containing the result document of the  transfor‐
189              mation  and  stores that document object in the optional output‐
190              Var, if that was given.
191
192              The optional -parameters option sets top  level  <xsl:param>  to
193              string values. The parameterList has to be a tcl list consisting
194              of parameter name and value pairs.
195
196              If the option -ignoreUndeclaredParameters is given, then parame‐
197              ter  names in the parameterList given to the -parameters options
198              that are not declared as top-level parameters in the  stylesheet
199              are  silently  ignored. Without this option, an error is raised,
200              if the user tries to set a top-level  parameter,  which  is  not
201              declared in the stylesheet.
202
203              The -xsltmessagecmd option sets a callback for xslt:message ele‐
204              ments in the stylesheet. The  actual  command  consists  of  the
205              script,  given  as argument to the option, appended with the XML
206              Fragment from instantiating the xsl:message element  content  as
207              string  (as  if  the  XPath  string()  function  would have been
208              applied to the XML Fragment) and a flag, which indicates, if the
209              xsl:message has an attribute "terminate" with the value "yes".
210
211       toXSLTcmd ?objVar?
212              If  the DOM tree represents a valid XSLT stylesheet, this method
213              transforms the DOM tree  into  an  xslt  command,  otherwise  it
214              returns  error. The created xsltCmd is returnd and stored in the
215              objVar, if a var name was given. A successful transformation  of
216              the  DOM  tree  to  an  xsltCmd  removes  the domDoc cmd and all
217              nodeCmds of the document.
218
219              The syntax of the created xsltCmd is:
220
221
222
223
224                     xsltCmd method ?arg ...?
225
226
227              The valid methods are:
228
229              transform ?-parameters parameterList?  ?-ignoreUndeclaredParame‐
230              ters? ?-xsltmessagecmd script? domDoc ?outputVar?
231                     Applies  XSLT  transformation  on  the  document  domDoc.
232                     Returns a document object containing the result  document
233                     of that transformation and stores it in the optional out‐
234                     putVar.
235
236                     The  optional   -parameters   option   sets   top   level
237                     <xsl:param> to string values. The parameterList has to be
238                     a tcl list consisting of parameter name and value pairs.
239
240                     If the option -ignoreUndeclaredParameters is given,  then
241                     parameter names in the parameterList given to the -param‐
242                     eters options that are not declared as top-level  parame‐
243                     ters in the stylesheet are silently ignored. Without this
244                     option, an error is raised, if the user tries  to  set  a
245                     top-level   parameter,  which  is  not  declared  in  the
246                     stylesheet.
247
248                     The -xsltmessagecmd option sets a callback for  xslt:mes‐
249                     sage  elements in the stylesheet. The actual command con‐
250                     sists of the script, given as  argument  to  the  option,
251                     appended  with  the  XML  Fragment from instantiating the
252                     xsl:message element content as string (as  if  the  XPath
253                     string()  function  would  have  been  applied to the XML
254                     Fragment) and a flag, which indicates, if the xsl:message
255                     has an attribute "terminate" with the value "yes".
256
257              delete Deletes the xsltCmd and cleans up all used recourses
258
259              If the first argument to an xsltCmd is a domDoc or starts with a
260              "-", then the command is processed in the same way as  <xsltCmd>
261              transform.
262
263       normalize ?-forXPath?
264              Puts  all  Text nodes in the document into a "normal" form where
265              only structure (e.g., elements,  comments,  processing  instruc‐
266              tions  and CDATA sections) separates Text nodes, i.e., there are
267              neither adjacent Text nodes nor empty Text nodes. If the  option
268              -forXPath  is  given,  all  CDATA sections in the nodes are con‐
269              verted to text nodes, as a first step before the normalization.
270
271       nodeType
272              Returns the node type of the document node. This is always DOCU‐
273              MENT_NODE.
274
275       getElementById id
276              Returns  the  node  having  a  id attribute with value id or the
277              emtpy string, if no node has an id attribute with that value.
278
279       firstChild ?objVar?
280              Returns the first top level node of the document.
281
282       lastChild ?objVar?
283              Returns the last top level node of the document.
284
285       appendChild newChild
286              Append newChild to the end of the list of top level nodes of the
287              document.
288
289       removeChild child
290              Removes  child from the list of top level nodes of the document.
291              child will be part of the  document  fragment  list  after  this
292              operation. It is not physically deleted.
293
294       hasChildNodes
295              Returns 1 if the document has any nodes in the tree. Otherwise 0
296              is returned.
297
298       childNodes
299              Returns a list of the top level nodes of the document.
300
301       ownerDocument ?domObjVar?
302              Returns the document itself.
303
304       insertBefore newChild  refChild
305              Insert newChild before the refChild into the list of  top  level
306              nodes  of  the document. If refChild is the empty string, insert
307              newChild at the end of the top level nodes.
308
309       replaceChild newChild  oldChild
310              Replace newChild with oldChild in list of top level nodes of the
311              document.  oldChild  will  be part of the document fragment list
312              after this operation.
313
314       appendFromList list
315              Parses list , creates an according DOM subtree and appends  this
316              subtree at the end of the current list of top level nodes of the
317              document.
318
319       appendXML XMLstring
320              Parses XMLstring, creates an according DOM subtree  and  appends
321              this  subtree  at the end of the current list of top level nodes
322              of the document.
323
324       selectNodes ?-namespaces prefixUriList? ?-cache  <boolean>?  xpathQuery
325       ?typeVar?
326
327
328              Returns the result of applying the XPath query xpathQuery to the
329              document. The context node of the query is the root node in  the
330              sense  of  the  XPath recommendation (not the document element).
331              The result can be a string/value, a list of strings, a  list  of
332              nodes  or  a list of attribute name / value pairs. If typeVar is
333              given the result type name is stored into that variable  (empty,
334              bool, number, string, nodes, attrnodes or mixed).
335
336              The argument xpathQuery has to be a valid XPath expression. How‐
337              ever, there is one exception to that rule.  Tcl  variable  names
338              can  appear  in  the XPath statement at any position where it is
339              legal according to the rules of the XPath syntax to put an XPath
340              variable. The value of the variable is substituted for the vari‐
341              able name. Ignoring the syntax rules of XPath the  Tcl  variable
342              name  may  be  any  legal  Tcl var name: local variables, global
343              variables, array entries and so on.
344
345              The option -namespaces expects a tcl list with prefix  /  names‐
346              pace  pairs  as  argument. If this option is not given, then any
347              namespace prefix within  the  xpath  expression  will  be  first
348              resolved  against  the list of prefix / namespace pairs set with
349              the selectNodesNamespaces method  for  the  document,  the  node
350              belongs  to.  If  this  fails, then the namespace definitions in
351              scope of the context node will be used to resolve the prefix. If
352              this  option  is  given,  any  namespace prefix within the xpath
353              expression will be first resolved against that given  list  (and
354              ignoring  the  document  global prefix / namespace list). If the
355              list bind the same prefix  to  different  namespaces,  then  the
356              first binding will win.  If this fails, then the namespace defi‐
357              nitions in scope of the context node will be used to resolve the
358              prefix, as usual.
359
360              If  the -cache option is used with a true value, then the xpath‐
361              Query will be looked up in a document  specific  cache.  If  the
362              query is found, then the stored pre-compiled query will be used.
363              If the query isn't found, it will be pre-compiled and stored  in
364              the  cache,  for  use  in further calls. Please notice, that the
365              xpathQuery as given as string is used as key for the cache. This
366              means,  that equal XPath expressions, which differ only in white
367              space are treated as different cache entries.  Special  care  is
368              needed,  if  the  XPath  expression includes namespace prefixes.
369              During pre-compilation, the prefixes will be resolved  first  to
370              the  prefix  /  namespace  pairs  of  the -namespaces option, if
371              given, and to the namespaces in scope of  the  context  node  at
372              pre-compilation  time.  If the XPath is found in the cache, nei‐
373              ther the -namespaces option nor the namespaces in scope  of  the
374              context  node  will be taken in account but the already resolved
375              (stored) namespaces will be used for the query.
376
377              Examples:
378
379
380                     set paragraphNodes [$node selectNodes {chapter[3]//para[@type='warning' or @type='error'} ]
381                     foreach paragraph $paragraphNodes {
382                         lappend  values [$paragraph selectNodes attribute::type]
383                     }
384
385                     set doc [dom parse {<doc xmlns="http://www.defaultnamespace.org"><child/></doc>}]
386                     set root [$doc documentElement]
387                     set childNodes [$root selectNodes -namespaces {default http://www.defaultnamespace.org} default:child]
388
389       baseURI ?URI?
390              Returns the present baseURI of the  document.  If  the  optional
391              argument  URI is given, sets the base URI of the document to the
392              given URI.
393
394       appendFromScript tclScript
395              Appends the nodes created by the  tclScript  by  Tcl  functions,
396              which have been built using dom createNodeCmd, at the end of the
397              current list of top level nodes of the document.
398
399       insertBeforeFromScript tclScript refChild
400              Inserts the nodes created in the  tclScript  by  Tcl  functions,
401              which  have  been  built  using  dom  createNodeCmd,  before the
402              refChild into to the list of top level nodes of the document. If
403              refChild is the empty string, the new nodes will be appended.
404
405       deleteXPathCache ?xpathQuery?
406              If  called  without  the  optional  argument,  all  cached XPath
407              expressions of the  document  are  freed.  If  called  with  the
408              optional  argument  xpathQuery,  this single XPath query will be
409              removed from the cache,  if  it  is  there.  The  method  always
410              returns an empty string.
411
412       Otherwise,  if  an  unknown  method name is given, the command with the
413       same name as the given metho  within  the  namespace  ::dom::domDoc  is
414       tried to be executed. This allows quick method additions on Tcl level.
415
416       Newly created nodes are appended to a hidden fragment list. If they are
417       not moved into the tree they are automaticaly deleted, when  the  whole
418       document gets deleted.
419

SEE ALSO

421       dom, domNode
422

KEYWORDS

424       DOM node creation, document element
425
426
427
428Tcl                                                                  domDoc(n)
Impressum