FF1+ IE5+ Opr8+

gAjax RSS Feeds Displayer v2.2 (hosted)

Author: Dynamic Drive

Dec 3rd, 16': Version 2.1, which uses YUI YQL in place of Google Feeds API due to retirement of later. Also adds limitlength() method
Feb 8th, 17': Version 2.2 (by jscheuer1), which adds Atom Feeds support, plus improvements to the limitlength() function

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 YQL to host the desired RSS feeds on Yahoo'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 YUI YQL 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", and more.
  • Strip HTML and limit the number of characters shown by a specific field, such as the "description" field. v2.1 feature
  • Search and replace any text within each RSS entry using regular expressions to mold the output to your exact specifications.
  • Customize the order of each field when they are output using the built in template 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 RSS feeds, 4 entries, "label", "datetime", and "snippet" fields enabled, sort by label)



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


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("BBC News", "http://feeds.bbci.co.uk/news/rss.xml") //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 description") //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", ["atom"])

Required

Improved in v2.2

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.
  • "atom": Optional string of "atom" if the RSS feed is an Atom Feed.

Example:

myrss.addFeed("BBC News", "http://feeds.bbci.co.uk/news/rss.xml")
myrss.addFeed("BBC News", "http://feeds.bbci.co.uk/news/feed.atom", "atom")

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"
    • "description"

Example:

//myrss.displayoptions("datetime")
//myrss.displayoptions("date label")
//myrss.displayoptions("datetime label description")

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

defaults to ("li", "")

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:

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

instance.limitlength(chars, "fieldtype", [ForceStrip])

defaults to undefined

Improved in v2.2

Lets you strip any HTML inside a field and limit the number of remaining characters shown inside a particular field, most commonly, the "description" field.

Parameter:

  • chars: An integer specifying the maximum number of characters to show after any HTML has been stripped. Use the keyword "strip" instead to simply strip the output of any HTML tags without imposing a limit on the field length.
  • "fieldtype": The field of each RSS entry to apply the restriction- valid keywords are "titlefield" or "descriptionfield".
  • ForceStrip: Optional Boolean that if set to true always strips a field of any HTML tags

This method can be called more than once to apply the character restriction to both the "title" and "description" fields if needed.

Examples:

//instance.limitlength(150, "descriptionfield")

// Strip field of tags without imposing limit on field length:
//instance.limitlength("strip", "descriptionfield")

//Limit field length to 150 and always trips field of HTML tags (even if below 150 chars):
//instance.limitlength(150, "descriptionfield", true)

instance.definetemplate("template_string")

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

 

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

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:

//instance.filterfeed(6, "date")
//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.

Table Of Contents

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

Wordpress Users: Step by Step instructions to add ANY Dynamic Drive script to an entire Wordpress theme or individual Post