Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

burst.xml.DomUtil Class Reference

List of all members.

Detailed Description

Scoping class to hold static generic DOM-related utility functions; see also burst.xml.XmlDoc .


Static Public Member Functions

String escapeHtml (String s, Boolean quot_too)
 Replace: less-than, greater-than, and ampersand with their html parameters.

Object setTimeout (Window win, Function func, Number millis)
 On platforms that only support window.setTimeout of String, not Function, simulate Function support.

Node ownerDocument (Node node)
 Function to emulate node.ownerDocument in a non-compliant environment (such as IE5.0 Win).

Boolean isDocumentComplete (Document doc)
 Returns true if the document (defaults to current) is complete (finished loading).

Array getAttributeNodes (Node node)
 On W3-compliant systems, just returns node.attributes (which supports both by-number and by-name indexing).

String getInnerText (Node node)
 innerText is a convenient node member, but not part of the standard DOM .

void setInnerText (Node node, String text)
 Setting innerText.

String getInnerHTML (Node node)
 innerHTML is non-standard, but is available as a gettable and settable member variable in Mozilla, IE, and Opera 7.

void setInnerHTML (Node node, String html)
 Set innerHTML.

String getOuterHTML (Node node)
 IE has native outerHTML, but Moz does not.

void setOuterHTML (Node node, String html)
 If setting outerHTML is not native (as it is on IE), we emulate on Moz using its proprietary createContextualFragment (which is also available on recent KHTML browsers).

void insertAdjacentElement (Node node, String where, Node el)
 insertAdjacentElement, insertAdjacentHTML and insertAdjacentText are IE-specific, but convenient.

void insertAdjacentText (Node node, String where, Node el)
 Calls native insertAdjacentText if available.

void insertAdjacentHTML (Node node, String where, Node el)
 Calls native insertAdjacentHTML if available.

String serialize (Node node, Boolean isHtml)
 Serialize the provided node to a String.

Node nd (Node node, Object attmap, Node child1,...)
 Set the attributes in attmap in the provided node, and call appendChild on all children.

Element structToNode (Object st, Document doc)
 Convert a hierarchical structure to a Node.

String el (String name, Object attmap, String children,...)
 Return a String of HTML (or XML) for the element with provided name, attributes and children.

void for_children (Node node, Function unary_func, Number node_type)
 Iterate through the node's child nodes calling the provided function with each child.

Node find_child (Node node, Function unary_pred, Number node_type)
 Find the first child of node satisfying the predicate.

Node firstChildWithTagName (Node node, String name, Boolean must_exist, Boolean cs)
 Return the first child with the specified tag name, or null.

Node nthChildWithTagName (Node node, Number n, String name, Boolean must_exist, Boolean cs)
 Like firstChildWithTagName, but returns the nth (zero-based) child element with the specified tag name.

Array getChildrenWithTagName (Node node, String name, Boolean cs)
 Returns a snapshot Array, unlike getElementsByTagName(name).

Array childrenNamed (Node node, String name, Boolean is_snapshot)
 A convenience function.

String getAttribute (Element node, String name)
 Perform what Node.getAttribute should do, but doesn't always.

void setAttribute (Element node, String name, String val)
 Correct for any problems with native Node.setAttribute.

Member Function Documentation

Array burst.xml.DomUtil.childrenNamed (  Node  node,
String  name,
Boolean  is_snapshot
)  [static]
 

A convenience function.

If is_snapshot, then calls burst.xml.DomUtil.getChildrenWithTagName. Otherwise uses Node.getElementsByTagName (which differs semantically in that it returns all descendants not just immediate children).

String burst.xml.DomUtil.el (  String  name,
Object  attmap,
String  children,
... 
)  [static]
 

Return a String of HTML (or XML) for the element with provided name, attributes and children.

For attribute values, we do value quoting and escaping; the caller is not expected to. We skip attributes whose value is null. We throw on attributes whose value is undefined.

Todo:
have an XMLWriter object that supports options such as controllable indenting, doctype, etc.
Parameters:
name The element name. Case is preserved.
attmap Optional. If specified, an associative array from name to value.
children Optional. If specified, it is an (already serialized) String or an Array of String. Any following arguments are concatenated.

String burst.xml.DomUtil.escapeHtml (  String  s,
Boolean  quot_too
)  [static]
 

Replace: less-than, greater-than, and ampersand with their html parameters.

