View source for ECMAscript for XML

{{under construction}}
{{Stub}}

ECMAscript for XML (ak E4X) is an extension to ECMAscript.

It is available in
* Some [[JavaScript]] engines, e.g.
** Firefox [http://en.wikipedia.org/wiki/SpiderMonkey_(JavaScript_engine) SpiderMonkey] (the default JS engine)
* [[ActionScript 3]]

Using E4X is considerably simpler than using the [[DOM]]. Maybe some day we will be
back to the elegance of languages like LISP instead of fighting against obscure C/Java syntax. But for now there are two problems with E4X: (1) It can't read the DOM, in otherwords you only can manipulate XML as (external) data. (2) There seem to be some inconsistencies that developers complain about.

This text has been writting for casual E4X users (by a a casual user). Internal properties and methods are not covered.

== Overview ==

(to do)

== Simple use patterns ==

===  Example XML code ===
In most examples, we will use the following XML fragment, i.e. '''instructions''' will refer to the following XML fragment. It is also available as [http://tecfa.unige.ch/guides/xml/examples/e4x/instructions-empty.xml instructions-empty.xml]. Test code is [http://tecfa.unige.ch/guides/xml/examples/e4x/instructions-e4x.xhtml instructions-e4x.xhtml] (XHTML-capable Browser needed, IE will not work as of Nov 2008)
<source lang="xml">
instructions=<stepbystep>
  <doctitle>Sample document</doctitle>
  <info>
    <para>
     See <a href="http://edutechwiki.unige.ch/en/ECMAscript_for_XML"
            name="hot_link">ECMAscript for XML</a></para>
  </info>
  <steps>
    <title>List of steps</title>
    <step>
      <title status="draft">Step 1</title>
      <para>Think !</para>
    </step>
    <step id="s2">
      <title>Step 2</title>
    </step>
    <step id="s3">
      <title>Step 3</title>
      <para>That was easy !</para>
    </step>
  </steps>
</stepbystep>;
</source>

=== Creating an E4X XML object ===

;(1) Using the XML literal syntax
The easiest way is to create a new variable and just create the XML structure like this. In ECMAScript 4 (e.g. ActionScript 3) you should define the type of the variable. 
<source lang="xml">
var instructions:XML  = <stepbystep>
  <doctitle></doctitle>
  <steps>
    <title></title>
  </steps>
 </stepbystep>;
</source>
Don't forget the ";" at the end since this instruction extends over several lines.

(1b) In JavaScript 1.6 (ECMAScript 3) you can't define types and you simply use:
<source lang="javascript">
  var instructions  = <stepbystep> ....
</source>

This the same principle as creating an array or an object like this:
<source lang="javascript">
  var arr = [item1,item2,item3];
  var obj = {a:"item 1",b:"item 2",c:"item 3"}
</source>

; Using the XML constructor
(2) You also can create an XML E4X object from a string with the new XML() constructor.
<source lang="javascript">
var instruction_string = "<stepbystep>
  <doctitle></doctitle>
    <steps>
     <title></title>
    </steps>
   </stepbystep>";

var instruction2:XML = new XML(instruction_string);
</source>

(3) Dynamic values
Using the XML literal syntax is very practical when you want to create markup dynamically.

Variables and expressions can be used to create XML contents by simply wrapping them with braces ({}). 
Note: To create attribute values, omit the quotation marks (as in the example below)!

<source lang="javascript">
var URL = "http://edutechwiki.unige.ch/en/ECMAscript_for_XML";
var URL_text = "ECMAscript for XML";
var A   = <a href={URL}>{URL_text}</a>;
</source>

the value of A is:
  ECMAscript for XML
The value of A.toXMLString is:
  <a href="http://edutechwiki.unige.ch/en/ECMAscript_for_XML">ECMAscript for XML</a>

=== XML lists ===

XML lists are the other important datastructure in E4X. Lists are needed for example to hold results of queries (like NodeLists in the DOM model).

Here is a little example of an XML list:
<pre>
    <step>
      <title>step 1</title>
    </step>
    <step>
      <title>step 2</title>
    </step>
    <step>
      <title>step 3</title>
    </step>
</pre>


=== Accessing elements and attributes ===

There is a similarity between E4X objects, arrays, and traditional Objects. XML Elements are just properties and  the typical JavaScript conventions can be used:

;(1) Method object.propertyName

Used on the right side of an assignment, this convention is equivalent to calling the [[Get]] method of object with the string propertyName.
 
Used on the left side of an assignment (see later), this convention is equalent to calling the [[Put]] method of object with arguments propertyName and a value.

; (2) Method object["propertyName"] or object [index]

Attributes can be accessed and set with the attribute identifier "@".

Let's have a look at some examples:

;(1) Getting en element with the "." operator
To access an element you simply can use an expression like a.b.c to walk down the tree.

The result is either an XML fragment or an XMLList depending on whether there is only one child or several children.

* Extracting a list of elements:
  var step_list = instructions.steps.step;
: Result, i.e. step_list is now:
  <step> <title>step 1</title> </step>
  <step> <title>step 2</title></step>
  <step> <title>step 3</title>  <para>That was easy !</para></step>

; (2) Extracting precise elements with the [] operator

* Extracting element 0 of element 2 
  var para = instructions.steps.step[2].para[0];
: Result - para is:
  That was easy !
: Result - para.toXMLString is:
  

; (3) Extracting descendants with the ".." operator
* To extract descendants use the 
  var grandchild = instructions..para;
: Result, grandchild is:
  <para> See <a href="http://edutechwiki.unige.ch/en/ECMAscript_for_XML">ECMAscript for XML</a>
  </para><para>That was easy !</para>

; (4) Getting en attribute with the "@" operator
  var attr = instructions..a.@href;
: Result, attr is:
  http://edutechwiki.unige.ch/en/ECMAscript_for_XML

=== About namespaces ===

E4X can handle namespaces through the use of qualified identifiers.

E.g. to extract an xlink:href attribute in the following kind of fragment:
<source lang="xml">
xml = <STORY>
        <INFOS>
    	<a xmlns:xlink="http://www.w3.org/1999/xlink"
	   xlink:href="http://edutechwiki.unige.ch/en/ECMAscript_for_XML">ECMAscript for XML</a>
	 </INFOS>
    </STORY>;
</source>
You will have to define a Namespace object
  var NS = new Namespace("http://www.w3.org/1999/xlink");
and then use the variable as prefix
  @NS::href;
<source lang="javascript">
 function show_URL() {
      var NS = new Namespace("http://www.w3.org/1999/xlink");
      var URL = xml..a;
      var link = URL.@NS::href;
      alert ("URL (content of the 'a' tag)=" + URL + "\n" + "NameSpace=" + NS + "\nxlink:href=" + link);
      }
</source>

=== Changing elements and attributes ===

The simplest syntax is:

<source lang="javascript">
element.subelement = value ;
</source>


Example:
<source lang="javascript">
var titlecontents = instructions..step[0].title; // was Step 1
instructions..step[0].title = "Things to do first";
</source>

Notice: You can't do this:
<source lang="javascript">
titlecontents = "Things to do first";
</source>

You also can add XML:
<source lang="javascript">
 instructions..step[3] = <step>
    <title>Last step changed</title
    <list><item>Wonderful</item><item>Super</item> </list>
  </step>;
</source>

Of course, there exist methods for more complex surgery, see below.
 
=== Iteration ===

There exist two easy expressions

; for each Syntax
<source lang="javascript">
   for each item in collection {
    steps
   }
</source>

; for Syntax
<source lang="javascript">
  for variable = first downto last {
    steps
  }
</source>

== List of methods ==

=== XML Objects ===

==== Retrieving nodes and attributes ====

; attribute(attributeName)
: Returns an XMLList with 0 or 1 XML attributes associated with this XML object that have the given attributeName.

; attributes()
: returns an XMLList containing the XML attributes of an object
: Example:
  instructions.info..a.attributes()
: Returns:
  http://edutechwiki.unige.ch/en/ECMAscript_for_XML
  hot_line

; child(propertyName)
: returns the list of children in this XML object matching the given propertyName
; This is equivalent to using child.propertyName. 
  var x = instructions.child("steps");
  var y = instructions.steps;
: x==y above

; children()
: Returns an XMLList with all the children
  instructions.children()

; descendants([name])
: returns all the XML valued descendants (children, grandchildren, great-grandchildren, etc.) of this XML object with the given name. If the name parameter is omitted, it returns all descendants of this XML object.
: Example
  instructions.descendants("para")
: Same as
  instructions..para

; elements([name])
: returns an XMLList containing all the children of this XML object that are XML elements with the given name. When the elements method is called with no parameters, it returns an XMLList containing all the children of this XML object that are XML elements

; parent()
: returns the parent of this XML object

; processingInstructions([name])
: With name parameter, it returns an XMLList containing all the children of this XML object that are processing-instructions with the given name. Without parameters, it returns an XMLList containing all the children of this XML object that are processing-instructions.

; comments()
: returns an XMLList with all the comments

; text()
: returns an XMLList containing all XML properties of this XML object that represent XML text nodes.

==== Finding Names and Namespaces ====

; localName()
: returns the local name portion of the qualified name of this XML object, i.e. the element or attribute name without namespace prefix.

; name ()
: returns the qualified name associated with this XML object.

; namespace([prefix])
: If no prefix is specified, the namespace method returns the Namespace associated with the qualified name of this XML object. If a prefix is specified, the namespace method looks for a namespace in scope for this XML object with the given prefix and, if found, returns it. If no such namespace is found, the namespace method returns undefined.

; namespaceDeclarations()
: returns an Array of Namespace objects representing the namespace declarations associated with this XML object in the context of its parent.

==== Changing Names and Namespaces ====

; removeNamespace(namespace)
: removes the given namespace from the in scope namespaces of this object and all its descendents, then returns a copy of this XML object

; setLocalName(name)
: replaces the local name of this XML object with a string constructed from the given name.

; setName(name)


; addNamespace(namespace)
:

; setNamespace(ns)
: replaces the namespace associated with the name of this XML object with the given namespace.

==== Counting and other infos ====

; childIndex()
: Returns the index number (ordinal position starting at 1) with respect to parent context.
: Example
  instructions..step[2].childIndex())
: Returns
  3

; length()
: Always returns 1

; nodeKind()
: returns a string representing the Class of this XML object

==== Changing nodes and attributes ====

; appendChild(child)
: Adds a child at the end of a XMLList and returns this list. It also modifies the whole XML fragment of course.
: Example
<source lang="javascript">
  var new1 = instructions.steps.appendChild(<step><title>step 4</title>
      <para>New contents appended !</para></step>);
</source>
: Result returned is the new list of child objects
<source lang="xml">
  <steps>
  <title>List of steps</title>
    ..........
  <step><title>step 3</title><para>That was easy !</para></step>
  <step><title>step 4</title> <para>New contents appended !</para> </step>
  </steps>
</source>

; prependChild(value)
: Inserts the given child into this object prior to its existing XML properties. It's the opposite of appendChild.
: Returns this object (not the whole child list)

; insertChildAfter(child1, child2)
: inserts the given child2 after the given child1 in this XML object and returns this XML object. If child1 is null, the insertChildAfter method inserts child2 before all children of this XML object (i.e., after none of them). If child1 does not exist in this XML object, it returns without modifying this XML object.

; insertChildBefore(child1, child2)
: inserts the given child2 before the given child1 in this XML object and returns this XML object. If child1 is null, the insertChildBefore method inserts child2 after all children in this XML object (i.e., before none of them). If child1 does not exist in this XML object, it returns without modifying this XML object.

; normalize()
: puts all text nodes in this and all descendant XML objects into a normal form by merging adjacent text nodes and eliminating empty text nodes. It returns this XML object.

; contains(value)
: returns the result of comparing this XML object with the given value
: Example
  var xmlnode = instructions..step[0].title;
  append_text_string("contains()", xmlnode.contains("Step 1"));
: Returns
  true

; copy()
: returns a deep copy of this XML object with the internal Parent property set to null

; replace(propertyName, value)
: Replaces the XML properties of this XML object specified by propertyName with value and returns this XML object. The propertyName parameter may be a numeric property name, an unqualified name for a set of XML elements, a qualified name for a set of XML elements or the properties wildcard â*â.

; setChildren(value)
: replaces the XML properties of this XML object with a new set of XML properties from value. value may be a single XML object or an XMLList.

==== Value extraction and string conversion ====

; toString()
: returns a string representation of this XML object. If a value of type XML has simple content (i.e., contains no elements), it represents a primitive value and ToString returns the String contents of the XML object, omitting the start tag, attributes, namespace declarations and end tag. Otherwise, ToString returns a string representing the entire XML object, including the start tag, attributes, namespace declarations and the end tag. NOTE the actual format of the resulting string content is implementation defined.

; toXMLString()
: method returns an XML encoded string representation of this XML object. Unlike the toString method, toXMLString provides no special treatment for XML objects that contain only XML text nodes (i.e., primitive values). The toXMLString method always includes the start tag, attributes and end tag of the XML object regardless of its content. Use this to print out XML code.

; valueOf()
: returns this XML object.

==== Tests ====

; hasComplexContent()
: returns a true or flase indicating whether this XML object contains complex content, i.e. child elements. Note: attributes, comments, PIs and text nodes cannot have complex content.

; hasSimpleContent()
: returns true or false indicating whether this XML object contains simple content, i.e. if it is a text node, an attribute node or an XML element without child elements.

; inScopeNamespaces()
: returns an Array of Namespace objects representing the namespaces in scope for this XML object in the context of its parent

; propertyIsEnumerable
: returns a Boolean value indicating whether the property P will be included in the set of properties iterated over when this XML object is used in a for-in statement

=== XML List objects ===

Some of these methods also work with XMLList objects. Here is a list:

* attribute(attributeName)
* attributes()
* child(propertyName)
* children()
* comments()
* contains(value)
* copy()
* descendants([name])
* elements([name])
* hasComplexContent()
* hasSimpleContent()
* length()
* normalize()
* parent()
* processingInstructions([name])
* text()
* toString()
* toXMLString()
* valueOf()

== Examples used ==

* [http://tecfa.unige.ch/guides/xml/examples/e4x/instructions-e4x.xhtml Instructions] (look at the source

* [http://tecfa.unige.ch/guides/xml/examples/e4x/story.xhtml Story] (look at the source of this file)

== Links ==

=== Overviews ===

* [http://en.wikipedia.org/wiki/E4X ECMAScript for XML] (Wikipedia)

=== Introductions and tutorials ===

; JavaScript

* [http://www.ibm.com/developerworks/library/x-javascript4x.html E4X: JavaScript on steroids] by Grace Walker, IBM Developer Works. (2008).

* [http://www.w3schools.com/e4x/default.asp E4X Tutorial], W3Schools.

* [http://www.xml.com/pub/a/2007/11/28/introducing-e4x.html Introducing E4X] (by Kurt Cagle, xml.com, nov 2007)

* [http://rephrase.net/days/07/06/e4x E4X] by Mark. Useful as short manual !

* At Mozilla (Firefox)
** [https://developer.mozilla.org/en/E4X_Tutorial E4X Tutorial] (Mozilla Developer center)
** [https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide/Processing_XML_with_E4X Processing XML with E4X] (JavaScript 1.6 +)
** [https://developer.mozilla.org/en/E4X E4X], Mozilla Developer Center.

; Flash/ActionScript/Flex

* [http://livedocs.adobe.com/flex/3/html/help.html?content=13_Working_with_XML_03.html The E4X approach to XML processing] (Adobe, part of the Flex manual/Programming ActionScript 3.0)

* [http://livedocs.adobe.com/flex/3/html/help.html?content=databinding_6.html Using an E4X expression in a data binding expression] (Adobe)

* [http://learn.adobe.com/wiki/display/Flex/E4X E4X] (Adobe, Flex, Getting Started)

* [http://www.actionscript.org/resources/articles/222/1/Intro-to-E4X/Page1.html Intro to E4X] (Actionscript.org) by Hasan Otuome

* [http://developer.yahoo.com/flash/articles/e4x-beginner-to-advanced.html E4X: Beginner to Advanced] by Josh Tynjala, Yahoo Flash Developer Center.

* [http://www.morearty.com/blog/2007/03/13/common-e4x-pitfalls/ Common E4X pitfalls] by Mike Morearty (2007).

; Php
* [http://www.adobe.com/cfusion/communityengine/index.cfm?event=showdetails&productId=2&postId=7843 PHP5 quick database E4X queries] (Adobe, Flex cookbook) by Sand Wyrm.

; Namespaces

* [http://www.faqts.com/knowledge_base/view.phtml/aid/35123 How does E4X deal with XML with namespaces?] by Martin Honnen (2005)
* [http://www.faqts.com/knowledge_base/view.phtml/aid/35171 How can I access elements or attributes that are in a namespace?] by Martin Honnen (2005)

; Ajax
* Fremantle, Paul and Anthony Elder (1005). AJAX and scripting Web services with E4X, Part 1, IBM Works, [http://www-128.ibm.com/developerworks/webservices/library/ws-ajax1/ HTML]

=== Standard and Manuals ===

* [http://www.ecma-international.org/publications/standards/Ecma-357.htm ECMA-357 standard]
* [http://rephrase.net/days/07/06/e4x E4X] Short tutorial by Mark. Also useful as short manual !

[[Category: XML]]
[[Category: Actionscript 3]]
[[Category: Flex]]
[[Category: Programming]]
[[Category: JavaScript]]
[[Category:JavaScript]]
{{edutechwiki}}