instantRSS

usage documentation

• installing
• tagging your page
• channel tags
• item tags
• notes
• configuration
• linking to your new feed
• further hacking

installation

instantRSS can be used two ways: remotely or locally. both methods of of usage will return the same output.

Remote usage implies that the instantRSS script resides on a server that does not host your site/blog. This is handy for folks that don't have any type of scripting on their hosts, or just don't want to fool with it. If you'd like to use thelocust.org's instantRSS script to generate your RSS then check out instantRSS's site listed above for the url to use.

Local usage implies that the instantRSS script resides on the same server that hosts your site, and that instantRSS script is used *only* for your instantRSS marked pages.

In either case, to give instantRSS a URL to parse just specify the page to get the RSS from in the url= variable in the URL (replacing yourblog.com with the name of the server with instantRSS on it):

http://yourblog.com/instantRSS.php?url=http://yourblog.com/index.html

TAGGING YOUR PAGE

if you don't know about the different RSS tags, check out http://voidstar.com/rssfaq 'cause I'm not going to explain it here.

All instantRSS tags are in this format: <!--instantRSS:xxxxx--> where xxxxx is the name of the tag.

example instantRSS markup:

<!--instantRSS:beginchantitle--> Ben's Blog <!--instantRSS:endchantitle--> <!--instantRSS:beginchanlink--> http://thelocust.org <!--instantRSS:endchanlink--> <!--instantRSS:beginchandesc--> the blog of ben wilson <!--instantRSS:endchandesc--> <!--instantRSS:beginitem--> <!--instantRSS:begintitle--> February 11, 2003 <!--instantRSS:endtitle--> <!--instantRSS:beginlink--> <!--http://thelocust.org?newsid=364--> <!--instantRSS:endlink--> <!--instantRSS:begindesc--> Man, I've got SO MUCH news today! The sun is shining! <!--instantRSS:enddesc--> <!--instantRSS:enditem-->

instantRSS will use whatever is in between the two corresponding tags as the value for that tag. for instance, the channel title in the above example is "Ben's Blog". instantRSS will also take values in HTML comments as seen in the item link tag in the example above. This allows you to hide values so that they are not see on your actual site. This may be done with ANY valid instantRSS tag. When outputting that hidden value, the <!-- and --> header and footer will be removed automagically.

CHANNEL TAGS

title - (beginchantitle / endchantitle). if instantRSS fails to find this tag, it will attempt to find and use the tag which is found in the <header></header> of most pages.

link - (beginchanlink / endchanlink). if instantRSS fails to find this tag, it will use the link passed to it via the URL variable.

desc - (beginchandesc / endchandesc). if instantRSS fails to find this tag it will attempt to use the META description tag found on many pages in the <header>. e.g.: <meta name="description" content="AE4RV.com is....">

ITEM TAGS

item - (beginitem / enditem). Note that each item must begin and end with
the corresponding tag. all item sub-tags must be within the beginning
and ending item tags
item title - (begintitle / endtitle)
item link - (beginlink / endlink)
item desc - (begindesc / enddesc)

NOTES

HTML will be stripped out of ALL tag values, unless specified through the HTML variable as such (or you have specified a value for $iHTMLLevel, see IN-SCRIPT CONFIGURATION):

http://yoursite.com/instantRSS.php?url=http://thelocust.org&html=1
There are 3 possible values for HTML=:
0 - no HTML in RSS output
1 - any and all HTML in RSS
2 - escaped HTML in RSS (spaces become %20, etc)

IN-SCRIPT CONFIGURATION

There are couple of options you may set within the script.

URL Restriction ($bURLRestrict,$arrValidURL)

This set of veriables allows you to restrict your copy of instantRSS from parsing and outputting RSS feeds from any other servers, save for the ones you specify in the $arrValidURL array. This way, other folks can't use up your bandwidth to spit out their RSS.

To turn this on, specify $bURLRestrict = 1;. Otherwise $bURLRestrict = 0;.
To add a URL to the $arrValidURL array, just add that hostname (e.g. thelocust.org) to the array as such:
  $arrValidURL = array("thelocust.org","www.thelocust.org","ae4rv.com");


HTML Level ($iHTMLLevel)

This allows you to set the HTML level you'd like to see in your RSS. This operates just like the above "HTML" variable, with the exception that if this variable ($iHTMLLevel) is set, it will override any querystring-specified HTML value.

HOW TO LINK TO IT

A raw link example: http://yourserver.com/instantRSS.php?url=http://yourserver.com/index.html

Alternately, you can make a tasty little text-only button like this: XML

<a href="http://yourserver.com/instantRSS.php?url=http://yourserver.com/index.html" title="XML"> <span style="font-family: verdana, sans-serif; font-size: 10px; font-weight:bold; text-decoration:none; color: white; background-color: #FF6600; border-left:1px solid #EAEAEA; border-top:1px solid #EAEAEA; border-right:1px solid #3A3A3A; border-bottom:1px solid #3A3A3A; padding:0px 3px 0px 3px; margin:0px;">XML</span> </a>

HACKING NOTES

You want to hack on this and send me a patch? AWESOME. Send your changes (in a patch or as the whole file) to ben[at]thelocust[dot]org. Please use spaces instead of tabs when indenting. Tabs are the work of the devil.