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

This article or section is a stub. It does not yet contain enough information to be considered a real article. In other words, it is a short or insufficient piece of information and requires additions.

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.

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

Overview[edit | edit source]

(to do)

Simple use patterns[edit | edit source]

Example XML code[edit | edit source]

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[edit | edit source]

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

 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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

E4X can handle namespaces through the use of qualified identifiers.

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

Changing elements and attributes[edit | edit source]

The simplest syntax is:

element.subelement = value ;

Example:

var titlecontents = instructions..step[0].title; // was Step 1
instructions..step[0].title = "Things to do first";

Notice: You can't do this:

titlecontents = "Things to do first";

You also can add XML:

 instructions..step[3] = <step>
    <title>Last step changed</title
    <list><item>Wonderful</item><item>Super</item> </list>
  </step>;

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

Iteration[edit | edit source]

There exist two easy expressions

for each Syntax

   for each item in collection {
    steps
   }

for Syntax

  for variable = first downto last {
    steps
  }

List of methods[edit | edit source]

XML Objects[edit | edit source]

Retrieving nodes and attributes[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

childIndex(): Returns the index number (ordinal position starting at 1) with respect to parent context.; Example

 instructions..step[2].childIndex())

Returns

length(): Always returns 1

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

Changing nodes and attributes[edit | edit source]

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

  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>

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[edit | edit source]

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[edit | edit source]

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