Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.xml 
XMLDocument 
Packageflash.xml
Classpublic class XMLDocument
InheritanceXMLDocument Inheritance XMLNode Inheritance Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The XMLDocument class represents the legacy XML object that was present in ActionScript 2.0. It was renamed in ActionScript 3.0 to XMLDocument to avoid name conflicts with the new XML class in ActionScript 3.0. In ActionScript 3.0, it is recommended that you use the new XML class and related classes, which support E4X (ECMAScript for XML).

The XMLDocument class, as well as XMLNode and XMLNodeType, are present for backward compatibility. The functionality for loading XML documents can now be found in the URLLoader class.

View the examples

See also



Public Properties
 PropertyDefined By
 Inheritedattributes : Object
An object containing all of the attributes of the specified XMLNode instance.
XMLNode
 InheritedchildNodes : Array
[read-only] An array of the specified XMLNode object's children.
XMLNode
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  docTypeDecl : Object = null
Specifies information about the XML document's DOCTYPE declaration.
XMLDocument
 InheritedfirstChild : XMLNode
Evaluates the specified XMLDocument object and references the first child in the parent node's child list.
XMLNode
  idMap : Object
An Object containing the nodes of the XML that have an id attribute assigned.
XMLDocument
  ignoreWhite : Boolean = false
When set to true, text nodes that contain only white space are discarded during the parsing process.
XMLDocument
 InheritedlastChild : XMLNode
An XMLNode value that references the last child in the node's child list.
XMLNode
 InheritedlocalName : String
[read-only] The local name portion of the XML node's name.
XMLNode
 InheritednamespaceURI : String
[read-only] If the XML node has a prefix, namespaceURI is the value of the xmlns declaration for that prefix (the URI), which is typically called the namespace URI.
XMLNode
 InheritednextSibling : XMLNode
An XMLNode value that references the next sibling in the parent node's child list.
XMLNode
 InheritednodeName : String
A string representing the node name of the XMLNode object.
XMLNode
 InheritednodeType : uint
A nodeType constant value, either XMLNodeType.ELEMENT_NODE for an XML element or XMLNodeType.TEXT_NODE for a text node.
XMLNode
 InheritednodeValue : String
The node value of the XMLDocument object.
XMLNode
 InheritedparentNode : XMLNode
An XMLNode value that references the parent node of the specified XML object, or returns null if the node has no parent.
XMLNode
 Inheritedprefix : String
[read-only] The prefix portion of the XML node name.
XMLNode
 InheritedpreviousSibling : XMLNode
An XMLNode value that references the previous sibling in the parent node's child list.
XMLNode
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  xmlDecl : Object = null
A string that specifies information about a document's XML declaration.
XMLDocument
Public Methods
 MethodDefined By
  
XMLDocument(source:String = null)
Creates a new XMLDocument object.
XMLDocument
 Inherited
Appends the specified node to the XML object's child list.
XMLNode
 Inherited
Constructs and returns a new XML node of the same type, name, value, and attributes as the specified XML object.
XMLNode
  
Creates a new XMLNode object with the name specified in the parameter.
XMLDocument
  
Creates a new XML text node with the specified text.
XMLDocument
 Inherited
Returns the namespace URI that is associated with the specified prefix for the node.
XMLNode
 Inherited
Returns the prefix that is associated with the specified namespace URI for the node.
XMLNode
 Inherited
Indicates whether the specified XMLNode object has child nodes.
XMLNode
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Inserts a new child node into the XML object's child list, before the beforeNode node.
XMLNode
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
Parses the XML text specified in the value parameter and populates the specified XMLDocument object with the resulting XML tree.
XMLDocument
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Removes the specified XML object from its parent.
XMLNode
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
  
[override] Returns a string representation of the XML object.
XMLDocument
 Inherited
Returns the primitive value of the specified object.
Object
Property Detail

docTypeDecl

property
public var docTypeDecl:Object = null

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Specifies information about the XML document's DOCTYPE declaration. After the XML text has been parsed into an XMLDocument object, the XMLDocument.docTypeDecl property of the XMLDocument object is set to the text of the XML document's DOCTYPE declaration (for example, <!DOCTYPE greeting SYSTEM "hello.dtd">). This property is set using a string representation of the DOCTYPE declaration, not an XMLNode object.

The legacy ActionScript XML parser is not a validating parser. The DOCTYPE declaration is read by the parser and stored in the XMLDocument.docTypeDecl property, but no DTD validation is performed.

If no DOCTYPE declaration was encountered during a parse operation, the XMLDocument.docTypeDecl property is set to null. The XML.toString() method outputs the contents of XML.docTypeDecl immediately after the XML declaration stored in XML.xmlDecl, and before any other text in the XML object. If XMLDocument.docTypeDecl is null, no DOCTYPE declaration is output.

idMap

property 
public var idMap:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

An Object containing the nodes of the XML that have an id attribute assigned. The names of the properties of the object (each containing a node) match the values of the id attributes.

