rssfilter-docs.txt

for news RSS to HTML as ASP

RSSFilter v3.x PHP Script Documentation

CONTENTS:
  Introduction
  Install
  Uses
  Filter Creation
  Usage
  Advanced Filters


Introduction:
-------------

RSSFilter allows the filter rules to be applied to an RSS feed to produce a new RSS feed.  RSS 2.0 feeds are fully supported, but the other RSS formats and Atom feeds are supported to a lesser extent.  The filter rules can constructed with the help of a built-in interface.


Install:
-------------

To install RSSFilter copy all of the .php files in rssFilter.zip to your web server.  If you are using any of the other FeedForAll scripts, place them all in the same directory.


Uses:
-----

- Filter the items displayed by words or phrases
- Filter the display of items by time or date ranges


Filter Creation:
----------------

By using the built-in filter rule builder it is very easy to build the filters.  To start add "?buildScript" to the URL, for example http://www.your-web-server.com/rssFilter.php?buildScript .  This will bring up a page showing default values.  The main part of the screen is the filter rules screen.  Right above the large table is the selector the defines how the rules work together.  The item from the feed can be used if all of the rules match, "AND"; or the item will be used if any of the rules match, "OR".

The first column contains a drop-down list to select the field from a RSS 2.0 feed that will be used, for non-RSS 2.0 feeds a lot of the fields are mapped to RSS 2.0 fields.  The second column is the filter or type of comparison, that will be used.  The last column is the value compared to.

When working with the <pubDate>, you can work with the date as a number so comparisons can be done.  This is done by choosing "~~~ItemPubDateAsNumber~~~" for the field.  The filters "Before Time" and "After Time" compare against the <pubDate> for both the date and time against the value field.  The filters "Before Date", "On Date" and "After Date" compare only against the date, ignoring the time.  The values that can be used to comparing against is very flexible, full information can be found at http://www.gnu.org/software/tar/manual/html_node/tar_109.html .  So if you wanted to only include items were released in the last week you could use the following settings.

Field: ~~~ItemPubDateAsNumber~~~~
Filter: After Date
Value: 1 week ago

After entering your rules, of if you need more then 5 rules, click on "Generate script file".  After each generate, there will always be 5 blank rule spaces open.  The current state of the filter script will be displayed at the top, along with a "Test Script" button.  This will open a new browser and show the results of the filter as a raw XML file.

To modify an existing filter rule, add the filter filename to the URL.  http://www.your-web-server.com/rssFilter.php?buildScript=myfeed.php


Usage:
------

After creating and testing your new filter, copy the filter file from the rssFilter.php?buildScript page to a file ending in .php on your server.  You can specify this file as your feed.  If you name the file "myfeed.php" you could access the filtered feed in two ways, http://www.your-web-server.com/rssFilter.php?SCRIPTFILE=myfeed.php , which will work but is messy.  You can also produce the exact same results with http://www.your-web-server.com/myfeed.php .  Using this shortened version makes much cleaner URLs for your users or as the input to other FeedForAll scripts.


Advanced Filters:
-----------------

For usability the ?buildScript tool only supports an all-AND or all-OR mode.  However, that doesn't mean you are limited to staying in that mode.  If you want to build a filter the checks for items released in the last week and contains a word or another word in the title requires syntax similar to "date AND (word or other word)" you will have to do some of this by hand.  The best way to start is to use the ?buildScript tool to create the base filter rules.  Then you can modify the rule itself to add the grouping and comparisons that meet your needs.  If you load this filter back into ?buildScript the original logic will be used and displayed for you to use.  But since this is an advanced topic, it should not be to hard to re-modify to apply the same changes again.


Copyright 2007 NotePage, Inc. All rights reserved

$Id: rssFilter-docs.txt,v 3.0 2007/04/16 14:23:04 housley Exp $