flash.xml

# XMLDocument - AS3

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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

Related API Elements

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
|  | 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
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String [override] 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

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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, Flash Lite 4

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:

Copy

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

Copy

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

Copy

         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:
Copy

         <c id='1' />

### ignoreWhite

property

`public var ignoreWhite:Boolean = false`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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:

Copy

         my_xml.ignoreWhite = true;

### xmlDecl

property

`public var xmlDecl:Object = null`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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, Flash Lite 4

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.

Related API Elements

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

### createElement

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Related API Elements

XMLDocument.createTextNode()

### createTextNode

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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.

Related API Elements

XMLDocument.createElement()

### parseXML

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

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, Flash Lite 4

Returns a string representation of the XML object.

Returns

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

Examples How to use this example
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.
Copy

    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";
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00