SingleSub Documentation Page

Latest version can always be found at: http://singlesub.sf.net


What is this all about?

This project is another answer to the so called "Yahoo" problem originally mentioned by Dave Winer. What this project does is provide a list of subscribe URLs for common aggregators in three different formats (OPML, RSS 2.0 and RDF) AND provide three different services for blog publishers (hover-over subscribe button, chicklet generator and HTML subscribe page). Original blog post is here.

The main premise behind this project is that subscription information for aggregators can be stored in XML format and then used to generate different types of subscription utilities. I store this information in OPML format and then use XSLT templates to generate six different types of utilities. The beauty of this approach is that by changing the original XML file, all of the six utilities generated by this project are automatically updated. It is also hoped that other websites and utilities will use this service to auto-update their own tools.

Code, forums, news and more information can be found at our SourceForge project page.

List of services:
  1. OPML list of subscription URLs (for developers) - http://www.shaftek.org/code/singlesub/singlesub.pl?type=opml
  2. RSS 2.0 feed of subscription URLs (for developers) - http://www.shaftek.org/code/singlesub/singlesub.pl?type=rss2
  3. RDF list of subscription URLs (for developers) - http://www.shaftek.org/code/singlesub/singlesub.pl?type=rdf
  4. QuickSub javascript generator (for publishers) - http://www.shaftek.org/code/singlesub/singlesub.pl?type=quicksub
  5. Chicklet javascript generator* (for publishers) - http://www.shaftek.org/code/singlesub/singlesub.pl?type=chicklet&feed=http://sourceforge.net/export/rss2_projnews.php?group_id=151486
  6. HTML subscription page* (for publishers) - http://www.shaftek.org/code/singlesub/singlesub.pl?type=html&feed=http://sourceforge.net/export/rss2_projnews.php?group_id=151486
(* requires feed URL)

Services for Developers (hosted externally)

The main service provides for tool developers on this site is the list of subscription URLs, icon urls and aggregator names in XML format, all of which can be easily used to generate and update subscription tools. I provide this data in three different formats: OPML, RSS 2.0 and RDF. The formats are described below:

1. OPML format.

To access this service, use the following URL: http://www.shaftek.org/code/singlesub/singlesub.pl?type=opml. Different aggregators are sorted by categories (desktop, web-based and other). Aside from this web service, you can also access the latest version directly from CVS by clicking here. Within each outline OPML element, the following information is provided:

  • text - name of the aggregator or service (required)
  • htmlUrl - website for the aggregator or service (required)
  • type - always set to 'subscribe' (required)
  • subscribeUrl - URL used for subscribing [just append the feed url to the end] (required)
  • escaped - whether this service requires feed URLs to be escaped (required)
  • iconUrl - URL to a chicklet or button image (optional)

2. RSS 2.0 format.

To access this service, use the following URL: http://www.shaftek.org/code/singlesub/singlesub.pl?type=rss2. You can also optionally provide a URL to external OPML file in the format described above to be used for generating this list INSTEAD of the default file. This can be done by passing it as a "opml_url=" parameter. Within each item RSS 2.0 element, the following information is provided:

  • category - aggregator category [i.e. desktop, etc.] (required)
  • title - aggregator name (required)
  • description - whether this service requires feed URLs to be escaped (required)
  • source - URL for the aggregator website (required)
  • link - URL used for subscribing [just append the feed url to the end] (required)
  • enclosure - URL to a chicklet or button image (optional)

3. RDF format.

To access this service, use the following URL: http://www.shaftek.org/code/singlesub/singlesub.pl?type=rdf. The format used for each RDF element is defined by the Syndication Subscription Service (see that page for more information). You can also optionally provide a URL to external OPML file in the format described above to be used for generating this list INSTEAD of the default file. This can be done by passing it as a "opml_url=" parameter.


Services for Publishers (hosted externally)

4. QuickSub Javascript generator.

To access this service, use the following URL: http://www.shaftek.org/code/singlesub/singlesub.pl?type=quicksub. This is Jason Brome's QuickSub utility, however I modified it to automatically generate the subscribe URLs from the OPML list that I keep. Simply follow instructions at the QuickSub website BUT substitute the URL provided by me above in step #2 instead of Jason's. You can also optionally provide a URL to external OPML file in the format described above to be used for generating this list INSTEAD of the default file. This can be done by passing it as a "opml_url=" parameter. Here is a test feed:

Test Feed

5. Chicklet Javascript Generator.

To access this service, use the following URL: http://www.shaftek.org/code/singlesub/singlesub.pl?type=chicklet&feed=http://sourceforge.net/export/rss2_projnews.php?group_id=151486. This service is modeled after the one made by KB Cafe. The way it works is that it generates links to any aggregators that have the iconUrl includes in the OPML file defined above. You can also optionally provide a URL to external OPML file in the format described above to be used for generating this list INSTEAD of the default file. This can be done by passing it as a "opml_url=" parameter. To use it, includes the following in your HTML file:

<script src="http://www.shaftek.org/code/singlesub/singlesub.pl?type=chicklet&feed=http://sourceforge.net/export/rss2_projnews.php?group_id=151486" type="text/javascript" language="Javascript"></script>

A CSS class 'single_sub_chicklet' is used for generation and you can use that for styling. Here is a sample:

6. HTML Subscribe Page.

To access this service, use the following URL: http://www.shaftek.org/code/singlesub/singlesub.pl?type=html&feed=http://sourceforge.net/export/rss2_projnews.php?group_id=151486. This service is modeled after the Syndication Subscription Service, SoloSub and MultiRss. HOWEVER, the difference is that this HTML is automatically generated based on the data contained in the OPML file defined above. You can also optionally provide a URL to external OPML file in the format described above to be used for generating this list INSTEAD of the default file. This can be done by passing it as a "opml_url=" parameter. To use it, includes the following in your HTML file:

<a href="http://www.shaftek.org/code/singlesub/singlesub.pl?type=html&feed=http://sourceforge.net/export/rss2_projnews.php?group_id=151486" title="Subscribe to this Feed"><img src="http://singlesub.sf.net/includes/singlesub.gif" alt="subscribe to this feed" border="0" /></a>

OR the following in any HTML link:

http://www.shaftek.org/code/singlesub/singlesub.pl?type=html&feed=http://sourceforge.net/export/rss2_projnews.php?group_id=151486

Here is a sample: subscribe to this feed.

[Feel free to use my button (http://singlesub.sf.net/includes/singlesub.gif)]


Source Code and Contact Information

The source code can be downloaded the SourceForge project page. To use this code, you need Perl with XML and XSLT modules installed. Since a portion of this code used Jason Brome's QuickSub utility which is under the GPL, this entire project might GPL as well. Comments are welcome to code /at/ shaftek [dot] org or research \at\ solidmatrix /dot\ com.

A big "thank you" goes to Jason Brome, Mark Wilton-Jones, Morten Frederiksen, KB Cafe, Dave Winer, Pete Freitag, Url Trends, Mike Rowehl and many others.


Copyright (C) 2005 SolidMatrix Technologies, Inc. Licensed under the Apache 2.0 License.

Valid HTML 4.01 Transitional SourceForge.net Logo