ECMAscript for XML

This article or section is currently under construction

In principle, someone is working on it and there should be a better version in a not so distant future.
If you want to modify this page, please discuss it with the person working on it (see the "history")

Draft

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

It is available in

• Some JavaScript engines, e.g.
  • Firefox 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.

Usage 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 instructions-empty.xml. Test code is instructions-e4x.xhtml (XHTML-capable Browser needed, IE will not work as of Nov 2008)

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

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.

var instructions:XML  = <stepbystep>
  <doctitle></doctitle>
  <steps>
    <title></title>
  </steps>
 </stepbystep>;

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:

 var instructions  = <stepbystep> ....

This the same principle as creating an array or an object like this:

 var arr = [item1,item2,item3];
 var obj = {a:"item 1",b:"item 2",c:"item 3"}

Using the XML constructor

(2) You also can create an XML E4X object from a string with the new XML() constructor.

var instruction_string = "<stepbystep>

 <doctitle></doctitle>
 <steps>
   <title></title>
 </steps>
</stepbystep>";

var instruction2:XML = new XML(instruction_string);

(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)!

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

The value of A 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:

    <step>
      <title>step 1</title>
    </step>
    <step>
      <title>step 2</title>
    </step>
    <step>
      <title>step 3</title>
    </step>

Accessing elements and attributes

There is a similarity between E4X objects, arrays, and traditional Object.

(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, i.e. para is:

 <para>That was easy !</para>

(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: E.g. to extract an xlink:href attribute in the following kind of fragment: 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>;

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;

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

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

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.

Counting

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

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.

Exampleinstructions.info..a.attributes()

 var new1 = instructions.steps.appendChild(<step><title>step 4</title>
     <para>New contents appended !</para></step>);

Result returned is the new list of child objects

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

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.

name()

normalize()

parent()

processingInstructions([name])

comments()

returns an XMLList with all the comments

prependChild(value)

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

removeNamespace(namespace)

copy()

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

replace(propertyName, value)

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

(to do)

namespace([prefix])

namespaceDeclarations()

addNamespace(namespace)

setChildren(value)

nodeKind()

setLocalName(name)

setName(name)

setNamespace(ns)

text()

toString()

toXMLString()

valueOf()

Other stuff

attribute(attributeName)

attributes()

child(propertyName)

normalize()

parent()

children()

processingInstructions([name])

comments()

contains(value)

copy()

descendants([name])

elements([name])

hasComplexContent()

hasSimpleContent()

text()

toString()

toXMLString()

length()

valueOf()

Examples used

• Instructions (look at the source

• Story (look at the source of this file)

Links

Overviews

• ECMAScript for XML (Wikipedia)

Introductions and tutorials

JavaScript

• E4X: JavaScript on steroids by Grace Walker, IBM Developer Works. (2008).

• E4X Tutorial, W3Schools.

• Introducing E4X (by Kurt Cagle, xml.com, nov 2007)

• E4X by Mark. Useful as short manual !

• At Mozilla (Firefox)
  • E4X Tutorial (Mozilla Developer center)
  • Processing XML with E4X (JavaScript 1.6 +)
  • E4X, Mozilla Developer Center.

Flash/ActionScript/Flex

• The E4X approach to XML processing (Adobe, part of the Flex manual/Programming ActionScript 3.0)

• Using an E4X expression in a data binding expression (Adobe)

• E4X (Adobe, Flex, Getting Started)

• Intro to E4X (Actionscript.org) by Hasan Otuome

• E4X: Beginner to Advanced by Josh Tynjala, Yahoo Flash Developer Center.

• Common E4X pitfalls by Mike Morearty (2007).

Php

• PHP5 quick database E4X queries (Adobe, Flex cookbook) by Sand Wyrm.

Namespaces

• How does E4X deal with XML with namespaces? by Martin Honnen (2005)
• 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, HTML

Standard and Manuals

• ECMA-357 standard
• E4X Short tutorial by Mark. Also useful as short manual !