1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Date: 2001/11/26 22:34:21 $ $Revision: 1.1.1.1 $ -->
<!--[ Element object description ]-->
<interface name="Element" inherits="Node" id="ID-745549614">
<descr><p>The <code>Element</code> interface represents an <termref def="dt-element">element</termref> in an HTML
or XML document. Elements may have attributes associated with them; since the
<code>Element</code> interface inherits from <code>Node</code>, the generic
<code>Node</code> interface attribute <code>attributes</code> may be used
to retrieve the set of all attributes for an element. There are methods on
the <code>Element</code> interface to retrieve either an <code>Attr</code>
object by name or an attribute value by name. In XML, where an attribute
value may contain entity references, an <code>Attr</code> object should be
retrieved to examine the possibly fairly complex sub-tree representing the
attribute value. On the other hand, in HTML, where all attributes have
simple string values, methods to directly access an attribute value can
safely be used as a <termref def="dt-convenience">convenience</termref>.</p>
<note><p>In DOM Level 2, the method <code>normalize</code> is
inherited from the <code>Node</code> interface where it was
moved.</p></note>
</descr>
<attribute type="DOMString" name="tagName" readonly="yes" id="ID-104682815">
<descr><p>The name of the element. For example, in:
<eg role="code">
<elementExample id="demo">
...
</elementExample> ,
</eg>
<code>tagName</code> has the value
<code>"elementExample"</code>. Note that this is
case-preserving in XML, as are all of the operations of the DOM.
The HTML DOM returns the <code>tagName</code> of an HTML element
in the canonical uppercase form, regardless of the case in the
source HTML document. </p>
</descr>
</attribute>
<method name="getAttribute" id="ID-666EE0F9">
<descr><p>Retrieves an attribute value by name.</p></descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute to retrieve.</p></descr>
</param>
</parameters>
<returns type="DOMString">
<descr><p>The <code>Attr</code> value as a string, or the empty string if
that attribute does not have a specified or default value.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setAttribute" id="ID-F68F082">
<descr><p>Adds a new attribute. If an attribute with that name is already
present in the element, its value is changed to be that of the value
parameter. This value is a simple string; it is not parsed as it is being
set. So any markup (such as syntax to be recognized as an entity
reference) is treated as literal text, and needs to be appropriately
escaped by the implementation when it is written out. In order to assign
an attribute value that contains entity references, the user must create
an <code>Attr</code> node plus any <code>Text</code> and
<code>EntityReference</code> nodes, build the appropriate subtree, and
use <code>setAttributeNode</code> to assign it as the value of an
attribute.</p>
<p>To set an attribute with a qualified name and namespace URI, use
the <code>setAttributeNS</code> method.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute to create or alter.</p></descr>
</param>
<param name="value" type="DOMString" attr="in">
<descr><p>Value to set in string form.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
an illegal character.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="removeAttribute" id="ID-6D6AC0F9">
<descr><p>Removes an attribute by name. If the removed attribute is known
to have a default value, an attribute immediately appears containing
the default value as well as the corresponding namespace URI,
local name, and prefix when applicable.</p>
<p>To remove an attribute by local name and namespace URI, use
the <code>removeAttributeNS</code> method.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute to remove.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="getAttributeNode" id="ID-217A91B8">
<descr><p>Retrieves an attribute node by name.</p>
<p>To retrieve an attribute node by qualified name and namespace URI, use
the <code>getAttributeNodeNS</code> method.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name (<code>nodeName</code>) of the attribute to
retrieve.</p></descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>The <code>Attr</code> node with the specified
name (<code>nodeName</code>) or <code>null</code> if there is no such
attribute.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setAttributeNode" id="ID-887236154">
<descr><p>Adds a new attribute node. If an attribute with that name
(<code>nodeName</code>) is already present in the element, it is replaced
by the new one.</p>
<p>To add a new attribute node with a qualified name and namespace URI,
use the <code>setAttributeNodeNS</code> method.</p>
</descr>
<parameters>
<param name="newAttr" type="Attr" attr="in">
<descr><p>The <code>Attr</code> node to add to the attribute
list.</p></descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>If the <code>newAttr</code> attribute replaces
an existing attribute, the replaced <code>Attr</code> node is
returned, otherwise <code>null</code> is returned.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was
created from a different document than the one that created the
element.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
<p>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already
an attribute of another <code>Element</code> object. The
DOM user must explicitly clone <code>Attr</code>
nodes to re-use them in other elements.</p></descr>
</exception>
</raises>
</method>
<method name="removeAttributeNode" id="ID-D589198">
<descr><p>Removes the specified attribute node. If the removed
<code>Attr</code> has a default value it is immediately
replaced. The replacing attribute has the same namespace URI
and local name, as well as the original prefix, when
applicable.</p>
</descr>
<parameters>
<param name="oldAttr" type="Attr" attr="in">
<descr><p>The <code>Attr</code> node to remove from the attribute
list.</p></descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>The <code>Attr</code> node that was removed.</p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
readonly.</p>
<p>NOT_FOUND_ERR: Raised if <code>oldAttr</code> is not an attribute of
the element.</p>
</descr>
</exception>
</raises>
</method>
<method name="getElementsByTagName" id="ID-1938918D">
<descr><p>Returns a <code>NodeList</code> of all <termref def="dt-descendant">descendant</termref>
<code>Elements</code> with a given tag name, in the order in which they
are encountered in a preorder traversal of this <code>Element</code>
tree.</p></descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the tag to match on. The special value "*"
matches all tags.</p></descr>
</param>
</parameters>
<returns type="NodeList">
<descr><p>A list of matching <code>Element</code> nodes.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<!-- ****** DOM Level 2 additions ****** -->
<method name="getAttributeNS" id="ID-ElGetAttrNS" since="DOM Level 2">
<descr><p>Retrieves an attribute value by local name and namespace
URI. HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to retrieve.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
attribute to retrieve.</p>
</descr>
</param>
</parameters>
<returns type="DOMString">
<descr><p>The <code>Attr</code> value as a string, or the empty string if
that attribute does not have a specified or default value.</p></descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setAttributeNS" id="ID-ElSetAttrNS" since="DOM Level 2">
<descr><p>Adds a new attribute. If an attribute with the same local name
and namespace URI is already present on the element, its prefix is
changed to be the prefix part of the <code>qualifiedName</code>, and
its value is changed to be the <code>value</code> parameter. This value
is a simple string; it is not parsed as it is being set. So any markup
(such as syntax to be recognized as an entity reference) is treated as
literal text, and needs to be appropriately escaped by the
implementation when it is written out. In order to assign an attribute
value that contains entity references, the user must create an
<code>Attr</code> node plus any <code>Text</code> and
<code>EntityReference</code> nodes, build the appropriate subtree, and
use <code>setAttributeNodeNS</code> or <code>setAttributeNode</code> to
assign it as the value of an attribute.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to create or alter.</p>
</descr>
</param>
<param name="qualifiedName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
of the attribute to create or alter.</p>
</descr>
</param>
<param name="value" type="DOMString" attr="in">
<descr><p>The value to set in string form.</p></descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
contains an illegal character.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
<p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
malformed, if the <code>qualifiedName</code> has a prefix and
the <code>namespaceURI</code> is <code>null</code>, if the
<code>qualifiedName</code> has a prefix that is
"xml" and the <code>namespaceURI</code> is different from
"<loc href='xml-ns;'>xml-ns;</loc>", or if the
<code>qualifiedName</code> is "xmlns" and the
<code>namespaceURI</code> is different from
"<loc href='xmlns-ns;'>xmlns-ns;</loc>".</p>
</descr>
</exception>
</raises>
</method>
<method name="removeAttributeNS" id="ID-ElRemAtNS" since="DOM Level 2">
<descr><p>Removes an attribute by local name and namespace URI. If
the removed attribute has a default value it is immediately
replaced. The replacing attribute has the same namespace URI
and local name, as well as the original prefix.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to remove.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
attribute to remove.</p>
</descr>
</param>
</parameters>
<returns type="void">
<descr><p></p></descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is
readonly.</p>
</descr>
</exception>
</raises>
</method>
<method name="getAttributeNodeNS" id="ID-ElGetAtNodeNS" since="DOM Level 2">
<descr><p>Retrieves an <code>Attr</code> node by local name and namespace
URI. HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to retrieve.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
attribute to retrieve.</p>
</descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>The <code>Attr</code> node with the specified attribute local
name and namespace URI or <code>null</code> if there is no such
attribute.</p>
</descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="setAttributeNodeNS" id="ID-ElSetAtNodeNS" since="DOM Level 2">
<descr><p>Adds a new attribute. If an attribute with that local name and
that namespace URI is already present in the element, it is replaced by
the new one.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="newAttr" type="Attr" attr="in">
<descr><p>The <code>Attr</code> node to add to the attribute list.</p>
</descr>
</param>
</parameters>
<returns type="Attr">
<descr><p>If the <code>newAttr</code> attribute replaces an existing
attribute with the same <termref def='dt-localname'>local
name</termref> and <termref def='dt-namespaceURI'>namespace
URI</termref>, the replaced <code>Attr</code> node is
returned, otherwise <code>null</code> is returned.</p>
</descr>
</returns>
<raises>
<exception name="DOMException">
<descr><p>WRONG_DOCUMENT_ERR: Raised if <code>newAttr</code> was
created from a different document than the one that created the
element.</p>
<p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.</p>
<p>INUSE_ATTRIBUTE_ERR: Raised if <code>newAttr</code> is already an
attribute of another <code>Element</code> object. The DOM user
must explicitly clone <code>Attr</code> nodes to re-use them in
other elements.</p>
</descr>
</exception>
</raises>
</method>
<method name="getElementsByTagNameNS" id="ID-A6C90942" since="DOM Level 2">
<descr><p>Returns a <code>NodeList</code> of all the <termref def="dt-descendant">descendant</termref>
<code>Elements</code> with a given local name and namespace URI in the
order in which they are encountered in a preorder traversal of this
<code>Element</code> tree.</p>
<p>HTML-only DOM implementations do not need to implement this
method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the elements to match on. The special value "*" matches all
namespaces.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
elements to match on. The special value "*" matches all local
names.</p>
</descr>
</param>
</parameters>
<returns type="NodeList">
<descr><p>A new <code>NodeList</code> object containing all the matched
<code>Elements</code>.</p>
</descr>
</returns>
<raises>
<!-- Throws no exceptions -->
</raises>
</method>
<method name="hasAttribute" id="ID-ElHasAttr" since="DOM Level 2">
<descr><p>Returns <code>true</code> when an attribute with a given name is
specified on this element or has a default value, <code>false</code>
otherwise.</p>
</descr>
<parameters>
<param name="name" type="DOMString" attr="in">
<descr><p>The name of the attribute to look for.</p></descr>
</param>
</parameters>
<returns type="boolean">
<descr><p><code>true</code> if an attribute with the given name is
specified on this element or has a default value, <code>false</code>
otherwise.</p>
</descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
<method name="hasAttributeNS" id="ID-ElHasAttrNS" since="DOM Level 2">
<descr><p>Returns <code>true</code> when an attribute with a given local
name and namespace URI is specified on this element or has a default
value, <code>false</code> otherwise. HTML-only DOM implementations do
not need to implement this method.</p>
</descr>
<parameters>
<param name="namespaceURI" type="DOMString" attr="in">
<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
the attribute to look for.</p>
</descr>
</param>
<param name="localName" type="DOMString" attr="in">
<descr><p>The <termref def='dt-localname'>local name</termref> of the
attribute to look for.</p>
</descr>
</param>
</parameters>
<returns type="boolean">
<descr><p><code>true</code> if an attribute with the given local name and
namespace URI is specified or has a default value on this element,
<code>false</code> otherwise.</p>
</descr>
</returns>
<raises>
<!-- No exceptions -->
</raises>
</method>
</interface>
|
