FF1+ IE5+ Opr8+

RSS Display Boxes

Author: Dynamic Drive

Updated: Dec 18th, 06'. Added templates based, "manual" pagination mode for complete customization of the pagination interface.

Description: Using Ajax, this script makes it easy to display RSS feeds from other sites inside DIV containers. Each RSS box can be independently tailored, from the RSS feed to fetch, how many items to show (and whether to paginate them), to what portions of each entry (just the "title", or "title" plus "description" etc) to display. All this is done on the client side via the script's exposed methods.

On the server side, RSS Display Box relies on a simple yet versatile PHP RSS parser called SimplePie to fetch the RSS feeds first. This is required as JavaScript cannot access nor parse remote files. The script then uses Ajax to manipulate the feed and provide simple JavaScript methods for customizing the output and on the fly. The feed as a result can also be added to any page on your site, not just PHP pages.

Requirement of this script: Ability to run PHP on your server. The actual page(s) on your server displaying the RSS boxes can be any page, not just php pages.

It's helpful to list the features of this script in terms of what's possible on both the client side and server side, so here goes.

On the client side:

  • Specify which RSS feed to fetch based on the list of RSS feed URLs listed inside the server side script.
  • Specify how many items within the feed to display.
  • Optionally, specify how many items to show per "page", with pagination links automatically or semi-automatically created to cycle though pages.
  • New! Two types of pagination supported- "auto" or "manual". In the later, you dictate the exact format of the pagination interface using "pagination templates". See RSS Display Box syntax reference.
  • Specify the name of the "template" used to format the body of each RSS item. This name is picked up by the server side script to display each item in the desired format, whether it's just the "title" of the item, "title" plus "description", or "title" plus "date" etc.
  • Each RSS display box instance on the page generates a unique CSS ID attribute plus CSS classname, allowing you to easily style the RSS box via CSS.

Since the above settings are all done on the client side, a RSS box can be modified instantly and impulsively, without having to make any changes to/reupload the server side script.

On the server side:

  • Uses the versatile PHP RSS parser called SimplePie to fetch the RSS feeds, with support for caching, error handling, international encoding, and much more.
  • Format the body of the RSS item and limit the portions shown using all the functions available within Simplepie and the custom function "outputbody.php".

If you're looking to display RSS feeds on your site in a no fuss yet flexible manner, RSS Display Boxes is your script!

Demos:

Example 1 (CSS Drive):

Example 2 (BBC News):

Example 3 (NYTimes):

Example 4 (CSS Drive):

The 3rd and 4th examples utilize the versatile "manual" pagination mode to let you customize this part of the box in infinite ways. Each ticker is called independently on the page via JavaScript. For example, for the BBC News box, the JavaScript on the page looks like this:

<script type="text/javascript">
var showbbc=new rssdisplaybox("bbc", "bbcid", "someclass")
showbbc.set_items_shown(10, 5) //Fetch 10 entries, but display only 5 at a time (pagination links auto created)
showbbc.set_template("titles") //Use "titles" template, which outputs title + category
showbbc.start() //Required: start script
</script>

Detailed info below.


Directions: The easiest way to install RSS Display Boxes is to download the zip file below:

-rssdisplaybox.zip

which contains all the files that make up the script. They are:

  • demo.htm: working demo page of RSS display boxes
  • rssbox/rssdisplaybox.js
    rssbox/virtualpaginate.js
  • rssbox/rssdisplaybox.css
  • rssbox/main.php
  • rssbox/outputbody.php
  • rssbox/loading.gif
  • rssbox/cache/ directory. Chmod 777 or 755!
  • simplepie/ directory, which contains the files that make up the SimplePie package

To get the script up and running, just upload all files above as is to your PHP capable server, and make sure the directory "rssbox/cache/" has read+write permissions (typically chmod 777 or chmod 755) for the cache files to be created in. Then, call up demo.htm in your browser to see the script in action!

Customization info

It's now time to learn exactly how to customize the script to display your favourite RSS feeds and in the desired format. Lets examine the files that need to be touched.

1) rssbox/rssdisplaybox.js

Inside this file, the only line you need to change immediately is the following at the top:

var rssoutputscript="rssbox/main.php"

This is the path to "main.php" relative to demo.htm within the zip file. It will work out of the box, but only for the demo page. You should uncomment and configure immediately the line that follows it so the path to "main.php" becomes absolute instead:

rssoutputscript="http://"+window.location.hostname+"/subdir/rssbox/main.php