Parameters:
s The string to escape.
quot_too Optional. If true, also escape double-quote as quot.

Node burst.xml.DomUtil.find_child (  Node  node,
Function  unary_pred,
Number  node_type
)  [static]
 

Find the first child of node satisfying the predicate.

Parameters:
node 
unary_pred 
node_type Optional. One of the Node.*_NODE constants. If specified, only nodes with that type are passed to unary_pred.
Returns:
The satisfying child node, or null if none.

Node burst.xml.DomUtil.firstChildWithTagName (  Node  node,
String  name,
Boolean  must_exist,
Boolean  cs
)  [static]
 

Return the first child with the specified tag name, or null.

Note that this only iterates through immediate children (unlike DOM getElementsByTagName, which goes through all descendants). It will only return an Element child, of an Element parent.

By default (cs is false), name is uppercased prior to iteration.

Parameters:
node the parent node
name the tag name of the desired child
must_exist Optional. If true the function will throw instead of returning null.
cs Optional. If true, us a case-sensitive comparison.
Returns:
The satisfying child node, or null if none and !must_exist.

void burst.xml.DomUtil.for_children (  Node  node,
Function  unary_func,
Number  node_type
)  [static]
 

Iterate through the node's child nodes calling the provided function with each child.

Implementation note: This is implemented with firstChild and nextSibling because NodeList Node.childNodes isn't a true Array but a collection and isn't terribly efficient.

Parameters:
node A DOM Node instance.
unary_func A function taking one argument.
node_type Optional. One of the Node.*_NODE constants. If specified, only nodes with that type are passed to unary_func.

String burst.xml.DomUtil.getAttribute (  Element  node,
String  name
)  [static]
 

Perform what Node.getAttribute should do, but doesn't always.

PPK has much discussion of this, for example at: http://www.xs4all.nl/~ppk/js/w3c_core.html He suggests that Node.getAttribute in IE5 and IE6 is not always correct, saying the function is only trustworthy in Moz, Safari, IE-mac. However, I think it does actually work in IE5/IE6 except for the special cases noted below. In fact, see PPK's own tests at http://www.xs4all.nl/~ppk/js/w3c/attributes.html

Attributes that are ECMAScript reserved names

Apparently getAttribute('class') doesn't work in IE (must use getAttribute('className')). Apparently opera does not support getAttribute('className').


Disposition: Resolved. caller should pass in 'class'. We try both 'class' and 'className'. For set, we do node.className = 'whatever';

Attribute name case-sensitivity

In IE, Node.getAttribute takes a second argument that is 0 for case-insensitive, and 1 for case-insensitive. The default is 0, for case-insensitive. However, reputedly in practice IE5+ still acts case-sensitively for special attributes (e.g., requiring 'bgColor' or 'colSpan' vs. allowing 'bgcolor' or 'colspan'), see: http://www.pxl8.com/setAttribute_test.html

The W3 DOM has no such second argument. Moz and IEMac are case-insensitive at least for HTML.


Disposition: We do nothing.

Non-Standard Attributes

Apparently, only IE preserves non-standard attributes in "expando" properties. But for getAttribute and setAttribute, non-standard attributes seem to be generally supported.


Disposition: We do nothing.

Attributes for event handlers

In IE, attributes for event handlers (such as 'onclick') may be queried with getAttribute, but not set with setAttribute, but will allow a set with "expando" properties. If they are queried, IE returns a Function object, not a String. To set in IE, you have to say node[attname] = new Function(attval) instead of node.setAttribute(attname) = attval. It would be safest to use lowercase event handler names (like 'onclick', not 'onClick' or 'ONCLICK'). Alternatively, node.attachEvent(attname, new Function(attval)).

Moz returns a String from getAttribute, and supports setAttribute with String too.

The 'style' attribute

For the 'style' attribute, IE6 getAttribute('style') returns an object. Moz returns a String for getAttribute('style').

Note that object accessor "node.style" is an Object in IE. Note however that it has no value unless the document has an inline style attribute (from the document or from setAttribute).

To set a 'style' attribute, node.setAttribute(style, 'top: 5px') works in Moz, but not in IE, where it is necessary to do something like node.style.top = '5px' or node.style.cssText = 'top: 5px' or node.style.setProperty('top', '5px').

