RSS Display Boxes
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.zipwhich 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)!