PackageTop Level
Classpublic final dynamic class XMLList
InheritanceXMLList Inheritance Object

An XMLList object is an ordered collection of properties. An XMLList object represents an XML document, an XML fragment, or an arbitrary collection of XML objects.

An XMLList object with one XML element is treated the same as an XML object. When there is one XML element, all methods that are available for the XML object are also available for the XMLList object.

In the following example, example.two is an XMLList object of length 1, so you can call any XML method on it. 

 var example2 = <example><two>2</two></example>;

The following table lists the XML methods that are not included in the XMLList class, but which you can use when your XMLList object has only one XML element. If you attempt to use these methods with anything other than one XML element (zero or more than one element), an exception is thrown.

XML methods
addNamespace()
appendChild()
childIndex()
inScopeNamespace()
insertChildAFter()
insertChildBefore()
name()
namespace()
localName()
namespaceDeclarations()
nodeKind()
prependChild()
removeNamespace()
replace()
setChildren()
setLocalName()
setName()
setNamespace()

This class (along with the XML, Namespace, and QName classes) implements powerful XML-handling standards defined in ECMAScript for XML (E4X) specification (ECMA-357 edition 2).

View the examples.

See also
XML, Namespace, QName

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties
 PropertyDefined by
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods
 FunctionDefined by
  
XMLList(value:Object)
Creates a new XMLList object.
XMLList
  
attribute(attributeName:*):XMLList
Calls the attribute() method of each XML object and returns an XMLList object of the results.
XMLList
  
attributes():XMLList
Calls the attributes() method of each XML object and returns an XMLList object of attributes for each XML object.
XMLList
  
child(propertyName:Object):XMLList
Calls the child() method of each XML object and returns an XMLList object that contains the results in order.
XMLList
  
children():XMLList
Calls the children() method of each XML object and returns an XMLList object that contains the results.
XMLList
  
comments():XMLList
Calls the comments() method of each XML object and returns an XMLList of comments.
XMLList
  
contains(value:XML):Boolean
Checks whether the XMLList object contains an XML object that is equal to the given value parameter.
XMLList
  
copy():XMLList
Returns a copy of the given XMLList object.
XMLList
  
descendants(name:Object = *):XMLList
Returns all descendants (children, grandchildren, great-grandchildren, and so on) of the XML object that have the given name parameter.
XMLList
  
elements(name:Object = *):XMLList
Calls the elements() method of each XML object.
XMLList
  
hasComplexContent():Boolean
Checks whether the XMLList object contains complex content.
XMLList
  
hasOwnProperty(p:String):Boolean
Checks for the property specified by p.
XMLList
  
hasSimpleContent():Boolean
Checks whether the XMLList object contains simple content.
XMLList
 Inherited
isPrototypeOf(theClass:Object):Boolean
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
length():int
Returns the number of properties in the XMLList object.
XMLList
  
normalize():XMLList
Merges adjacent text nodes and eliminates empty text nodes for each of the following: all text nodes in the XMLList, all the XML objects contained in the XMLList, and the descendants of all the XML objects in the XMLList.
XMLList
  
parent():Object
Returns the parent of the XMLList object if all items in the XMLList object have the same parent.
XMLList
  
processingInstructions(name:String = "*"):XMLList
If a name parameter is provided, lists all the children of the XMLList object that contain processing instructions with that name.
XMLList
  
propertyIsEnumerable(p:String):Boolean
Checks whether the property p is in the set of properties that can be iterated in a for..in statement applied to the XMLList object.
XMLList
 Inherited
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Sets the availability of a dynamic property for loop operations.
Object
  
text():XMLList
Calls the text() method of each XML object and returns an XMLList object that contains the results.
XMLList
  
toString():String
Returns a string representation of all the XML objects in an XMLList object.
XMLList
  
toXMLString():String
Returns a string representation of all the XML objects in an XMLList object.
XMLList
  
valueOf():XMLList
Returns the XMLList object.
XMLList
Constructor detail
XMLList constructor

public function XMLList(value:Object)

Creates a new XMLList object.

