New Revised CSS Library Forums Web Tools
FAQs Awards Usage Terms Contact
Categories
Other Sections
Sweet Ads
Compatibility
Bookmark online:

FF1+ IE5+ Opr8+

gAjax RSS Feeds Displayer v2.0 (hosted)

Author: Dynamic Drive

Sept 20th, 12': Version 2 release. Adds support for templating of entries' output, search and replace via regular expressions of any RSS field.

Description: This script is the fastest way to display RSS feeds from other sites on your own, period. It uses Google's Ajax Feed API to host the desired RSS feeds on Google's servers, so all that's left for you is to insert some code on your page to show them. Using gAjax RSS Feeds Displayer, you can display results from multiple feeds intermixed, sort them in a variety of ways, specify which fields of each RSS entry to display, and more. No more hurdles in your way to showing RSS feeds on your site!

Here's a summary of the features of this script:

  • Uses Google Ajax Feed API to host/cache the desired RSS feeds, so you don't have to install or host anything on your own server.
  • Specify multiple RSS feeds to display, with the results intermixed.
  • Sort the results either by "date", "title", or a custom "label" assigned to each feed (ie: "Digg" then "Slashdot").
  • Set the number of total RSS entries to show. If multiple feeds are specified, that number is spread out evenly amongst the feeds.
  • Specify which additional fields of each RSS entry to show, such as its "label", "date", "description", "snippet" and more.
  • Search and replace any text within each RSS entry using regular expressions to mold the output to your exact specifications. v2.0 feature
  • Customize the order of each field when they are output using the built in template feature. v2.0 feature
  • Ability to refresh the contents of the feeds on the fly without reloading the page.
  • Supports multiple gAjax RSS displayer instances on the same page.

Demo:

Example 1: (Single RSS feed, 10 entries, "date" field enabled, sort by title)
Example 2: (Two different RSS feeds, 6 entries, "label", "datetime", and "snippet" fields enabled, sort by label)

Example 3: (Three different RSS feeds, 8 entries, "datetime" and "snippet" fields enabled, sort by date)


Example 4: (One RSS feed, use of definetemplate() method to alter display order of the involved fields, so to display description field first, followed by title field. The former is also manipulated to be hyperlinked to entry URL)


Directions Developer's View

Step 1: Insert the following code into the HEAD section of your page:

Select All

Step 2: Download the below .js file and image, which are also referenced by the code above,  and upload to your site:

  • gfeedfetcher.js (right click and choose "Save As").

  • (right click and choose "Save As").

Step 3: Finally, to display the desired RSS feeds, just add the below sample HTML to your page, which illustrates 3 different examples using various feeds (Slashdot, Digg, CSS Drive, CNN etc):

Select All

That's it!

Documentation

Here comes the part you dread, but will come to love soon enough- the documentation section.

var socialfeed=new gfeedfetcher("someid", "someclass", "_new")
socialfeed.addFeed("Slashdot", "http://rss.slashdot.org/Slashdot/slashdot") //Specify "label" plus URL to RSS feed
socialfeed.addFeed("Digg", "http://digg.com/rss/index.xml") //Specify "label" plus URL to RSS feed
socialfeed.displayoptions("label datetime snippet") //show the specified additional fields
socialfeed.setentrycontainer("div") //Display each entry as a DIV
socialfeed.filterfeed(6, "label") //Show 6 entries, sort by label
socialfeed.init() //Always call this last

gfeedfetcher object and methods
Constructor Description
new gfeedfetcher("id", "cssclass,
"[optional_link_target]")

Required

Main gfeedfetcher() constructor function to create a new instance of gAjax RSS Displayer.

Parameters:

  • id: An arbitrary but unique string to be used as the CSS "id" attribute of the outermost container DIV.
  • cssclass:  An arbitrary string to be used as the CSS "class" attribute of the outermost container DIV.
  • [optional_link_target]: An optional parameter that lets you set the link target for the RSS feed links.

Example:

var myrss=new gfeedfetcher("someid", "someclass", "_new")

Method

Description

instance.addFeed("label", "feedurl")

Required

Adds a feed to be retrieved and shown (based on its full URL). Call this function more than once to add multiple feeds.

Parameters:

  • label: An arbitrary string used to "label" this feed (ie: "Slashdot"). This label can then be optionally shown alongside each entry, or to sort multiple feeds based on their label.
  • feedurl: The full URL to the feed.

Example:

myrss.addFeed("Slashdot", "http://rss.slashdot.org/Slashdot/slashdot")

instance.displayoptions(space_delimited_keywords)

defaults to "title"

By default, only the title of each RSS entry is shown. Specify additional fields such as each entry's date and description by calling displayoptions() and passing in specific keywords, each separated by a space, for example, "datetime label description".

Parameter:

  • space_delimited_keywords: A list of keywords representing the additional fields of each entry you wish to show, separated by a space. The list of valid keywords are:
    • "date"
    • "time"
    • "datetime"
    • "label"
    • "snippet"
    • "description"

Example:

//eg1: myrss.displayoptions("datetime")
//eg2: myrss.displayoptions("date label snippet")
//eg3: myrss.displayoptions("datetime label description")

instance.setentrycontainer("TagName", ["cssclass"])

defaults to ("li", "")

Updated in v2.0

Changes the element used to contain each RSS entry. By default, it is a li element (<li>), so that the RSS entries are displayed as a HTML list. You can, for example, pass in "div" or "p" so the entries are displayed as DIVs or paragraphs, respectively.