Do NOT modify "window.location.hostname", which is your site's root domain (ie: dynamicdrive.com), dynamically determined. Just modify the path that follows it to "main.php" on your server.

2) rssbox/main.php:

"Main.php" is the custom RSS output file that uses the SimplePie RSS class to retrieve RSS feeds and outputs them  (as regular HTML). The only portion that you need to change immediately is the list of RSS feeds to display:

$rsslist=array(
"cssdrive" => "http://www.cssdrive.com/index.php/news/rss_2.0/",
"bbc" => "http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml",
"nytimes" => "http://www.nytimes.com/services/xml/rss/nyt/HomePage.xml",
"dynamicdrive" => "http://www.dynamicdrive.com/export.php?type=new" //no trailing comma after last RSS URL!!
);

You'll want to give each RSS URL a unique array key name (ie: "bbc"), which is used to identify this feed within the JavaScript portion of the script.

3) Inside your page that will display the RSS boxes

With a list of desired RSS feeds defined, you're now ready to display them inside any page on the same server. Firstly, make sure you've added the mandatory code that should appear inside the HEAD section to your page:

<link rel="stylesheet" type="text/css" href="rssbox/rssdisplaybox.css" />
<script type="text/javascript" src="rssbox/virtualpaginate.js"></script>

<script type="text/javascript" src="rssbox/rssdisplaybox.js">

/***********************************************
* RSS Display Boxes- (c) Dynamic Drive DHTML code library (www.dynamicdrive.com)
* Please keep this notice intact
* Visit Dynamic Drive at http://www.dynamicdrive.com/ for this script and 100s more
***********************************************/

</script>

Make sure the references to the .css and .js files above is correct! You're now ready to show RSS feeds. The most basic JavaScript code to add without any fancy features looks like this,

<script type="text/javascript">
var showbbc=new rssdisplaybox("bbc", "bbcid", "someclass")
showbbc.set_items_shown(10) //show 10 entries from feed
showbbc.start() //Required: start script
</script>

where "bbc" is the ID of the RSS feed to display, and should correspond to the ID defined inside "main.php" above. "bbcid" and "someclass" are just the desired CSS id and classname you wish to be assigned to this RSS box, for styling purposes. Finally, the variable "showbbc" is also just an arbitrary variable name you should define to instantiate this particular RSS box.

Now, the above code block only invokes two of the script's functions to display a RSS feed in its basic form, though additional parameters and methods are supported. Furthermore, the script supports a powerful "manual" mode when it comes to paginating the RSS items into multiple pages that let you format the pagination interface using "templates". Read the syntax reference for full info.

Note: The general look of your RSS boxes is controlled via CSS. See "rssdisplaybox.css" for the CSS used to style the demos.

4) rssbox/outputbody.php

The php file "outputbody.php" contains a single function used to output the body of each RSS item. By editing this file, you control exactly how each RSS item body is presented, such as limiting it to just the item's title. Lets take a look at a slice of the function:

if ($template=="" || $template=="default"){ //DEFAULT TEMPLATE
?>
<DIV class="rsscontainer">
<div class="rsstitle"><a href="<?php echo $item->get_permalink(); ?>"><?php echo $item->get_title(); ?></a></div>
<div class="rssdate"><?php echo $item->get_date('d M Y g:i a'); ?></div>
<div class="rssdescription"><?php echo $item->get_description(); ?></div>
</DIV>
<?
} //end default template
else if ($template=="titles"){ //"TITLES" TEMPLATE
?>
<DIV class="rsscontainer">
<div class="rsstitle"><a href="<?php echo $item->get_permalink(); ?>" target="_new"><?php echo $item->get_title(); ?></a></div>
<div>Category: <?php echo $item->get_category(); ?></div>
</DIV>
<?
}

The above shows the RSS item body for two templates- "default" and "titles". These names (in red) are significant, as they are what you'll be passing into "set_template("templatename")" on the client side to tell the script the template to use to output the RSS item's body. You can create additional "templates" if you're familiar with basic programming  if/else statements. Now, the syntax for the RSS item bodies themselves may look confusing to you:

<div class="rsstitle"><a href="<?php echo $item->get_permalink(); ?>"><?php echo $item->get_title(); ?></a></div>
<div class="rssdate"><?php echo $item->get_date('d M Y g:i a'); ?></div>
<div class="rssdescription"><?php echo $item->get_description(); ?></div>

That's because it uses SimplePie's designated syntax for formatting each item. Once you've taken the time to learn the various methods, the sky's the limit as far as how your RSS items can be manipulated. Visit the below two links for more info:

Enjoy (reading)!

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