Parameters
value:Object — Any object that can be converted to an XMLList object by using the top-level XMLList() function.

See also
top-level XMLList() function
Method detail
attribute method

public function attribute(attributeName:*):XMLList

Calls the attribute() method of each XML object and returns an XMLList object of the results. The results match the given attributeName parameter. If there is no match, the attribute() method returns an empty XMLList object.

Parameters
attributeName:* — The name of the attribute that you want to include in an XMLList object.

Returns
XMLList — An XMLList object of matching XML objects or an empty XMLList object.

See also
XML.attribute(), XML.attributes()
attributes method

public function attributes():XMLList

Calls the attributes() method of each XML object and returns an XMLList object of attributes for each XML object.

Returns
XMLList — An XMLList object of attributes for each XML object.

See also
XML.attribute(), XML.attributes()
child method

public function child(propertyName:Object):XMLList

Calls the child() method of each XML object and returns an XMLList object that contains the results in order.

Parameters
propertyName:Object — The element name or integer of the XML child.

Returns
XMLList — An XMLList object of child nodes that match the input parameter.

See also
XML.child()
children method

public function children():XMLList

Calls the children() method of each XML object and returns an XMLList object that contains the results.

Returns
XMLList — An XMLList object of the children in the XML objects.

See also
XML.children()
comments method

public function comments():XMLList

Calls the comments() method of each XML object and returns an XMLList of comments.

Returns
XMLList — An XMLList of the comments in the XML objects.

See also
XML.comments()
contains method

public function contains(value:XML):Boolean

Checks whether the XMLList object contains an XML object that is equal to the given value parameter.

Parameters
value:XML — An XML object to compare against the current XMLList object.

Returns
Boolean — If the XMLList contains the XML object declared in the value parameter, then true; otherwise false.
copy method

public function copy():XMLList

Returns a copy of the given XMLList object. The copy is a duplicate of the entire tree of nodes. The copied XML object has no parent and returns null if you attempt to call the parent() method.

Returns
XMLList — The copy of the XMLList object.
descendants method

public function descendants(name:Object = *):XMLList

Returns all descendants (children, grandchildren, great-grandchildren, and so on) of the XML object that have the given name parameter. The name parameter can be a QName object, a String data type, or any other data type that is then converted to a String data type.

To return all descendants, use the asterisk (*) parameter. If no parameter is passed, the string "*" is passed and returns all descendants of the XML object.

Parameters
name:Object (default = *) — The name of the element to match.

Returns
XMLList — An XMLList object of the matching descendants (children, grandchildren, and so on) of the XML objects in the original list. If there are no descendants, returns an empty XMLList object.

See also
XML.descendants()
elements method

public function elements(name:Object = *):XMLList

Calls the elements() method of each XML object. The name parameter is passed to the descendants() method. If no parameter is passed, the string "*" is passed to the descendants() method.

Parameters
name:Object (default = *) — The name of the elements to match.

Returns
XMLList — An XMLList object of the matching child elements of the XML objects.

See also
XML.elements()
hasComplexContent method

public function hasComplexContent():Boolean

Checks whether the XMLList object contains complex content. An XMLList object is considered to contain complex content if it is not empty and either of the following conditions is true:

Returns
Boolean — If the XMLList object contains complex content, then true; otherwise false.

See also
XML.hasComplexContent(), XML.hasSimpleContent(), hasSimpleContent()
hasOwnProperty method

public function hasOwnProperty(p:String):Boolean

Checks for the property specified by p.

Parameters
p:String — The property to match.

Returns
Boolean — If the parameter exists, then true; otherwise false.
hasSimpleContent method

public function hasSimpleContent():Boolean

Checks whether the XMLList object contains simple content. An XMLList object is considered to contain simple content if one or more of the following conditions is true:

Returns
Boolean — If the XMLList contains simple content, then true; otherwise false.

See also
XML.hasComplexContent(), XML.hasSimpleContent(), hasComplexContent()
length method

public function length():int

Returns the number of properties in the XMLList object.

Returns
int — The number of properties in the XMLList object.
normalize method

public function normalize():XMLList

