by Prateek Rungta

We all have a list of links (blogroll) on our blogs, mostly pointing to other blogs. My friend Karan Misra decided to make his blogroll a bit more interesting on his (excellent) blog by arranging the links in the order by which they were last updated. I dug the idea and decided to implement it on my blog as well. Halfway through I realised a lot of people may like to do the same with their blogrolls so I created LinkedList.

WordPress users check out LinkedList.wp, a WordPress plugin.

Overview

LinkedList is a small JavaScript plugin for displaying a list of links to websites in the order by which they were last updated. Typically, you would use it on your blog to provide links to other blogs/websites, your blogroll in other words.

LinkedList is free software and has been released under the GPLv3 license.

Example

Nothing explains better than an example – links to a few of my favourite websites.

Some other places where you can see the LinkedList script at work – Souvik's blog, Varenya's blog and my photoblog.

Usage

LinkedList uses Google’s excellent AJAX Feed API to read the RSS/Atom feeds of the websites you want to link to and then arranges the list with the most recently updated website on the top.

The Deep Breath

You’ll need a valid Google AJAX Feed API Key for the website where you wish to display the links. Sign up for one if you haven't got it already (don't worry there aren't any forms to fill).

Download the LinkedList.js script. If you have access to a web server, upload the file there.

The Pieces

Place the following bit of code in the <head> tag of the page you wish to display the links on.

If you have uploaded the linkedlist.js file to a web server then paste:

<script src="http://www.google.com/jsapi?key=YOUR_KEY" type="text/javascript"></script>
<script src="PATH_TO_LINKEDLIST.JS" type="text/javascript" charset="utf-8"></script>

Replace YOUR_KEY with the API key your acquired earlier and replace PATH_TO_LINKEDLIST.JS with the path to the linkedlist.js file you uploaded earlier.

If you haven't uploaded the file to a web server, paste the following instead:

<script src="http://www.google.com/jsapi?key=YOUR_KEY" type="text/javascript"></script>	
<script type="text/javascript" charset="utf-8">
	CONTENTS_OF_LINKEDLIST.JS
</script>

Replace YOUR_KEY with the API key your acquired earlier and copy and paste the entire contents of the linkedlist.js file in the second script tag.

Finally, place this tag in the <body> of your page—wherever you want the links to be displayed (your sidebar for example).

<div id="livelinks"></div>
The Plunge

Back to the <head> tag of the page. Paste the following AFTER the code that you just added.

<script type="text/javascript" charset="utf-8">
	google.load("feeds", "1");

	var links = new LinkedList('livelinks', 0); //number of entries per link = 0
	
	// links.add("AN_RSS_OR_ATOM_FEED", "OPTIONAL_TITLE"); for example
	links.add("http://feeds.feedburner.com/Flickrblog", "Flickr Blog");
	links.add("http://www.digg.com/rss/index.xml");
	
	// links.add("A_NORMAL_WEBPAGE", "TITLE", false); for example
	links.add("http://www.google.com", "Google", false);
	links.add("http://prateekrungta.com/linkedlist", "LinkedList Script", false);
	
	google.setOnLoadCallback(function() {
		links.display();
	});	
</script>

Add as many links as you want!

Documentation

LinkedList.js is written using object-oriented programming concepts. It provides a LinkedList class, each instance of which is, as the name suggests, a list of links.

Constructor
LinkedList (String elementId [, int numberOfEntires [, bool fadeIn [, bool useCookies]]])

Creates a new LinkedList instance to which you can add links.

elementId required
– id of the DOM element inside which the list is displayed.

numberOfEntries optional (defaults to 1)
– sets the number of entry titles that are displayed from each of RSS/Atom feeds provided. If set to 0 (zero) each of the links will be suffixed with the date of the latest entry in its feed.

fadeIn optional (defaults to true)
– takes a boolean value of false to prevent the fade in animation when the list is displayed on the page.

useCookies optional (defaults to false)
– takes a boolean value of true to store auto–discovered feed urls for sites looked up by LinkedList.

Methods
add ( String url [, String title [, boolean isFeed]] )

Adds a new link to the LinkedList instance.

url required
– a valid URL. Can be a syndicated RSS/Atom feed or a regular web page.

title optional (defaults to the title supplied by the feed)
– sets the name of the link.

isFeed optional (defaults to true)
– indicates if the url is a syndicated feed. When set to false, LinkedList will attempt to auto–discover a feed associated with that web page, and if found, use that feed for sorting its link. However, it is recommended that feed URLs be specified whenever possible in order to decrease the number of Ajax requests made by LinkedList. (Feed discovery is made possible by the lookupFeed method in Google’s API)

display ( )

As the name suggests, draws the linked list in the element specified in the constructor earlier. Links for whom no feed was supplied are placed at the end of the list. Feeds for which the Google API returns an error are excluded from the list.

limitTo ( int n )

Displays only the last n updated links.

HTML Structure

The list drawn by the script is enclosed in semantic HTML markup. Should you want to use CSS to style the list, you can make use of the class names of the elements in the list to do the same. This is the basic skeleton of the list drawn by a LinkedList instance.

<ul class="ll-linksList">
    <li>
        <div>
            <a href="<!-- target url -->"><!-- link title --></a>
            <ul class="ll-entriesList">
                <li><!-- entry title --><span class="ll-entryDate"><!-- entry date --></span></li>
            </ul>
        </div>
    </li>
</ul>
Change Log

20th July '08 Version 1.2

  • Shows a status message while the feeds are loading
  • Shows relative time for feeds updated within the last 24 hours
  • Can specify max number of links to display by calling limitTo(number)
  • Reduced file size by using YUI Compressor

24th April '08 Version 1.1.4

  • Cookies are now optional, and turned off by default

2nd April '08 Version 1.1.3

  • Changed license to GPLv3

1st February '08 Version 1.1.2

  • Fixed a bug with error cases during feed auto-discovery

12th December '07 Version 1.1.1

  • Added the ability to recognize a feed’s lastBuildDate if individual item pubDates are missing

Feedback

Like it? Hate it? Want something more out of it? Spotted a bug? General feedback? Drop me an email—I'd love to hear about it!
Feeling generous? I like cash feedback just as much (ok, maybe a little more) ;).

Donate