All Topics

#2250 [ANN] Atom v1.0.0 Released!

SlimerDude Mon 31 Mar 2014

Atom v1.0.0 Released!

Atom is a library for creating Atom (RSS) Feed Documents.

The Atom Syndication Format, or Atom for short, is the technically advanced successor to RSS v2.0. This Atom library provides a collection of entities that let you compose an Atom Feed Document and serialise it to XML.

Atom is an implementation of the The Atom Syndication Format. See atomenabled.org for a more human readable version.

Alien-Factory: http://www.alienfactory.co.uk/pods/afAtom
Install: fanr install -r http://repo.status302.com/fanr/ afAtom
API & Docs: http://repo.status302.com/doc/afAtom/#overview
Source: https://bitbucket.org/AlienFactory/afatom

Quick Start

1). Create a text file called Example.fan:

using afAtom

class Example {
    Void main() {

        // create a feed...
        feed := Feed(`example:feed`, Text("Fantom Feed"), DateTime.now)
        feed.links.add(Link(`http://www.fantomfactory.org/`, "alternate") {
            it.title = "Fantom-Factory"
            it.type  = MimeType("application/xhtml+xml")
        })

        // add entries...
        text  := "<p>Visit the <b>Atom</b> homepage to find out moar!</p>"
        entry := Entry(`example:afAtom:`, Text("Atom Released!"), DateTime.now)
        entry.content = Content(text, TextType.html)
        feed.entries.add(entry)

        // convert to XML...
        atomXml := feed.toXml.writeToStr
        echo(atomXml)
    }
}

2). Run Example.fan as a Fantom script from the command line:

C:\> fan Example.fan

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'>
 <id>example:feed</id>
 <title type='text'>Fantom Feed</title>
 <updated>2014-03-31T17:50:52.786+01:00</updated>
 <link href='http://www.fantomfactory.org/' rel='alternate' type='application/xhtml+xml' title='Fantom-Factory'/>
 <entry>
  <id>example:afAtom:</id>
  <title type='text'>Atom Released!</title>
  <updated>2014-03-31T17:50:52.786+01:00</updated>
  <content type='html'>&lt;p>Visit the &lt;b>Atom&lt;/b> homepage to find out moar!&lt;/p></content>
 </entry>
</feed>

BedSheet Integration

To serve an Atom feed with BedSheet first add a Route to your AppModule that configures the feed URI and the request handler:

using afIoc
using afBedSheet

class AppModule {

    @Contribute { serviceType=Routes# }
    static Void contributeRoutes(OrderedConfig config) {
        config.add(Route(`/feeds/atom.xml`, AtomFeed#generate))
    }
}

Then create the request handler that generates the Atom feed:

using afAtom
using afBedSheet::Text as BsText

class AtomFeedGenerator {
    BsText generate() {
        feed := Feed(`example:feed`, Text("Example Feed"), DateTime.now)

        // add feed metadata and entries...
        feed.entries.add(Entry(`example:entry:`, Text("Example Entry"), DateTime.now))

        // serialise to XML and return as a BedSheet Text response object
        return BsText.fromMimeType(feed.toXml.writeToStr, MimeType("application/atom+xml"))
    }
}

Note that Atom feeds should be served with the application/atom+xml mime type.

Auto-Discovery

Some browsers, such as Firefox, automatically know when a site has an Atom or RSS feed and contain features to easily let you subscribe. To enable this, you need to add a bit of HTML to your web page:

<html>
<head>
    ...
    <link rel="alternate" type="application/atom+xml" title="Feed Title" href="/feeds/atom.xml">
    ...

If you have multiple feeds, then you may have multiple link elements.

Note that in HTML the link element is a Void Element and has no closing tag.

This old article in the WHATWG Blog on Feed Autodiscovery talks of a new standard where feed is used for the link rel attribute. But its absence in the HTML5 specification on Link types suggests it never took off. Also Section 4.8.4.1 Link type "alternate" specifically says alternate should be used for Atom and RSS feeds.

Have fun!

: )

SlimerDude Thu 3 Apr 2014

Hi,

Just thought I'd mention that with the advent of Atom, I've added an Atom Feed to the Fantom-Factory site. It's handy if you want to be notified of library updates and new articles.

Speaking of which, there's also a new tutorial on Basic HTTP Authentication With BedSheet which also shows how to make your own configurable IoC service.

Laters!