XML document object

Introduction

This section illustrates how to use the MediaRich XmlDocument object. Our documentation does a good job of defining the MediaRich specific portion of our implementation and the DOM specification covers the rest. What we still need to do is bring the whole thing together.

In a nutshell the XmlDocument object parses your XML and creates an in memory representation of it as a DOM structure. You can then get data from that structure, alter it and save it. In this article we will cover the following items:

Requirements for Scripts that use the XmlDocument object

How to instantiate an XmlDocument object
How to load an XmlDocument object from a file
How to use the methods of some common DOM objects
How to use the XmlDocument object to help process images

Target Audience

This document assumes that you already have some familiarity with MediaRich, XML and the DOM. Those last two standards are showing up everywhere these days which is why we chose them as our preferred method of handling structured text. We hope that you will be able to leverage skills that you are already using in other common environments such as web browsers and servers.

Core Technologies

MediaScript enables you to write scripts to automate image & video processing. A lot of times it is convenient to get all of your input from a MRL. Other times you may want to get input from an alternative source like a database or a text file. We added the XmlDocument object to provide a standard way to work with structured text files.

XML is a technology for adding structure to data. In contrast HTML (a relative of XML), adds layout information to your data. In HTML you can say things like, “names should be displayed in red”. In XML you can convey concepts like, “images have names”.

The DOM is a programming structure specifically designed for representing documents. It is a specialized tree structure. This is a good fit for XML. In XML an entity may contain other entities. The same is true for a tree, in which nodes may contain nodes.

Example

To meet all of our goals for this document we are going to use a simple example. In our example we will get some data from an XML file and use it to do some image processing.

The reason to take this approach would be that the meta-data about the image that is in the XML file is useful to multiple processes. Your MediaScript will only encapsulate the logic for the transformation that it should perform based on the data in the XML file. The data in the XML file could also be useful to a printing company or your content management system.

For our example we are going to make some assumptions. Somewhere some process is generating XML files. Each XML file will have a unique name for each image that we want to process. Each XML file will contain one image element. Each image element will always have a relPath element and an orientation element. Each of those elements will in turn have a text node as it’s only child node. Our MediaScript will receive the XML file name as it’s only argument on the MRL.

Here is our sample XML file, image0.xml:


    <image>
    <title>image0</title>
    <relPath>/images/image0.jpg</relPath>
    <width>200</width>
    <height>200</height>
    <orientation>vertical</orientation>
    </image>

Here is our sample MediaScript, xmlfunctions.ms:


    #include "sys:xml.ms";

    function reorientImage(xmlFileName)
    {
    //instantiate an XmlDocument object
    var xmlDoc = new XmlDocument();

    //load the XmlDocument from a file
    xmlDoc.loadFile("XML:/" + xmlFileName);

    //use the DOM to find the image element
    var imgElem = xmlDoc.getElementsByTagName("image").item(0);

    //use the DOM to get the relPath
    var tmpElem = imgElem.getElementsByTagName("relPath").item(0);
    var relPath = tmpElem.childNodes.item(0).data;

    //use the DOM to get the orientation
    tmpElem = imgElem.getElementsByTagName("orientation").item(0);
    var orientation = tmpElem.childNodes.item(0).data;

    //process image
    var img = new Media();
    img.load(name @ relPath);

    if(orientation == "vertical")
    img.rotate(angle @ 90, resizeCanvas @ true);

    img.save(type @ "jpg");
    }

We would call this function with a MRL like this:


    http://localhost/mgen/xmlfuncs.ms?f=reorientImage&args=%22image0.xml

There is quite a bit going on here in just a few lines of code.

It should be noted that this is not a production ready example as all the error checking code has been omitted so that we can concentrate on just our areas of interest. This is particularly important in the case of XML because the XmlDocument object uses a non-validating XML parser. So even if the loadFile() call succeeds we are not guaranteed that the file we loaded had an image element or that the image element had a relPath element, etc… We are relying on the assumption that our company has a convention that these things are true. What we can be assured of is that the XML is well-formed. That means that all the start tags are matched by end tags, that there are no missing “>” characters and so forth.

The first portion of the code is the MediaRich dependent part. You must include xml.ms, call the XmlDocument constructor and then call the returned objects loadFile() method. At that point you have an instance of XmlDocument (xmlDoc) that is loaded with data and ready to go.

XmlDocument is derived from the DOM’s Document object. For all intents and purposes it is a DOM Document with the addition of the few methods and properties (like loadFile()) needed to make it useful in MediaRich. So immediately we can start calling Document methods like getElementsByTagName(). So we use that method to find the image element in the document. Then we call that method on the image element to get it’s relPath and orientation elements. We know based on our companies convention that each of those will have a single text node for children. So we get those nodes from the childNodes list and access their data members to get our actual values.

At this point we have all the data we need from the XML so we can now do some image processing based on that data. In this function we load the file we got from the XML and decide whether or not we need to rotate the image based on the value of orientation. Finally we save out the image.

Summary

There is no doubt that using XML requires us to do a little work up front, but what makes it worthwhile is cases where it can help us keep from embedding data in our scripts that we would like to use multiple places, or where we would rather not pass it on the MRL.

Back to Developer Resources

XML document object