AtomUser Guide

Fandoc ERRORS:
Line 118 - Invalid annotation []

Overview [#overview]
********************
*'Atom' is a support library that aids Alien-Factory in the development of libraries, frameworks and applications.
Though you are welcome to use it, you may find features are missing and the documentation incomplete.*

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

The [Atom Syndication Format]`http://tools.ietf.org/html/rfc4287`, or Atom for short, is the technically advanced successor to [RSS v2.0]`http://www.rssboard.org/rss-specification`.
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]`http://tools.ietf.org/html/rfc4287`.
See [atomenabled.org]`http://atomenabled.org/developers/syndication` for a more human readable version.



Install [#Install]
******************
Install 'Atom' with the Fantom Repository Manager ( [fanr]`http://fantom.org/doc/docFanr/Tool.html#install` ):

  $ fanr install -r http://repo.status302.com/fanr/ afAtom

To use in a [Fantom]`http://fantom.org/` project, add a dependency to 'build.fan':

  depends = ["sys 1.0", ..., "afAtom 0+"]



Quick Start [#quickStart]
*************************
1). Create a text file called 'Example.fan':
pre>
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)
    }
}
<pre

2). Run 'Example.fan' as a Fantom script from the command line:
pre>
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>
<pre



BedSheet Integration [#bedSheet]
********************************
To serve an Atom feed with [BedSheet]`http://www.fantomfactory.org/pods/afBedSheet` first add a 'Route' to your 'AppModule' that configures the feed URI and the request handler:

pre>
using afIoc
using afBedSheet

class AppModule {

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

Then create the request handler that generates the Atom feed:

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

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



Auto-Discovery [autoDiscovery]
******************************
Some browsers, such as [Firefox]`http://toodifficult.com/keeping-up-with-news-using-rss/`, 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:

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

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

Note that in HTML the 'link' element is a [Void Element]`http://www.w3.org/TR/html-markup/syntax.html#void-element` and has no closing tag.

This old article in the WHATWG Blog on [Feed Autodiscovery]`http://blog.whatwg.org/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]`http://www.w3.org/TR/html5/links.html#linkTypes` suggests it never took off.
Also [Section 4.8.4.1 Link type "alternate"]`http://www.w3.org/TR/html5/links.html#rel-alternate` specifically says 'alternate' should be used for Atom and RSS feeds.



Release Notes [#releaseNotes]
*****************************

v1.0.0 [#v1.0.0]
----------------
 - New: Initial release.