Welcome to CG-Feedread

A system for aggregating RSS-type newsfeeds and data sources into your website.

The origin of CG-Feedread was a neat script by Jaykul.
Unsure if it was originally derived from anything/anyone before him, and needless
to say that at this point (two years later), I've replaced core functionality,
rewritten most every line of code, so the only thing that's the same is a function
name or a parameter somwhere...

CG-FeedRead includes:

RSS/RDF/Atom feed parsing, with basic field identification and output
new XML parsing system, using the revised CG XMLParser library (shared with CG-Amazon).
pre-parse the XML page into an array structure, walks proper parts of the structure to

retrieves full HTML-capable descriptions (DANGER), if provided in feed, and not disabled in call
creates nice-text link titles for non-description layouts
new HTTP reader function, for custom access to web servers and XML feeds
handle 'weird' feeds, like WordPress RSS2, that don't quite follow HTTP convention 100%
ability to do 'MultiFeed' intermixes from multiple RSS feeds at once
ability to re-output a formatted RSS feed from some source (good for re-feeding a MultiFeed, for example) still under dev

NOTE FOR OLD USERS:
The 'parseURL' function is now called 'getSomeFeed', to make the functionality much
more clearly delineated (and there are other php functions called 'ParseURL' out there...)

PLEASE Help CHAITGEAR

If you find this code useful, please help out CHAITGEAR in return. Go to the How to Help CHAITGEAR page,
and donate money, time, or links back.

Thanks!

INSTALLING CG-Feedread

This documentation is in a state of flux!!
Feedread is now supporting the WordPress 1.2 'Plugin' format, so there are multiple ways
to install/use Feedread depending on whether you are using WP or not (and if you are,
which version...).

For non-WP and WP<1.2:
The library assumes it is in a subdirectory in the root of your website. It is easiest
for it to stay in the "cg-plugins" folder, as that's where other CG libraries share code
from and live. Just copy the cg-plugins folder up to your site.

You MUST make sure to give the cg-plugins/cache_rssfeeds/ directory server-writeable permissions.

Then, ONLY FOR NON-WP OR 1.2 AND EARLIER:
modify your index.php or my-hacks.php or other main website file. (If in WP's index.php,
you'll want this after the wp-blog-header include, but before the header block begins,
within the initial <?php section.
Also note to put it AFTER the CG-Amazon startup if using that too.

	$myplugins = "cg-plugins"; // not needed if you have CG-Amazon already above this.
	require_once($myplugins."/feedread.php");

For WP1.5+:
You MUST make sure to give the cg-plugins/cache_rssfeeds/ directory server-writeable permissions.

Then, within the Admin - Plugins interface, you should see CG-Feedread listed, and can click the
ACTIVATE link to enable it. Done with install. ;)

USING CG-Feedread

Add to your index.php, or wherever you want the feed 'imported', something like:

<?php
	$feedUrl = "http://news.com.com/2547-1040_3-0-5.xml"; // a sample CNET feed.  use your own...
	$feedOut = getSomeFeed($feedUrl, 4, false, "feed-cnetttech", '', 36, false);
	if ($feedOut)
		echo $feedOut;
?>

To better integrate into the default WP styling scheme, for a sidebar feed,
I've included some 'simple block' functions. Try code like the following
in the menu/sidebar section of your template:

<?php
	$feedUrl = "http://news.com.com/2547-1040_3-0-5.xml"; // enter your feed's url here
	$feedOut = getSomeFeed($feedUrl, 4, false, "feed-cache-name", '', 36); // enter a cache name
	if (!empty($feedOut))
	{
		start_block("Feedread News", "feedread", "li");
		echo $feedOut;
		end_block();
	}
?>

A newer feature of CG-FeedRead is 'MultiFeed', the ability to draw in a bunch of newsfeeds at once,
and 'intermix' the results by their timestamps for a nice sorted display. This REQUIRES all feeds to
properly output timestamps, obviously!

