ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
XMLDocument

Package | flash.xml
Class | public class XMLDocument
Inheritance | XMLDocument XMLNode Object

Language Version : | ActionScript 3.0

Player Version : | 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

flash.net.URLLoader
XML class

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | attributes : Object An object containing all of the attributes of the specified XMLNode instance. | XMLNode
|  | childNodes : Array [read-only] An array of the specified XMLNode object's children. | XMLNode
|  | constructor : 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
|  | firstChild : 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
|  | lastChild : XMLNode An XMLNode value that references the last child in the node's child list. | XMLNode
|  | localName : String [read-only] The local name portion of the XML node's name. | XMLNode
|  | namespaceURI : 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
|  | nextSibling : XMLNode An XMLNode value that references the next sibling in the parent node's child list. | XMLNode
|  | nodeName : String A string representing the node name of the XMLNode object. | XMLNode
|  | nodeType : uint A nodeType constant value, either XMLNodeType.ELEMENT_NODE for an XML element or XMLNodeType.TEXT_NODE for a text node. | XMLNode
|  | nodeValue : String The node value of the XMLDocument object. | XMLNode
|  | parentNode : XMLNode An XMLNode value that references the parent node of the specified XML object, or returns null if the node has no parent. | XMLNode
|  | prefix : String [read-only] The prefix portion of the XML node name. | XMLNode
|  | previousSibling : XMLNode An XMLNode value that references the previous sibling in the parent node's child list. | XMLNode
|  | prototype : 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
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | XMLDocument(source:String = null) Creates a new XMLDocument object. | XMLDocument
|  | appendChild(node:XMLNode):void Appends the specified node to the XML object's child list. | XMLNode
|  | cloneNode(deep:Boolean):XMLNode Constructs and returns a new XML node of the same type, name, value, and attributes as the specified XML object. | XMLNode
|  | createElement(name:String):XMLNode Creates a new XMLNode object with the name specified in the parameter. | XMLDocument
|  | createTextNode(text:String):XMLNode Creates a new XML text node with the specified text. | XMLDocument
|  | getNamespaceForPrefix(prefix:String):String Returns the namespace URI that is associated with the specified prefix for the node. | XMLNode
|  | getPrefixForNamespace(ns:String):String Returns the prefix that is associated with the specified namespace URI for the node. | XMLNode
|  | hasChildNodes():Boolean Indicates whether the specified XMLNode object has child nodes. | XMLNode
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | insertBefore(node:XMLNode, before:XMLNode):void Inserts a new child node into the XML object's child list, before the beforeNode node. | XMLNode
|  | 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
|  | parseXML(source:String):void Parses the XML text specified in the value parameter and populates the specified XMLDocument object with the resulting XML tree. | XMLDocument
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeNode():void Removes the specified XML object from its parent. | XMLNode
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toString():String Returns a string representation of the XML object. | XMLDocument
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

docTypeDecl | property

`public var docTypeDecl:Object = null`

Language Version : | ActionScript 3.0

Player Version : | 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

Player Version : | 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

Player Version : | 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

Player Version : | 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

Player Version : | 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

XMLDocument.createElement()
XMLDocument.createTextNode()
Method Detail

createElement | () | method

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

Language Version : | ActionScript 3.0

Player Version : | 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

XMLDocument.createTextNode()

createTextNode | () | method |

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

Language Version : | ActionScript 3.0

Player Version : | 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

XMLDocument.createElement()

parseXML | () | method |

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

Language Version : | ActionScript 3.0

Player Version : | 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

Player Version : | Flash Player 9

Returns a string representation of the XML object.

Returns

| `String` — A string representation of the XML object.

Examples How to use examples
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";
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00