NAME
    XML.ObjTree -- XML source code from/to JavaScript object like E4X

SYNOPSIS
        var xotree = new XML.ObjTree();
        var tree1 = {
            root: {
                node: "Hello, World!"
            }
        };
        var xml1 = xotree.writeXML( tree1 );        // object tree to XML source
        alert( "xml1: "+xml1 );

        var xml2 = '<?xml version="1.0"?><response><error>0</error></response>';
        var tree2 = xotree.parseXML( xml2 );        // XML source to object tree
        alert( "error: "+tree2.response.error );

DESCRIPTION
    XML.ObjTree class is a parser/generater between XML source code and
    JavaScript object like E4X, ECMAScript for XML. This is a JavaScript
    version of the XML::TreePP module for Perl. This also works as a wrapper
    for XMLHTTPRequest and successor to JKL.ParseXML class when this is used
    with prototype.js or JSAN's HTTP.Request class.

  JavaScript object tree format
    A sample XML source:

        <?xml version="1.0" encoding="UTF-8"?>
        <family name="Kawasaki">
            <father>Yasuhisa</father>
            <mother>Chizuko</mother>
            <children>
                <girl>Shiori</girl>
                <boy>Yusuke</boy>
                <boy>Kairi</boy>
            </children>
        </family>

    Its JavaScript object tree like JSON/E4X:

        {
            'family': {
                '-name':    'Kawasaki',
                'father':   'Yasuhisa',
                'mother':   'Chizuko',
                'children': {
                    'girl': 'Shiori'
                    'boy': [
                        'Yusuke',
                        'Kairi'
                    ]
                }
            }
        };

    Each elements are parsed into objects:

        tree.family.father;             # the father's given name.

    Prefix '-' is inserted before every attributes' name.

        tree.family["-name"];           # this family's family name

    A array is used because this family has two boys.

        tree.family.children.boy[0];    # first boy's name
        tree.family.children.boy[1];    # second boy's name
        tree.family.children.girl;      # (girl has no other sisiters)

METHODS
  xotree = new XML.ObjTree()
    This constructor method returns a new XML.ObjTree object.

  xotree.force_array = [ "rdf:li", "item", "-xmlns" ];
    This property allows you to specify a list of element names which should
    always be forced into an array representation. The default value is
    null, it means that context of the elements will determine to make array
    or to keep it scalar.

  xotree.attr_prefix = '@';
    This property allows you to specify a prefix character which is inserted
    before each attribute names. Instead of default prefix '-', E4X-style
    prefix '@' is also available. The default character is '-'. Or set '@'
    to access attribute values like E4X, ECMAScript for XML. The length of
    attr_prefix must be just one character and not be empty.

  tree = xotree.parseXML( xmlsrc );
    This method loads an XML document using the supplied string and returns
    its JavaScript object converted.

  tree = xotree.parseDOM( domnode );
    This method parses a DOM tree (ex. responseXML.documentElement) and
    returns its JavaScript object converted.

  tree = xotree.parseHTTP( url, options );
    This method loads a XML file from remote web server and returns its
    JavaScript object converted. XMLHTTPRequest's synchronous mode is always
    used. This mode blocks the process until the response is completed.

    First argument is a XML file's URL which must exist in the same domain
    as parent HTML file's. Cross-domain loading is not available for
    security reasons.

    Second argument is options' object which can contains some parameters:
    method, postBody, parameters, onLoading, etc.

    This method requires JSAN's HTTP.Request class or prototype.js's
    Ajax.Request class.

  xotree.parseHTTP( url, options, callback );
    If a callback function is set as third argument, XMLHTTPRequest's
    asynchronous mode is used.

    This mode calls a callback function with XML file's JavaScript object
    converted after the response is completed.

  xmlsrc = xotree.writeXML( tree );
    This method parses a JavaScript object tree and returns its XML source
    generated.

EXAMPLES
  Text node and attributes
    If a element has both of a text node and attributes or both of a text
    node and other child nodes, text node's value is moved to a special node
    named "#text".

        var xotree = new XML.ObjTree();
        var xmlsrc = '<span class="author">Kawasaki Yusuke</span>';
        var tree = xotree.parseXML( xmlsrc );
        var class = tree.span["-class"];        # attribute
        var name  = tree.span["#text"];         # text node

  parseHTTP() method with HTTP-GET and sync-mode
    HTTP/Request.js or prototype.js must be loaded before calling this
    method.

        var xotree = new XML.ObjTree();
        var url = "http://example.com/index.html";
        var tree = xotree.parseHTTP( url );
        xotree.attr_prefix = '@';                   // E4X-style
        alert( tree.html["@lang"] );

    This code shows "lang=""" attribute from a X-HTML source code.

  parseHTTP() method with HTTP-POST and async-mode
    Third argument is a callback function which is called on onComplete.

        var xotree = new XML.ObjTree();
        var url = "http://example.com/mt-tb.cgi";
        var opts = {
            postBody:   "title=...&excerpt=...&url=...&blog_name=..."
        };
        var func = function ( tree ) {
            alert( tree.response.error );
        };
        xotree.parseHTTP( url, opts, func );

    This code send a trackback ping and shows its response code.

  Simple RSS reader
    This is a RSS reader which loads RDF file and displays all items.

        var xotree = new XML.ObjTree();
        xotree.force_array = [ "rdf:li", "item" ];
        var url = "http://example.com/news-rdf.xml";
        var func = function( tree ) {
            var elem = document.getElementById("rss_here");
            for( var i=0; i<tree["rdf:RDF"].item.length; i++ ) {
                var divtag = document.createElement( "div" );
                var atag = document.createElement( "a" );
                atag.href = tree["rdf:RDF"].item[i].link;
                var title = tree["rdf:RDF"].item[i].title;
                var tnode = document.createTextNode( title );
                atag.appendChild( tnode );
                divtag.appendChild( atag );
                elem.appendChild( divtag );
            }
        };
        xotree.parseHTTP( url, {}, func );

  XML-RPC using writeXML, prototype.js and parseDOM
    If you wish to use prototype.js's Ajax.Request class by yourself:

        var xotree = new XML.ObjTree();
        var reqtree = {
            methodCall: {
                methodName: "weblogUpdates.ping",
                params: {
                    param: [
                        { value: "Kawa.net xp top page" },  // 1st param
                        { value: "http://www.kawa.net/" }   // 2nd param
                    ]
                }
            }
        };
        var reqxml = xotree.writeXML( reqtree );       // JS-Object to XML code
        var url = "http://example.com/xmlrpc";
        var func = function( req ) {
            var resdom = req.responseXML.documentElement;
            xotree.force_array = [ "member" ];
            var restree = xotree.parseDOM( resdom );   // XML-DOM to JS-Object
            alert( restree.methodResponse.params.param.value.struct.member[0].value.string );
        };
        var opt = {
            method:         "post",
            postBody:       reqxml,
            asynchronous:   true,
            onComplete:     func
        };
        new Ajax.Request( url, opt );

AUTHOR
    Yusuke Kawasaki http://www.kawa.net/

COPYRIGHT AND LICENSE
    Copyright (c) 2005-2006 Yusuke Kawasaki. All rights reserved. This
    program is free software; you can redistribute it and/or modify it under
    the Artistic license. Or whatever license I choose, which I will do
    instead of keeping this documentation like it is.