first version

dylang · Apr 18, 2011 · b646280 · b646280
commit b646280
Show file tree

Hide file tree

Showing 7 changed files with 312 additions and 0 deletions.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2011 Dylan Greene <dylang@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/index.js b/index.js
@@ -0,0 +1 @@
+module.exports = require('./lib/atom.js');
diff --git a/lib/atom.js b/lib/atom.js
@@ -0,0 +1,80 @@
+/*
+ Documentation coming soon.
+*/
+
+var XML        = require('xml'),
+    log        = require('logging').from(__filename);
+
+function ATOM (options, items) {
+    options = options || {};
+
+    this.title          = options.title || 'Untitled ATOM Feed';
+    this.description    = options.description || '';
+    this.feed_url       = options.feed_url;
+    this.site_url       = options.site_url;
+    this.image_url      = options.image_url;
+    this.author         = options.author;
+    this.items          = items || [];
+
+    this.item = function (options) {
+        options = options || {};
+        var item = {
+            title:          options.title || 'No title',
+            description:    options.description || '',
+            url:            options.url,
+            guid:           options.guid,
+            categories:     options.categories || [],
+            author:         options.author,
+            date:           options.date
+        };
+
+        this.items.push(item);
+        return this;
+    };
+
+    this.xml = function(indent) {
+        return '<?xml version="1.0" encoding="UTF-8"?>\n'
+                + XML(generateXML(this), indent);
+    }
+
+}
+
+function ifTruePush(bool, array, data) {
+    if (bool) {
+        array.push(data);
+    }
+}
+
+function generateXML (data){
+
+    var feed =  [
+            { _attr: {
+                'xmlns':         'http://www.w3.org/2005/Atom',
+                'xml:lang':      'en-US'
+            } },
+            { id:           'tag:' + '*domain*' + 'something...' },
+            { link:         { _attr: { type: 'text/html', rel: 'alternate', href: data.site_url } } },
+            { link:         { _attr: { type: 'application/atom+xml', rel: 'self', href: data.feed_url } } },
+            { title:        data.title },
+            { updated: new Date().toISOString() }
+        ];
+
+     data.items.forEach(function(item) {
+        var entry = [
+                    { id:        'tag:...' }
+                ];
+        ifTruePush(item.date,    entry, { published:    new Date(item.date).toISOString() });
+        ifTruePush(item.updated, entry, { updated:      new Date(item.updated).toISOString() });
+        ifTruePush(item.link,    entry, { link:         { _attr: { type: 'text/html', rel: 'alternate', href: item.url } } });
+        ifTruePush(item.title,   entry, { title:        item.title });
+        ifTruePush(item.description, entry, { content:  { _attr: { type: 'xhtml', 'xml:lang': 'en' }, _cdata: item.description } });
+        //ifTruePush(item.author || data.author, entry, { 'dc:creator': { _cdata: item.author || data.author } });
+        feed.push({ entry: entry });
+    });
+
+    return { feed: feed };
+}
+
+
+
+module.exports = ATOM;
diff --git a/lib/util.js b/lib/util.js
diff --git a/package.json b/package.json
@@ -0,0 +1,31 @@
+{
+    "name": "atom",
+    "version": "0.0.1",
+    "description": "ATOM feed generator. A really simple API to add an ATOM feed to any project.",
+    "homepage": "http://github.com/dylang/node-atom",
+    "author": "Dylan Greene <dylang@gmail.com>",
+    "contributors": [
+        "Dylan Greene <dylang@gmail.com>"
+    ],
+    "repository":
+    {
+        "type": "git",
+        "url": "http://github.com/dylang/node-atom"
+    },
+    "bugs":
+    {
+        "mail": "dylang@gmail.com",
+        "web": "http://github.com/dylang/node-atom/issues"
+    },
+    "dependencies":
+    {
+        "xml": ">= 0.0.4",
+        "logging": ">= 2.0.0"
+    },
+    "main": "index.js",
+    "engines": { "node": ">=0.4.0" },
+    "licenses" :
+    [
+        { "type" : "MIT", "url" : "http://github.com/dylang/node-atom/raw/master/LICENSE" }
+    ]
+}
diff --git a/readme.md b/readme.md
@@ -0,0 +1,118 @@
+# RSS for Node
+
+  Fast and simple Javascript-based ATOM generator/builder for Node projects.
+
+## Install
+
+    $ npm install atom
+
+## Tests
+
+ Use [nodeunit](https://github.com/caolan/nodeunit) to run the tests.
+
+    $ npm install nodeunit
+    $ nodeunit test
+
+## Usage
+
+    var ATOM = require('atom');
+
+    /* lets create an atom feed */
+    var feed = new ATOM({
+            title: 'title',
+            description: 'description',
+            feed_url: 'http://example.com/rss.xml',
+            site_url: 'http://example.com',
+            image_url: 'http://example.com/icon.png',
+            author: 'Dylan Greene'
+        });
+
+    /* loop over data and add to feed */
+    feed.item({
+        title:  'item title',
+        description: 'use this for the content. It can include html.',
+        url: 'http://example.com/article4?this&that', // link to the item
+        guid: '1123', // optional - defaults to url
+        author: 'Guest Author', // optional - defaults to feed author property
+        date: 'May 27, 2012' // any format that js Date can parse.
+    });
+
+    // cache the xml
+    var xml = feed.xml();
+
+### Feed Options
+
+ * _title_ <string> Title of your site or feed
+ * _description_ <string> Optional. Short description of the feed.
+ * _feed_url_ <url> Url to the rss feed.
+ * _site_url_ <url> Url to the site that the feed is for.
+ * _image_url_ <url> Optional. Small image for feed readers to use.
+ * _author_ <string> Who owns this feed.
+
+### Item Options
+
+In RSS an item can be used for a blog entry, project update, log entry, etc.  Your rss feed
+an have any number of items. Ten to tenty is usually good.
+
+ * _title_ <string> Title of this particular item.
+ * _description_ <string> Content for the item.  Can contain html but link and image urls must include the server name.
+ (Note: I might change this to content in the next release.)
+ * _url_ <url> Url to the item. This could be a blog entry.
+ * _guid_ <unique string> A unique string feed readers use to know if an item is new or has already been seen.
+ If you use a guid never change it.  If you don't provide a guid then your item urls must
+ be unique.
+ * _author_ <string> Optional.  If included it is the name of the item's creator.
+ If not provided the item author will be the same as the feed author.  This is typical
+ except on multi-author blogs.
+ * _date_ <Date object or date string> The date and time of when the intem was created.  Feed
+ readers use this to determin the sort order. Some readers will also use it to determin
+ if the content should be presented as unread.
+
+### Methods
+
+ * _item(item_options)_ - add an rss item, article, entry etc.
+ * _xml([indent])_ - return the xml.  If you pass in true it will use four spaces for indenting. If you prefer
+ tabs use \t instead of true.
+
+## Notes
+ * You do not need to escape anything. This module will escape characters when necessary.
+ * This module is very fast but you might as well cache the output of xml() and serve
+ it until something changes.
+
+## Upcoming features
+
+ * Feed validation
+ * Feedburner integration
+ * More customization
+ * Express middleware for serving feeds
+ * What else?
+
+# Contributing
+
+Contributions to the project are welcome. Feel free to fork and improve. I accept pull requests and issues,
+especially when tests are included.
+
+# License
+
+(The MIT License)
+
+Copyright (c) 2011 Dylan Greene <dylang@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/test/test.js b/test/test.js
@@ -0,0 +1,60 @@
+/*
+    use nodeunit to run tests.
+*/
+
+var ATOM = require('../index');
+
+
+module.exports = {
+
+    'empty feed': function(test) {
+        var feed = new ATOM();
+        //test.equal(feed.xml(), '<?xml version="1.0" encoding="UTF-8"?>\n<rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Untitled RSS Feed]]></title><description><![CDATA[Untitled RSS Feed]]></description><link>http://github.com/dylan/node-rss</link><generator>NodeJS RSS Module</generator><lastBuildDate>' + new Date().toUTCString() +'</lastBuildDate></channel></rss>');
+        feed.item();
+        //test.equal(feed.xml(), '<?xml version="1.0" encoding="UTF-8"?>\n<rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Untitled RSS Feed]]></title><description><![CDATA[Untitled RSS Feed]]></description><link>http://github.com/dylan/node-rss</link><generator>NodeJS RSS Module</generator><lastBuildDate>' + new Date().toUTCString() +'</lastBuildDate><item><title><![CDATA[No title]]></title><guid isPermaLink="false">No title</guid></item></channel></rss>');
+        test.done();
+    },
+
+    'easy test': function(test) {
+        var feed = new ATOM({
+                    title: 'title',
+                    description: 'description',
+                    feed_url: 'http://example.com/rss.xml',
+                    site_url: 'http://example.com',
+                    image_url: 'http://example.com/icon.png',
+                    author: 'Dylan Greene'
+                });
+
+        feed.item({
+                    title:  'item 1',
+                    description: 'description 1',
+                    url: 'http://example.com/article1',
+                    date: 'May 24, 2012'
+                })
+            .item({
+                    title:  'item 2',
+                    description: 'description 2',
+                    url: 'http://example.com/article2',
+                    date: 'May 25, 2012'
+                })
+            .item({
+                    title:  'item 3',
+                    description: 'description 3',
+                    url: 'http://example.com/article3',
+                    guid: 'item3',
+                    date: 'May 26, 2012'
+                })
+            .item({
+                    title:  'item 4 & html test with <strong>',
+                    description: 'description 4 uses some <strong>html</strong>',
+                    url: 'http://example.com/article4?this&that',
+                    author: 'Guest Author',
+                    date: 'May 27, 2012'
+                });
+
+        console.log(feed.xml(true));
+        //test.equal(feed.xml(), '<?xml version="1.0" encoding="UTF-8"?>\n<rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[title]]></title><description><![CDATA[description]]></description><link>http://example.com</link><generator>NodeJS RSS Module</generator><lastBuildDate>' + new Date().toUTCString() +'</lastBuildDate><atom:link href="http://example.com/rss.xml" rel="self" type="application/rss+xml"/><item><title><![CDATA[item 1]]></title><description><![CDATA[description 1]]></description><guid isPermaLink="true">http://example.com/article1</guid><dc:creator><![CDATA[Dylan Greene]]></dc:creator><pubDate>Thu, 24 May 2012 04:00:00 GMT</pubDate></item><item><title><![CDATA[item 2]]></title><description><![CDATA[description 2]]></description><guid isPermaLink="true">http://example.com/article2</guid><dc:creator><![CDATA[Dylan Greene]]></dc:creator><pubDate>Fri, 25 May 2012 04:00:00 GMT</pubDate></item><item><title><![CDATA[item 3]]></title><description><![CDATA[description 3]]></description><guid isPermaLink="false">item3</guid><dc:creator><![CDATA[Dylan Greene]]></dc:creator><pubDate>Sat, 26 May 2012 04:00:00 GMT</pubDate></item><item><title><![CDATA[item 4 & html test with <strong>]]></title><description><![CDATA[description 4 uses some <strong>html</strong>]]></description><guid isPermaLink="true">http://example.com/article4?this&amp;that</guid><dc:creator><![CDATA[Guest Author]]></dc:creator><pubDate>Sun, 27 May 2012 04:00:00 GMT</pubDate></item></channel></rss>');
+        test.done();
+    }
+};
+