The Atom library provides a base set of functionality for using Atom feeds. It provides a data model to handle accessing the various elements of Atom feeds and entries, as well as a transport object to handle the various interactions with Web servers as for both handling standard Atom feeds and the Atom Publishing Protocol (APP).
For more information, read about the Atom Syndication Specification. For more information, read about the Atom Publishing Protocol.
Retrieving a feed is simple. With all server interactions from the client, an AtomIO object is created. This is the transport object referred to above, which handles any interaction with the Atom server. We will start with a simple task, such as retrieving a feed.
The feed used is the same as on the widget usage example page. It is available here. The contents of this feed are shown below for reference.
<?xml version='1.0' encoding='utf-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xml:lang='en-US'> <title>Example.com</title> <link rel="alternate" type="text/html" href="http://example.com/" hreflang="en" title="Example.com" /> <subtitle type='text'>Example.com's Sample Feed</subtitle> <rights>Copyright Example.com</rights> <id>http://example.com/samplefeed.xml</id> <updated>2007-08-07T20:00:00-05:00</updated> <link rel="self" type="application/atom+xml" href="http://www.example.com/samplefeed.xml"/> <entry> <title>Test Entry #1</title> <id>http://example.com/samplefeed.xml/entry/1</id> <link rel='alternate' href='http://example.com/1.html'/> <summary type='html'> <p>This is a sample entry in our Atom feed. It is simply a large paragraph in the summary.<p> <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras cursus. Aliquam eget metus sed leo lacinia rutrum. Nunc lacus lacus, viverra placerat, laoreet nec, placerat vel, eros. Donec nec magna id sem commodo rutrum. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos. Aenean pede. Quisque vel leo. In vitae nisi. Curabitur sodales congue nibh. Maecenas ultrices ante nec ipsum. Aenean quis nibh. Aenean semper, quam vitae ullamcorper euismod, arcu leo tincidunt nunc, vel pulvinar turpis dolor a elit. Praesent nonummy nunc faucibus nibh. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Vivamus laoreet, ante auctor condimentum venenatis, magna quam varius elit, at feugiat dolor metus id quam. Etiam enim.<p> </summary> <author> <name>Test User</name> <email>test@example.com</email> </author> <updated>2007-08-07T04:00:00-05:00</updated> </entry> <entry> <title>Test Entry #2</title> <id>http://example.com/samplefeed.xml/entry/2</id> <link rel='alternate' href='http://example.com/2.html'/> <summary type='text'> This is a sample entry in our Atom feed. It is simply a large paragraph in the summary. This is straight text. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras cursus. Aliquam eget metus sed leo lacinia rutrum. Nunc lacus lacus, viverra placerat, laoreet nec, placerat vel, eros. Donec nec magna id sem commodo rutrum. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos. Aenean pede. Quisque vel leo. In vitae nisi. Curabitur sodales congue nibh. Maecenas ultrices ante nec ipsum. Aenean quis nibh. Aenean semper, quam vitae ullamcorper euismod, arcu leo tincidunt nunc, vel pulvinar turpis dolor a elit. Praesent nonummy nunc faucibus nibh. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Vivamus laoreet, ante auctor condimentum venenatis, magna quam varius elit, at feugiat dolor metus id quam. Etiam enim. </summary> <author> <email>test@example.com</email> </author> <updated>2007-08-07T06:00:00-05:00</updated> </entry> </feed>
Now, to create a feed object from this feed, use the following code:
var _feed = null; var atomIO = new ibm_atom.io.atom.AtomIO(); function getComplete(feed, domNode){ _feed = feed; } atomIO.getFeed("samplefeed.xml", getComplete);
This block of code first defines a _feed variable, creates an AtomIO object, defines a function to be used as a callback, and then finally calls the getFeed function on the AtomIO object to fetch the feed. In the previous code block, the string "samplefeed.xml" is the URL to the feed.
With a feed object, you can fetch any of the attributes of the feed (such as the title, the ID, authors, contributors, updated date, and so on). Additionally, the entries beneath the feed can be fetched, either as an array of entries, or individually by ID.
function getComplete(/* Atom Feed Object */ feed, /* DOM Node Object */ domNode){ _feed = feed; var id = _feed.id; // id now equals "http://www.onlamp.com/" var title = _feed.title.value; // _feed.title is a ibm_atom.io.atom.Content object, with a // value of "Example.com" var arrayOfEntries = _feed.entries; // an array of all entries. Current length is 3. var specificEntry = _feed.getEntry("http://example.com/samplefeed.xml/entry/2"); // the entry specified by the given ID string. In this case, // it is the first entry in our feed. }
With an individual Entry object, you can do many similar items as on a feed object, including getting the entry title, id, updated date, and so on. The only unique function on an entry object is the ability to get the edit URL for that entry. This ability is not shown in this example, as the previous sample feed does not include any editable entries.
function getComplete(feed, domNode){ _feed = feed; var specificEntry = _feed.getEntry("http://example.com/samplefeed.xml/entry/2"); var id = specificEntry.id; // the id of the entry. var title = specificEntry.title.value; // the entry's title is an ibm_atom.io.atom.Content object, // the text value is in the 'value' attribute of that object. var updated = specificEntry.updated; // the entry's updated Date object. }
The other data model object's, such as authors and contributors, links, and so on, all operate similarly and have their own attributes and functions. For more information, check out the reference page.
The AtomIO object supports other functions to send data back to the server, including getting a single entry by using the getEntry function. This is typically to parse an Atom entry document, but if presented with a feed document, returns the first entry of that feed.
var _entry = null; var atomIO = new ibm_atom.io.atom.AtomIO(); function getComplete(/* Atom Entry Object */ entry, /* DOM Node Object */ domNode){ _entry = entry; var id = _entry.id; // the id of the entry. var title = _entry.title.value; // the entry's title is an ibm_atom.io.atom.Content object, // the text value is in the 'value' attribute of that object. var updated = _entry.updated; // the entry's updated Date object. } atomIO.getEntry("samplefeed.xml", getComplete);
Additionally, you can use the AtomIO object to send updated entries back to the server, with the URL being fetched from the edited entry. See the following example:
var _entry = null; var atomIO = new ibm_atom.io.atom.AtomIO(); function getComplete(/* Atom Entry Object */ entry, /* DOM Node Object */ domNode){ _entry = entry; _entry.addLink("editURL", "edit"); _entry.title.value = "Test Title!"; function getComplete2(entry2, domNode){} atomIO.updateEntry(_entry, getComplete2); } atomIO.getEntry("samplefeedEdit.xml", getComplete);
The previous code does not work as is, as the 'editURL' must be changed to a valid URL, and an APP server is needed to respond to the request.
Other available functions exist on the AtomIO object; however, most follow the same pattern as the getFeed, getEntry, and updateEntry functions above. See details on the reference page.