XParser

The first component in FooReader.NET is XParser, a JavaScript class that parses RSS and Atom feeds into JavaScript objects that can be easily used in web applications. The primary goal of XParser is to provide an interface for developers to easily access the most important elements. Not only does this save lines of code (not to mention download time), but extra, unnecessary work for the client as well.

The class-centric .NET Framework primarily inspires its design: with three classes comprising the main XParser class: XParserItem, XParserElement, and XParserAttribute.

Starting with the simplest class in XParser, XParserAttribute is a representation of an element's attribute. Attributes tend to have only one desired piece of data: its value, and that is the only property of XParserAttribute.

function XParserAttribute(oNode) {
    this.value = oNode.nodeValue;
}

The XParserAttribute constructor takes one argument, the DOM attribute node. From this node, the attribute's value is accessed and stored to the value property by the node's nodeValue property. Simple, eh?

The XParserElement class represents an XML element and is responsible for accessing and retrieving the element's value and attributes. The class's constructor accepts two arguments: the XML element's node and the value of that node.

function XParserElement(oNode,sValue) {
    this.node = oNode || false;
    this.value = sValue || (this.node && this.node.text) || false;

In these first few lines, two of the four class properties are set according to the values of the parameters. Notice the use of the OR (| |) operator in the assignment.

In the assignment of node, using the OR operator is a shorthand version of the ternary operator and produces the same results as this.node = (oNode)?oNode:false;. The assignment of value works more like an if…else if block.

if (sValue) {
    this.value = sValue;
}else if (this.node && this.node.text) {
    this.value = this.node.text;
} else {
    this.value = false;
}

The shorthand version removes over half of the characters of the if...else if block, and cutting excess characters is always good.

The next few lines build the attributes collection, a collection of XParserAttribute objects.

if (this.node) {
    this.attributes = [];
    var oAtts = this.node.attributes;
    for (var i = 0; i < oAtts.length; i++) {
        this.attributes[i] = new XParserAttribute(oAtts[i]);
        this.attributes[oAtts[i].nodeName] = new
            XParserAttribute(oAtts[i]);
    }
} else {
    this.attributes = false;
}
this.isNull = (!this.node && !this.value && !this.attributes);

The existence of the node is checked first. (There's no sense in creating a collection of attributes of a node that doesn't exist.) Then an array is created, and the element's attributes are collected through the DOM property attributes. Using a for loop, the attribute node is used in the creation of XParserAttribute objects; one using an integer key, and one using the attribute's name as a key that is retrieved with the nodeName property. The latter is to allow easy access to specific attributes where the name of the attribute is known.

If the element's node does not exist, attributes is set to false. (You can't divide by 0, and you can't get attributes from a node that doesn't exist.) Last, isNull is assigned. The isNull property enables you to check if the resulting object is null or not. If the node, value, and attributes properties are all false, then the XParserElement object is considered to be null.

The XParserItem class represents an <rss:item/> or an <atom:entry/> element (from now on, these elements will be referred to as simply items). Items consist of several elements, so naturally there will be quite a bit of parsing. The XParserItem constructor takes one argument called itemNode, which represents the item's DOM node.