(Btw, 'float' may appear in css text, but the name for setProperty and for rule attribute is 'cssFloat'. See http://www.w3.org/TR/DOM-Level-2-Style/css.html .)

The W3 standard way to get the effective style on a element is document.defaultView.getComputedStyle(node,null). You can get particular properties with getPropertyValue('top') This is implemented in Mozilla 1.2 but not IE6, which instead has "node.currentStyle".

Note that the choice between setting style by:


Disposition: When getting, if the value is an object (and not null or string), we return value.cssText. When setting, we similarly set cssText instead.

Missing attributes

The W3 standard says that the empty string '' should be returns for attribute that aren't set. Allegedly, in NN6 getAttribute of a non-existent attribute returns '' instead of null or undefined. Moz and NN7 instead return something that tests as false. See http://www.pxl8.com/setAttribute_test.html


Disposition: We do nothing.

White space in values

Apparent IE does not preserve white space in attribute values: http://www.zvon.org/xxl/DOM2reference/Output/examples/Element_getAttribute.html


Disposition: We do nothing.

XML namespaces and prefixes

We don't do anything about xml namespaces here; we are dealing with getAttribute here, not level 2 getAttributeNS.

Todo:
A similar function with xmlns support.

Determine whether attribute global namespace is done with getAttributeNS('', n) or getAttributeNS(null,n)

Parameters:
node The node which possibly contains the attribute in question.
name The name of the attribute.
Returns:
The String value of the attribute. null or undefined is returned if none.

Array burst.xml.DomUtil.getAttributeNodes (  Node  node  )  [static]
 

On W3-compliant systems, just returns node.attributes (which supports both by-number and by-name indexing).

On IE, it returns an Array of Attr nodes (which will only support by-number). See http://www.xs4all.nl/~ppk/js/w3c_core.html

Array burst.xml.DomUtil.getChildrenWithTagName (  Node  node,
String  name,
Boolean  cs
)  [static]
 

Returns a snapshot Array, unlike getElementsByTagName(name).

Has special treatment for name '*', to return all Element children.

String burst.xml.DomUtil.getInnerHTML (  Node  node  )  [static]
 

innerHTML is non-standard, but is available as a gettable and settable member variable in Mozilla, IE, and Opera 7.

If it is not native, we implement by calling getOuterHTML on all children.

String burst.xml.DomUtil.getInnerText (  Node  node  )  [static]
 

innerText is a convenient node member, but not part of the standard DOM .

If available (as in IE), we use the native member. Otherwise we implement it ourselves.

Note that IE innerText and innerHTML are members of document.documentElement, but not of document.

In IE, innerHTML can be roundtripped (what it returns can be set). What it provides is normalized:

  • upper case tag names
  • normalized attribute quotes
  • attributes may be ordered
  • normalized ending tags (and inserting implicit ones)
  • it converts href values to absolute urls
  • it converts less-than and ampersand to character references when used in text and attributes nodes

Furthermore, IE normalizes it to its own DTD, which might include changing the doctype.

In the case of innerText, "what you see is what you get". But in the case of html, you only get concatenated text nodes. You don't get any tags. You may get less-than and ampersand, but they are literals (not markup).

See http://www.xs4all.nl/~ppk/js/w3c_html.html for which browsers implement these.

NS6 has innerHTML but does not have innerText or outerHTML.

IE5 Mac has innerHTML but not innerText.

Opera 7, has innerHTML, innerText, outerHTML, outerText. Note that (at least in beta) in Opera, innerHTML has escaped angle brackets, whereas in IE they are not: http://groups.google.com/groups?selm=65sih4uf.fsf%40hotpop.com

Todo:
Is there a reliable distinction between returning '' and null if for example there are no children?
Parameters:
node The DOM Node whose innerText should be returned as a String
Returns:
The innerText.

String burst.xml.DomUtil.getOuterHTML (  Node  node  )  [static]
 

IE has native outerHTML, but Moz does not.

If getting outerHTML is not native, we emulating by writing the top level ourselves, then calling getInnerHTML (which may in turn recursively call us again).

void burst.xml.DomUtil.insertAdjacentElement (  Node  node,
String  where,
Node  el
)  [static]
 

insertAdjacentElement, insertAdjacentHTML and insertAdjacentText are IE-specific, but convenient.

See http://msdn.microsoft.com/workshop/author/dhtml/reference/methods/insertadjacentelement.asp

Opera 7 implements them. Mozilla does not.

The emulation for insertAdjacentHTML relies on the Mozilla non-standard createContextualFragment function (also implemented in recent KHTML browsers). We do not have an implementation otherwise.

Our emulation for the other two functions, insertAdjacentElement and insertAdjacentText, does not rely on Mozilla-specific functionality.

There are available implementations of insertAdjacent* by:

We are currently using Thor's.

void burst.xml.DomUtil.insertAdjacentHTML (  Node  node,
String  where,
Node  el
)  [static]
 

Calls native insertAdjacentHTML if available.

Otherwise emulates it if Mozilla-style createContextualFragment is available. Else it throws.

void burst.xml.DomUtil.insertAdjacentText (  Node  node,
String  where,
Node  el
)  [static]
 

Calls native insertAdjacentText if available.

Otherwise emulates it.

Boolean burst.xml.DomUtil.isDocumentComplete (  Document  doc  )  [static]
 

Returns true if the document (defaults to current) is complete (finished loading).

It is very important to never call document.write after a document has finished loading. If it is, the DOM will typically re-open and replace the entire document, which may also wipe out all functions previously defined on it.

For now, this function only works with an html dom.

Parameters:
doc Optional, defaults to document.

Node burst.xml.DomUtil.nd (  Node  node,
Object  attmap,
Node  child1,
... 
)  [static]
 

Set the attributes in attmap in the provided node, and call appendChild on all children.

Todo:
: IE will blindly setAttribute('onclick', str) to a string, which doesn't work.
Parameters:
node The node in question.
attmap Optional. If specified, an associative array from name to value.
child1 Optionally any number of children (varargs). Each can be an Array of Node, or a Node.

String burst.xml.DomUtil.serialize (  Node  node,
Boolean  isHtml
)  [static]
 

Serialize the provided node to a String.

Works with a node from either an HTML or XML DOM.

Note that in some browsers (such as IE5.0 PC), document has no children. You have to pass in document.documentElement, which is a real Node.

Todo:
: offer control over putting
after things like PIs, and possibly indenting. Ultimately, we'd need a "Writer" interface.
Parameters:
node The node to start with. It is included in the result, not just its children.
isHtml Optional. If true, then we may attempt to use innerHTML when available, for efficiency.

void burst.xml.DomUtil.setAttribute (  Element  node,
String  name,
String  val
)  [static]
 

Correct for any problems with native Node.setAttribute.

See burst.xml.DomUtil.getAttribute for more information.

void burst.xml.DomUtil.setInnerHTML (  Node  node,
String  html
)  [static]
 

Set innerHTML.

At the moment this just sets the member variable: we do not have an emulation for setting innerHTML if it is not native (which it is on IE and Moz and Opera).

void burst.xml.DomUtil.setInnerText (  Node  node,
String  text
)  [static]
 

Setting innerText.

This is native on IE, but not Moz.

If it is not native, it is implemented in terms of innerHTML (which is native on Moz), by simply escaping html (less-than, greater-than, ampersand).

void burst.xml.DomUtil.setOuterHTML (  Node  node,
String  html
)  [static]
 

If setting outerHTML is not native (as it is on IE), we emulate on Moz using its proprietary createContextualFragment (which is also available on recent KHTML browsers).

We do not have an emulation otherwise.

(The technique of providing settable outerHTML using createContextualFragment may be seen by:

Object burst.xml.DomUtil.setTimeout (  Window  win,
Function  func,
Number  millis
)  [static]
 

On platforms that only support window.setTimeout of String, not Function, simulate Function support.

Parameters:
win The window to call setTimeout on
func Either a String or a Function (it'll figure out what to do).
millis The timeout delay.

Element burst.xml.DomUtil.structToNode (  Object  st,
Document  doc
)  [static]
 

Convert a hierarchical structure to a Node.

The structure is of the form: 


  [tagname, {attname1: attval1, ...}, [childname1, ...], 'some text2', [childname3, ...], ...]

The returned Node is not attached anywhere in the document by this function. That would be done afterwards by the caller.

If tagname is '#document-fragment', then createDocumentFragment is called instead of createElement. (Not that you have to use a DocumentFragment, as w3 allows appendChild on orphaned parents.)

The documentation for this class was generated from the following file:
Generated on Tue Nov 30 04:03:09 2004 for BurstProject by doxygen 1.3.4