rss-homepage Documentation

Updated 25/11/04

This documentation is about the package rss-homepage. It includes an overview of how to quickly set up your page, more detailed line by line analysis of the code, and where all of this code is so that you can modify it to how you like.

Getting Started

Installation

To install rss-homepage, just extract the files from the archive to a folder that can be served on your web server. After this, no more installation is needed, as a basic rss-homepage comes as default. If you need to change the feeds on the page, or want to make any more modifications, you will need to read on.

Viewing

A file called index.php is provided as an example in the archive, and most servers will use this as the page to show if no file is specified in the URL. So all you need to do is fire up a web browser and type in the address of the directory on your web server.

Basic Overview

Use the following code for a basic rss-homepage, showing the Slashdot feed and a seperate box showing the time of the last update and a Google search box.

01:
02:
03:
04:
05:
06:
07:
08:
09:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
22:
23:
<?php
include("rss.php");
include("slashdot.php");
$slash_rss_parser = new Slashdot("slashdotcache.xml");
include("output.php");
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
   <title> Current Articles </title>
   <link rel="stylesheet" href="style.css" />
   <?php
      javascript();
   ?>
</head>
<body>
   <?php
      outputbox($slashdotoutput,"slashdot","slashdottitle.gif");
      outputinfo();
   ?>
</body>
</html>

This just basically includes the required files (rss.php and output.php), the config file, and also creates a new feed object. It then outputs the xHTML, including the Javascript, and creates a new box for the Slashdot feed and the information.

Required code

Set-up

To set up a rss-homepage, a certain amount of initialisation and output code is needed. In this example, only one feed is used - Slashdot. The following code is needed first (usually before any HTML code):

01:
02:
03:
04:
include("rss.php");
include("slashdot.php");
$slash_rss_parser = new Slashdot("slashdotcache.xml");
include("output.php");

Line by line:

Line 01:
Include the file for parsing RSS data. This file needs to be included for any RSS parsing, even if you are not using the extra features of rss-homepage.
Line 02:
Include the config file for the feed - in this instance, there is a specific config file for the Slashdot.org feed called slashdot.php. If you do not need to include a specific config file (when you do not need any extra features for the RSS feed), you can just include defaultconfig.php.
Line 03:
Create a new object called $slash_rss_parser derived from the Slashdot class (defined in slashdot.php). The class is passed a parameter of where the locally cached RSS data is for the constructor function that is needed to start reading RSS data. When this line is run, the constructor function of the Slashdot class actually runs the function feed() in rss.php (passing on the object and the location of the RSS cache), that reads and parses the RSS data, using any extra functions in the config file.
Line 04:
Include the file for creating an XHTML output - output.php, that is specific to the rss-homepage package.

Output

Within the body of the HTML file, output can be sent with PHP code to give the actual output of the page. The following code would be used to provide a Slashdot box, and the standard information box:

01:
02:
outputbox($slashdotoutput,"slashdot","slashdottitle.gif");
outputinfo();

Line by line:

Line 01:
Create an output in a box for the Slashdot feed (with no style sheet it will not actually be in a box, but using the default style sheet provided with rss-homepage it will place it in a box). This function is in output.php and uses some nice XHTML ready to be styled (usually by the style sheet provided), header images for each feed, and a little arrow that can show/change the mode of whether the box is minimized/maximized with the javascript provided in output.php. This function takes the parameters of the output string (provided by the config file), a unique name for the feed (used for element id's), and the location of the image in an images/ folder.
Line 02:
Creates an output box with the time of the last update (read from a file called updatetime using the format of the number of seconds since 00:00:00 1970-01-01) and a Google search box.

Extra Javascript

If you have looked at the default rss-homepage, or the example page on the web site, you will notice that each box has a small arrow in the top corner, showing whether the box has been minimized or maximized. Clicking on this arrow or the header image will change this state. This is all done with some basic Javascript code, that is in a function called javascript() in output.php. If you need/want to use the javascript, put the following line in a PHP block in the head section of the HTML page:

01:
javascript();