function XParserItem(itemNode) {
    this.title=this.link=this.author=this.description=this.date =
        new XParserElement();

This first line of this class is important. Even though RSS and Atom are standards, it does not necessarily mean that everyone follows the given standards. An RSS feed may leave out the <author/> element in one or all items, or an Atom feed may disregard the <content/> tag in favor of the <summary/> tag. Because of these discrepancies, it is important that the XParserItem properties have a default value in order to avoid errors down the road. This default value is a null XParserElement. Now it is time to start parsing the child elements.

for (var i = 0; i < itemNode.childNodes.length; i++) {
    var oNode = itemNode.childNodes[i];
    if (oNode.nodeType == 1) {
        switch (oNode.tagName.toLowerCase()) {

To begin, a for loop cycles through the child elements. The node's type is then checked; if nodeType is 1, then the current node is an element. Checking a node's type may seem like an odd thing to do, but it is necessary. Mozilla can count white space between elements as children; therefore, checking the nodeType avoids errors when the node is sent to XParserElement. When it is confirmed that the current node is indeed an element, the tag name is used in a switch…case block and the item's properties are assigned according to their tag name counterparts.

//Shared Tags
case "title":
    this.title = new XParserElement(oNode);
break;
case "link":
    if (oNode.getAttribute("href")) {
        this.link = new XParserElement(oNode,oNode.getAttribute("href"));
    } else {
        this.link = new XParserElement(oNode);
    }
break;
case "author":
    this.author = new XParserElement(oNode);
break;

Although different in many ways, RSS and Atom do have a few elements in common. In this code these like elements are the <title/>, <link/>, and <author/> elements. The only difference is in the <link/> element; in an Atom feed the desired value is located in the href attribute. The RSS value is simply the element's value.

//RSS Tags
case "description":
    this.description = new XParserElement(oNode);
break;
case "pubdate":
    this.date = new XParserElement(oNode);
break;

Following the shared elements are the RSS-specific elements, where the <description/> and <pub-date /> elements are matched and sent to XParserElement.

//Atom Tags
case "content":
    this.description = new XParserElement(oNode);

break;
case "issued":
    this.date = new XParserElement(oNode);
break;

In this code, the Atom-specific elements <content/> and <issued/> are matched. The last elements checked are extensions:

//Extensions
case "dc:date":
    this.date = new XParserElement(oNode);
break;
default:
break;

This code checks for the <dc:date/> element, a part of the Dublin Core extension (http://dublincore.org/documents/dcmi-terms/). This extension is widely used, so it is a good idea to check for it and use its value.

If for some reason a feed does not have an element in the switch block, the property representing the element defaults to a blank XParserElement object (from the first line of the XParserItem class). Because XParser is a JavaScript class, not every element needs to be parsed. However, the use of switch easily allows for the addition of other elements, if needed.

The XParser class is the main class that encompasses all the previous classes discussed. Its constructor accepts an argument sFileName and an optional argument called bIsXml. For maximum flexibility, XParser is designed either to make its own XMLHttp requests or to have the responseText of an external request passed to the constructor. If bIsXml is false or undefined, then sFileName is treated as a URL and XParser will make its own request; otherwise, sFileName is treated as an XML string and will be loaded into an XML DOM object.

var oThis = this;
this.title=this.link=this.description=this.copyright=this.generator= this.modified=
    this.author = new XParserElement();
this.onload = null;

It may seem strange to assign a variable to contain the object's reference, but this technique comes in handy when dealing with the onreadystatechange() event handler of an XMLHttp object, which will be seen later. The next line of code is similar in idea and function to the first line in XParserItem. It sets the object's properties that represent important elements with a default value. The following line declares onload, an event handler, which fires when the feed is completely loaded.

XParser's load() method is called when the XML data is retrieved. When XML is passed to the constructor, the load() method is immediately called and the XML data contained in sFileName is passed to the method.

if (bIsXml) {
    this.load(sFileName);
}

However, when a URL is passed to the constructor (and bIsXml is false or undefined), XParser makes its own request.

else {
    var oReq = zXmlHttp.createRequest();
    oReq.onreadystatechange = function () {
        if (oReq.readyState == 4) {
            //only if "OK"
            if (oReq.status == 200) {
                oThis.load(oReq.responseText);
            }
        }
    };
    oReq.open("GET", sFileName, true);
    oReq.send(null);
}

Note that this code uses the zXmlHttp cross-browser factory introduced earlier in the book using the onreadystatechange() event, the status of the request is checked and the responseText is passed to the load() method when the request is successful. This is where the oThis variable comes into play. Had this.load(oReq.responseText) been used, an error would have been thrown stating this.load() is not a function. This particular error is thrown because while inside the onreadystate change event handler, the this keyword references the event handler, not the XParser object.

Finally, the request is sent via the send() method.

The load() method is called only when XML data is ready to parse. It takes one argument, sXml, which is the XML data to parse.

XParser.prototype.load = function (sXml) {
    var oXmlDom = zXmlDom.createDocument();
    oXmlDom.loadXML(sXml);

In this code, the XML data is loaded into an XMLDOM object created from the cross-browser XML DOM factory discussed in Chapter 4. Now that the DOM is ready to go, the parsing can begin.

this.root = oXmlDom.documentElement;

The first step is to parse the simple properties of the file. Using the root property, which references the XML document element, it's possible to determine what type of feed is being parsed.

this.isRss = (this.root.tagName.toLowerCase() == "rss");
if (this.isRss && parseInt(this.root.getAttribute("version")) < 2) {
    throw new Error("RSS version is less than 2");
}
this.isAtom = (this.root.tagName.toLowerCase() == "feed");
this.type = (this.isRss)?" RSS":" Atom";

To find out what type of feed it is, the document's root element is checked. If the tag name is rss, then a version of RSS is being used. If the document's root element is feed, then it is an Atom feed. The Boolean properties isRss and isAtom are assigned their values according to the feed type. Last, the type property is set to reflect the feed type. This particular property is displayed to the user.

Both RSS and Atom have elements that contain information about the feed itself, but they are located in different parts of the document. In RSS, this information is contained in a <channel /> element that encloses all other elements in the feed. Atom, on the other hand, uses its root element to enclose the information. This similarity can be used to parse the feed easily:

var oChannel = (this.isRss)?this.root.getElementsByTagName("channel")[0]:this.root;

If the feed is RSS, the oChannel variable is set to the <channel/> element; otherwise, it's set to the document element of the feed. After this common starting point, parsing the non-items can begin:

for (var i = 0; i < oChannel.childNodes.length; i++) {
    var oNode = oChannel.childNodes[i];
    if (oNode.nodeType == 1) {

A for loop is used to loop through the children of the channel. Once again, the nodeType property of the current node is checked. If confirmed to be an element, parsing continues. Just like XParserItem, a switch block is used.

switch (oNode.tagName.toLowerCase()) {
    //Shared Tags
    case "title":
        this.title = new XParserElement(oNode);
    break;
    case "link":
        if (this.isAtom) {
            if (oNode.getAttribute("href")) {
                this.link = new XParserElement(oNode,oNode.getAttribute("href"));
            }
        } else {
           this.link = new XParserElement(oNode);
        }
    break;
    case "copyright":
        this.copyright = new XParserElement(oNode);
    break;
    case "generator":
        this.generator = new XParserElement(oNode);
    break;

RSS and Atom have quite a few elements in this part of their specifications that are similar, and this makes life easier (and keeps the amount of code down). The main difference in these few elements is the <link/> element (just like in XParserItem). Atom feeds contain a <link/> element, but the value you want to use is an attribute. Using the getAttribute() method, the href attribute's value is retrieved and is included in the XParserElement constructor. Next are the RSS-specific elements.

//RSS Tags
case "description":
    this.description = new XParserElement(oNode);
break;
case "lastbuilddate":
    this.modified = new XParserElement(oNode);
break;

case "managingeditor":
    this.author = new XParserElement(oNode);
break;

And then the Atom-specific elements.

//Atom Tags
case "tagline":
    this.description = new XParserElement(oNode);
break;
case "modified":
    this.modified = new XParserElement(oNode);
break;
case "author":
    this.author = new XParserElement(oNode);
break;
default:
break;

The feed's informational elements are parsed, and then it is time to create and populate the items array. As the name implies, the items array is a collection is of XParserItem objects. The <rss:item/> and <atom:entry/> elements will be looped through and sent to the XParserItem constructor:

var oItems = null;
if (this.isRss) {
    oItems = oChannel.getElementsByTagName("item");
} else {
    try {
        oXmlDom.setProperty('SelectionLanguage', 'XPath');
        oXmlDom.setProperty("SelectionNamespaces",
            "xmlns:atom='http://www.w3.org/2005/Atom'");
        oItems = oXmlDom.selectNodes("/atom:feed/atom:entry");
    } catch (oError) {
        oItems = oChannel.getElementsByTagName("entry");
    }
}

Since the Microsoft XML DOM version 4, the getElementsByTagName() method has changed some what. In version 3 and below, qualified names were ignored when using getElementsByTagName(), so retrieving any element was as simple as passing the tag name to the method.

In version 4 and later, however, selecting an element with a default namespace requires the use of the selectNodes() method, which takes an XPath expression. The setProperty() method, which sets additional properties for the XML DOM parser, is used to set the namespace in order make selections with selectNode() possible. In the previous example, a try…catch block is used to discern which method should be used. The newer selectNodes() method is tried; if it fails, then getElementsByTagName() is used to retrieve the elements.

After the retrieval of the <rss:item/> and <atom:entry/> elements, each individual node is passed to the XParserItem class constructor to create the items array:

for (var i = 0; i < oItems.length; i++) {
    this.items[i] = new XParserItem(oItems[i]);
}

At this point, all of the important elements are parsed and contained in their corresponding properties. The only thing left to do is fire the onload event:

if (typeof this.onload == "function") {
    this.onload();
}

When onload was first declared, it was assigned the value of null. Because of this, it is important to check the onload type. If it is a function (meaning that the event now has a handler), then the onload() method is called. Use of this event will be seen later in the chapter.

The User Experience

The user interface may be the most important part of any application; if the user cannot use the application, there is no reason for the application to exist. FooReader.NET was designed to be easily used and understood by the user. In fact, it borrows heavily from the Microsoft Outlook 2003 user interface. It has a threepane interface where the first two panes are a fixed width while the third pane is fluid (see Figure 5-1).

Figure 5-1

The first pane, called the feeds pane, displays the different feeds as links that the user can click on. A <div/> element with an id of divFeedList in the feeds pane allows the feeds list to be written to the document. Because this pane is populated dynamically, only the containing elements are statically written:

<div id=" divFeedsPane">
    <div class=" paneheader">Feeds</div>
    <div id=" divFeedList"></div>
</div>

When the user clicks on a feed, the feed items are loaded into the middle pane: the items pane. This second pane has two elements that are used to display information. The first is a <div/> element with an id of divViewingItem. This element displays two things to the user: which feed they are currently reading and the feed document type (RSS or Atom). The second element is another <div/> element whose id attribute is set to divItemList. This element will contain a list of <item/> RSS elements or <entry/> Atom elements. Like the feeds pane, only the containing elements are statically written to the page:

<div id=" divItemPane">
    <div class=" paneheader">Items</div>
    <div id=" divViewingItem"></div>
    <div id=" divItemList"></div>
</div>

If the user single-clicks an item, it loads the item into the last pane: the reading pane. This pane has three elements that display the item's information. The first, whose id is divMessageTitle, is where the <title/> element of RSS and Atom feeds is displayed. The second element has an id of aMessageLink whose href attribute is changed dynamically. Finally, the last element is divMessageBody, where the <rss:description/> and <atom:content/> elements are displayed:

<div id=" divReadingPane">
    <div class=" contentcontainer">
        <div class=" messageheader">
            <div id=" divMessageTitle"></div>
            <a href="" id=" aMessageLink" title=" Click to goto posting."
                 target="_new">Travel to Post</a>
        </div>
        <div id=" divMessageBody"></div>
    </div>
</div>