Consider the following XMLDocument object:

     <employee id='41'>
         <name>
             John Doe
         </name>
         <address>
             601 Townsend St.
         </address>
     </employee>
     
     <employee id='42'>
         <name>
             Jane Q. Public
         </name>
     </employee>
     <department id="IT">
         Information Technology
     </department>
     

In this example, the idMap property for this XMLDocument object is an Object with three properties: 41, 42, and IT. Each of these properties is an XMLNode that has the matching id value. For example, the IT property of the idMap object is this node:

     <department id="IT">
         Information Technology
     </department>
     

You must use the parseXML() method on the XMLDocument object for the idMap property to be instantiated.

If there is more than one XMLNode with the same id value, the matching property of the idNode object is that of the last node parsed. For example:

     var x1:XML = new XMLDocument("<a id='1'><b id='2' /><c id='1' /></a>");
     x2 = new XMLDocument();
     x2.parseXML(x1);
     trace(x2.idMap['1']);
     
This will output the <c> node:
     <c id='1' />
     

ignoreWhite

property 
public var ignoreWhite:Boolean = false

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

When set to true, text nodes that contain only white space are discarded during the parsing process. Text nodes with leading or trailing white space are unaffected. The default setting is false.

You can set the ignoreWhite property for individual XMLDocument objects, as the following code shows:

     my_xml.ignoreWhite = true;
     

xmlDecl

property 
public var xmlDecl:Object = null

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

A string that specifies information about a document's XML declaration. After the XML document is parsed into an XMLDocument object, this property is set to the text of the document's XML declaration. This property is set using a string representation of the XML declaration, not an XMLNode object. If no XML declaration is encountered during a parse operation, the property is set to null. The XMLDocument.toString() method outputs the contents of the XML.xmlDecl property before any other text in the XML object. If the XML.xmlDecl property contains null, no XML declaration is output.

Constructor Detail

XMLDocument

()Constructor
public function XMLDocument(source:String = null)

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Creates a new XMLDocument object. You must use the constructor to create an XMLDocument object before you call any of the methods of the XMLDocument class.

Note: Use the createElement() and createTextNode() methods to add elements and text nodes to an XML document tree.

Parameters
source:String (default = null) — The XML text parsed to create the new XMLDocument object.

See also

Method Detail

createElement

()method
public function createElement(name:String):XMLNode

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Creates a new XMLNode object with the name specified in the parameter. The new node initially has no parent, no children, and no siblings. The method returns a reference to the newly created XMLNode object that represents the element. This method and the XMLDocument.createTextNode() method are the constructor methods for creating nodes for an XMLDocument object.

Parameters

name:String — The tag name of the XMLDocument element being created.

Returns
XMLNode — An XMLNode object.

See also

createTextNode

()method 
public function createTextNode(text:String):XMLNode

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Creates a new XML text node with the specified text. The new node initially has no parent, and text nodes cannot have children or siblings. This method returns a reference to the XMLDocument object that represents the new text node. This method and the XMLDocument.createElement() method are the constructor methods for creating nodes for an XMLDocument object.

Parameters

text:String — The text used to create the new text node.

Returns
XMLNode — An XMLNode object.

See also

parseXML

()method 
public function parseXML(source:String):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Parses the XML text specified in the value parameter and populates the specified XMLDocument object with the resulting XML tree. Any existing trees in the XMLDocument object are discarded.

Parameters

source:String — The XML text to be parsed and passed to the specified XMLDocument object.

toString

()method 
override public function toString():String

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Returns a string representation of the XML object.

Returns
String — A string representation of the XML object.
XMLDocumentExample.as

The following example uses the XMLDocument and XMLNode classes to parse and format an XML document. Rather than loading an external XML file, the example uses the top-level XML class to create an XML document, then parses it.
package {
    import flash.display.Sprite;
    import flash.xml.XMLDocument;
    import flash.xml.XMLNode;
    import flash.xml.XMLNodeType;

    public class XMLDocumentExample extends Sprite {
        public function XMLDocumentExample() {
            var result:XMLDocument = new XMLDocument();
            result.ignoreWhite = true;
            result.parseXML(getXMLString());

            var books:Array = parseBooks(result.firstChild);
            trace("books: \n" + books);
        }

        private function parseBooks(node:XMLNode):Array {
            var books:Array = new Array();

            var kids:Array = node.childNodes;
            for each(var item:XMLNode in kids) {
                parseBook(item, books);
            }

            return books;
        }

        private function parseBook(node:XMLNode, books:Array):void {
            var item:Book = new Book();
            item.setPublisher(node.attributes.publisher);
            item.setName(node.attributes.name);
            books.push(item);
        }

        private function getXMLString():String {
            var list:XML = <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>;
            return list.toXMLString();
        }
    }

}
class Book {
    private var publisher:String;
    private var name:String;

    public function setPublisher(publisher:String):void {
        this.publisher = publisher;
    }

    public function setName(name:String):void {
        this.name = name;
    }

    public function toString():String {
        return "[Book name: " + name + " publisher: " + publisher + "]\n";
    }
}