A quick 'multifeed' example would be something like:

<?php
	// first, make an array of all the feeds you want intermixed
	$feeds = array (
					"http://www.chait.net/wp-rss2.php",
					"http://www.gizmodo.com/atom.xml"
	               );

	// decide how many total entries you want, sampled from how many PER FEED 
	$count = array(10, 5); // 10 max output, 5 max sourced from each feed.
 
	$feedOut = getSomeFeed($feeds, $count, true, 'multifeed', '', -1, -1, false, false, 0, false, false, true); 
	if (!empty($feedOut)) echo $feedOut;
?>

Function Parameters

Params to getSomeFeed function, in order:

function getSomeFeed($InUrl, $maxItemsPerFeed, $showDetails, $cacheName, $filterCat='',
					$tLimit = -1, $dLimit = -1, $noHTML = true,  
					$showTime = false, $feedStyle = false, $noTitle = false,
					$showTimeGMT = false, $titleImages = false, $multiSiteTitle=true,
					$makeRSS=false, $rssName="CG-FeedRead Multifeed", $rssLink="http://www.chait.net/")

$InUrl
The fully specified url of the news feed, or for MultiFeed an array of fully specified urls

$maxItemsPerFeed
How many items to display from the feed, taken in order in the feed. For MultiFeed, an array(total-count, per-feed-max), where per-feed max elements are taken from each feed and sorted by timestamp, and then in order total-count items are output.

$showDetails
false to show just the feed item title, true to show the details/body as well.

$cacheName
What to name the cache file on disk (obv give it something unique from other feeds!)
NOTE: caching is important, so that you don't repeatedly hit feeds.
The global $XML_CACHE_TIME controls the age of the cachefile before recaching. If not set
(global unset), defaults to 6 hours.

$filterCat
Can leave as '' generally. Allows you to filter items by matching a string in the feed urls
or categories. For stripping down big feeds that don't have sub-categoried feeds.

$tLimit
Character limit on titles. (truncates) -1 to leave alone.

$dLimit
Character limit on descriptions. (truncates) -1 to leave alone. NOTE: does NOT do any intelligent
truncation, so dangerous to use with HTML-enabled feed output.

$noHTML
Defaults false, to strips HTML tags from descriptions for safety. Set to true to enable HTML bodies from feeds.

$showTime
Defaults false. Set to true to have feed output include the timestamp of the feed item.

$feedStyle
Defaults false/0. Feed style option. 0 == list, 1 == WP post-like, 2 == simple <br>
Style=2 is for raw text and links, style=0 is for the general ul/li list format for typical sidebar/menu.
Style=1 approximates the 'general' style of wordpress tag elements for posts on a page (based off the old
default theme). Depending on your theme, you might need some extra divs (for kubrick...).

$noTitle
Defaults false. true to NOT show the feed title.

$showTimeGMT
Defaults false. true to show timestamps (when enabled above) in GMT format.

$titleImages
Defaults false. true to show titles as image graphics, when graphic URLs are provided in the feed.

$multiSiteTitle
Defaults true. true to show the title of the feed prefixed to each feed item when showing a MultiFeed.

Styling Things

Basic CSS styling approach to the style==0 feed output:

CSS for overall:
.feedItem
good for setting primary margins/padding/borders, etc.

CSS for titles:
.feedItemTitle
or
.feedItemTitle a, .feedItemTitle a:hover, .feedItemTitle a:visited
to manage the link stylings (which otherwise might be superceded...)

CSS for body:
.feedItemDescription
for basic paragraph styling, sub styling of elements off of this:
.feedItemDescription p
for HTML bodies
.feedItemDescription blockquote
for base quotes
.feedItemDescription a
for links within feeds
...etc...

The difficulty of styling feeds becomes most complex when you allow HTML descriptions, as you may need to override a bunch of basic CSS elements within .feedItemDescription.

NO WARRANTY

This library is free for use, WITH NO WARRANTY:

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.