Merges adjacent text nodes and eliminates empty text nodes for each of the following: all text nodes in the XMLList, all the XML objects contained in the XMLList, and the descendants of all the XML objects in the XMLList.

Returns
XMLList — The normalized XMLList object.
parent method

public function parent():Object

Returns the parent of the XMLList object if all items in the XMLList object have the same parent. If the XMLList object has no parent or different parents, the method returns undefined.

Returns
Object — Returns the parent XML object.
processingInstructions method

public function processingInstructions(name:String = "*"):XMLList

If a name parameter is provided, lists all the children of the XMLList object that contain processing instructions with that name. With no parameters, the method lists all the children of the XMLList object that contain any processing instructions.

Parameters
name:String (default = "*") — The name of the processing instructions to match.

Returns
XMLList — An XMLList object that contains the processing instructions for each XML object.

See also
XML.processingInstructions()
propertyIsEnumerable method

public function propertyIsEnumerable(p:String):Boolean

Checks whether the property p is in the set of properties that can be iterated in a for..in statement applied to the XMLList object. This is true only if toNumber(p) is greater than or equal to 0 and less than the length of the XMLList object.

Parameters
p:String — The index of a property to check.

Returns
Boolean — If the property can be iterated in a for..in statement, then true; otherwise false.
text method

public function text():XMLList

Calls the text() method of each XML object and returns an XMLList object that contains the results.

Returns
XMLList — An XMLList object of all XML properties of the XMLList object that represent XML text nodes.

See also
XML.text()
toString method

public function toString():String

Returns a string representation of all the XML objects in an XMLList object. The rules for this conversion depend on whether the XML object has simple content or complex content:

To return the entire XML object every time, use the toXMLString() method.

Returns
String — The string representation of the XML object.

Example
The following example shows what the toString() method returns when the XML object has simple content: 
var test:XML = <type name="Joe">example</type>;
trace(test.toString()); //example

The following example shows what the toString() method returns when the XML object has complex content: 
var test:XML = 
<type name="Joe">
    <base name="Bob"></base>
    example
</type>;
trace(test.toString());
  // <type name="Joe">
  // <base name="Bob"/>
  // example
  // </type>

See also
XMLList.hasSimpleContent(), XMLList.hasComplexContent(), XMLList.toXMLString()
toXMLString method

public function toXMLString():String

Returns a string representation of all the XML objects in an XMLList object. Unlike the toString() method, the toXMLString() method always returns the start tag, attributes, and end tag of the XML object, regardless of whether the XML object has simple content or complex content. (The toString() method strips out these items for XML objects that contain simple content.)

Returns
String — The string representation of the XML object.

See also
XMLList.toString()
valueOf method

public function valueOf():XMLList

Returns the XMLList object.

Returns
XMLList — Returns the current XMLList object.
Class examples

The following example creates an XML property named books and adds several items with book publisher and name tags to a node named books. Then the showBooksByPublisher() method is called, which takes the XMLList and returns each item matching the publisher, "Addison-Wesley." 
package {
    import flash.display.Sprite;

    public class XMLListExample extends Sprite {
        private var books:XML;

        public function XMLListExample() {
            books =    <books>
                        <book publisher="Addison-Wesley" name="Design Patterns" />
                        <book publisher="Addison-Wesley" name="The Pragmatic Programmer" />
                        <book publisher="Addison-Wesley" name="Test Driven Development" />
                        <book publisher="Addison-Wesley" name="Refactoring to Patterns" />
                        <book publisher="O'Reilly Media" name="The Cathedral & the Bazaar" />
                        <book publisher="O'Reilly Media" name="Unit Test Frameworks" />
                    </books>;

            showBooksByPublisher("Addison-Wesley");
        }

        private function showBooksByPublisher(name:String):void {
            var results:XMLList = books.book.(@publisher == name);
            showList(results);
        }

        private function showList(list:XMLList):void {
            var item:XML;
            for each(item in list) {
                trace("item: " + item.toXMLString());
            }
        }
    }
}



© 1996-2006 Adobe Systems Incorporated. All rights reserved.
Fri Apr 21 2006, 12:34 PDT