Parameter:

  • "TagName": Name of the HTML element you wish to encase each RSS entry using. Default is "li" (HTML list).
  • "cssclass": Optional string parameter that adds a CSS class to the outer container of each RSS entry. In the case of RSS entries being encased in "LI" elements, the CSS class would be added to each of the "LI" element.,

Examples:

//eg1: instance.setentrycontainer("div")
//eg2: instance.setPersist("li", "listyle")

instance.definetemplate("template_string")

defaults to "{title} {label} {date}<br />{description}"

New in v2.0

 

Allows you to change the display order of the various fields of each RSS entry as they are output. The default output structure is to put the "title", "label", and "date" fields all on one line, followed by the "description" field on the next. To rearrange this, plus add additional HTML tags to the output, enter a new template string, using the following keywords to designate the various fields:
  • {url}
  • {title}
  • {label}
  • {date}
  • {description}

The {url} keyword lets you display the destination URL of each RSS entry (extracted from the {title}) separately within your output. The following call to definetemplate() causes the output of each RSS entry to simply consist of the description field, hyperlinked:

Example:

instance.definetemplate("<a href='{url}'>{description}</a>")

See "Customizing the display order of each rss entry's fields" on the supplementary page for additional info.

instance.addregexp(RegExpLiteral, "replacement_text", ["targetfield"])

defaults to null

New in v2.0

 

Lets you perform a search and replace inside each RSS entry as a whole, or a specific field such as the "description" field. The first parameter is a regular expression to isolate the text you wish to replace, and the 2nd, the new text to replace it with. An optional 3rd parameter lets you limit the operation to a specific field within each RSS entry, with the valid keywords being:
  • "titlefield"
  • "labelfield"
  • "datefield"
  • "descriptionfield"

Lets say the description field of your RSS entries contain the "[CDATA[" and "]]" tags wrapped around it that's showing up in the output. To remove them, you can call addregexp() in such a manner:

instance.addregexp(/(\[CDATA\[)|(\]\])/g, '', 'descriptionfield')

The first parameter is a standard JavaScript regular expression that basically detects the presence of either "[CDATA[" or "]]" in the description fields, with the 2nd parameter specifying that they should be replaced with an empty string instead. The 3rd parameter limits the search and replace to just the "description" field.

You can call addregexp() multiple times in your initiation code to apply multiple search and replace operations.

See "Search and replace text within your RSS entries" on the supplementary page for additional info.

instance.filterfeed(int, ["sortby"])

Required

Sets the number of entries to retrieve and display. An optional second parameter lets you sort the results by "date", "label", or "title".

Parameter:

  • int: An integer specifying the total number of entries to fetch and display. If multiple feeds are defined, this number is distributed amongst the feeds. For example, if you've specified a value of "6" and there are 2 RSS feeds, each feed will show 3 entries.
  • "sortby": An optional second parameter lets you sort the results in a variety of ways. The valid keywords are "date", "label", or "title". Default is by "date".

Examples:

//eg1: instance.filterfeed(6, "date")
//eg2: instance.filterfeed(5, "label")

instance.onfeedload() Call back function that runs when the RSS Displayer has fully loaded (all of its feeds that is). Use it to execute custom code just before the RSS Displayer is shown on the page.

Examples:

instance.onfeedload=function(){
 alert("RSS Displayer has loaded!")
}

instance.init()

Required

Call this function at the very end to initialize the gAjax RSS Feed Displayer using the above settings.

Styling your RSS entries

Upon output, each entry within your RSS feed(s) is automatically formatted in a way that makes it easy to style its various fields. Specifically, each field is wrapped around its own SPAN tag with a specific CSS class name:

Sample Entry Output:

So the "Title Field" of each entry for example is always wrapped in a SPAN element carrying the CSS class "titlefield", and so on for the other fields, and in that order. The entire entry is wrapped in a "LI" element by default, or as dictated by the setentrycontainer(tagName, [cssclass]) method (see above table). With that said, you might have the following CSS to style your RSS entries:

.titlefield{ /* CSS for title field in general */
font-weight: bold;
}

.labelfield{ /* CSS for label field in general */
color:brown;
font-size: 90%;
}

#example1 .datefield{ /* CSS for date field of the RSS feed with id="example1" */
color:gray;
font-size: 90%;
}

The ID selector "#example1" above is used to let us further target a specific RSS feed instance's date field, where the ID derives from that specified when calling new gfeedfetcher("id", "cssclass, "[optional_link_target]") to instantiate a RSS feed displayer.

Now, you can also alter the order in which the various fields appear via the definetemplate() method, and do a search and replace of text inside any of them via addregexp(). That's further discussed in the Supplimentary Page.

Refreshing the contents of the feeds on the fly

After the desired RSS feeds are shown on your page, you can actually refresh its contents on the fly, without reloading the page. You do this by calling instance.init() again. For example:

<script type="text/javascript">

var socialfeed=new gfeedfetcher("example2", "example2class", "_new")
socialfeed.addFeed("Slashdot", "http://rss.slashdot.org/Slashdot/slashdot") //Specify "label" plus URL to RSS feed
socialfeed.filterfeed(6, "label") //Show 6 entries, sort by label
socialfeed.init() //Always call this last

</script>

<a href="javascript:socialfeed.init()">Refresh Feed Contents</a>

Bear in mind, however, that Google Feeds API caches the specified RSS feeds on their servers, and only refreshes them around once every hour. This means it's usually futile to be calling the init() function every few minutes, as the same content will most likely be returned.

Table Of Contents

This script consists of an index page plus one supplementary pages: