Chapter 3 DynaScript Predefined Objects

DOMElement object

Object

Represents an element in an XML document.

Syntax

To use a DOMElement's property:

DOMElement.propertyName

To use a DOMElement's method:

DOMElement.MethodName( parameter ) 

Description

The getAttributes method of the DOMNode object can be used to get the set of all attributes for an element. The getAttribute and getAttributeNode methods on the DOMElement object can be used to retrieve individual attributes.

DOMElement objects have all of the properties and methods of the DOMNode object as well as the properties and methods defined here.

Example

This example contains three elements--invoice, customer, and total:

<invoice >
<customer>Jina Janson</customer>
<total>$23.95</total>
</invoice>

tagName property

Syntax

DOMElement.tagName

Description

A string containing the name of the element. Element names are case-sensitive in XML.

Example

This example writes out the name of the document element of an XML DOM document stored in domDoc.

docElem = domDoc.documentElement;
document.writeln( docElem.tagName );

getAttribute method

Syntax

DOMElement.getAttribute( name )

Description

Retrieves an attribute value by name.

Return

The attribute value as a string or an empty string if the attribute does not have value

Example

This example writes out the value of the Type attribute for each Region element in a DOM document stored in the variable domDoc:

elemlist = domDoc.getElementsByTagName( "Region" );
for ( iEl = 0 ; iEl < elemlist.length ; iEl++ ){
  elem = elemlist.item(iEl);
  document.writeln( elem.getAttribute( "Type" ) );
}

getAttributeNode method

Syntax

DOMElement.getAttributeNode( name )

Description

Retrieves an attribute node by name.

Return

A DOMAttribute object or null if there is no such attribute

Example

This example assigns a DOMAttribute object to a variable named attnode. This object represents the Type attribute for a Region element in the DOM document domDoc:

elemlist = domDoc.getElementsByTagName( "Region" );
for ( iEl = 0 ; iEl < elemlist.length ; iEl++ ){
  elem = elemlist.item(iEl);
  attnode = elem.getAttributeNode( "Type" );
  document.writeln( attnode.nodeValue );
}

See also

"DOMAttribute object"

getElementsByTagName method

Syntax

DOMElement.getElementsByTagName( name )

Description

Returns a DOMNodeList object of all descendant elements with a given tag name, in the order in which they would be encountered in the document. Tag names in XML are case-sensitive. You can use the special tag name "*" to retrieve a list of DOMElement objects regardless of the tag name.

To search for DOMElement objects in the entire document, use the getElementsByTagName method on the DOMDocument object.

Return

A list of matching Element nodes

Example

Here is a simple XML document with a nested structure:

<?xml version="1.0"?>
<List>
  <ListItem>Item 1 
    <List><ListItem>Item 1.1</ListItem>
    </List>
  </ListItem>
  <ListItem>Item 2</ListItem>
</List>

This script fragment writes out the text content of each ListItem element, in the order in which they are encountered:

var docElem = domDoc.documentElement;
elemlist = docElem.getElementsByTagName( "ListItem" );
document.writeln( elemlist.length) ;
for( iEl=0; iEl < elemlist.length ; iEl++ ){
  document.writeln( 
     elemlist.item(iEl).firstChild.nodeValue );
}

The output from this example is:

Item 1
Item 1.1
Item 2

See also

"DOMNodeList object"

normalize method

Syntax

DOMElement.normalize( )

Description

Normalizing an element places it and all its descendants into a standard format. For all DOMText node objects that are descendants of this element, adjacent (sibling) DOMText objects are combined into a single DOMText object.

Adjacent DOMCDATASection nodes are not combined even though they inherit from DOMText .

Example

This statement normalizes the element named elem:

elem.normalize();

removeAttribute method

Syntax

DOMElement.removeAttribute( att_name )

Description

Removes the specified attribute. att_name is the name of the attribute to be removed.

The method returns nothing, as required by the DOM specification. This means there is no natural way to check for the success of the method. You can, however while debugging and testing, execute a prettyPrint() on the element after the call.

Return

This method returns nothing.

Example

This function removes all Type attributes from Region elements in a DOMDocument object stored in domDoc:

function RemoveTypeAttribute( domDoc ) {
  elemlist = domDoc.getElementsByTagName( "Region" );
  for( iElem=0; iElem < elemlist.length; iElem++ ) {
    elem = elemlist.item( iElem );
    elem.removeAttribute( "Type" );
  }
}

See also

"DOMAttribute object"

removeAttributeNode method

Syntax

DOMElement.removeAttributeNode( att_node )

Description

Removes the specified attribute node.

Return

The DOMAttribute object that was removed.

Example

This example removes all Type attributes from Region elements in a DOMDocument object stored in domDoc. It confirms the removal by writing out the name of the removed attribute:

function RemoveTypeAttribute( domDoc ) {
  elemlist = domDoc.getElementsByTagName( "Region" );
  for( iElem=0; iElem < elemlist.length; iElem++ ) {
    elem = elemlist.item( iElem );
    attnode = elem.getAttributeNode( "Type" )
    old_att = elem.removeAttributeNode( attnode );
    document.writeln( "Attribute " + old_att.name + 
                             "removed" );
  }
 }

See also

"DOMAttribute object"

setAttribute method

Syntax

DOMElement.setAttribute( name, value )

Description

Adds a new attribute to the element. If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. The parameters are:

• name The name of the attribute to create or alter.
• value Value to set in string form. The string is not parsed, so any markup is treated as literal text and may need to be escaped.

To assign an attribute value that contains entity references, first create a DOMAttribute object, plus any DOMText and DOMEntityReference objects. Then insert the text and entity reference objects as children of the DOMAttribute , and use setAttributeNode to assign the attribute to the element.

Example

This function changes the value of the Type attribute for all Region elements from its current setting to County:

function SetAttribute( domDoc ){
  elemlist = domDoc.getElementsByTagName( "Region" );
  for( iElem=0; iElem < elemlist.length; iElem++ ) {
    elem = elemlist.item( iElem );
    elem.setAttribute( "Type", "County" )
    document.writeln( elem.prettyPrint() );
  }
}

See also

"DOMAttribute object"

setAttributeNode method

Syntax

DOMElement.setAttributeNode( newAttr  )

Description

Adds a new attribute. If an attribute with that name is already present in the element, it is replaced by the new one. newAttr is the DOMAttribute object representing the attribute to be set.

Return

If the newAttr attribute replaces an existing attribute with the same name, the previously existing DOMAttribute object is returned, otherwise null is returned.

Example

This function resets the value of the Type attribute for reach Region element to County. It then uses prettyPrint to display the structure of the document for debugging purposes.

function SetAttributeNode( domDoc ){
  elemlist = domDoc.getElementsByTagName( "Region" );
  for( iElem=0; iElem < elemlist.length; iElem++ ) {
    elem = elemlist.item( iElem );
    attnode = elem.getAttributeNode( "Type" );
    attnode.value = "County";
    old_att = elem.setAttributeNode( attnode );
  }
  document.writeln( domDoc.prettyPrint() );
}

See also

"DOMAttribute object"

Copyright © 2001 Sybase, Inc. All rights reserved.