New Revised CSS Library Forums Web Tools
FAQs Awards Usage Terms Contact

RSS Display Box syntax reference

RSS Display Box makes it easy to display RSS feeds on any page within your site (not just PHP pages, for example). 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, easily and in real time.

Here's the sample code you'd use on your page to invoke a RSS Display Box (minus the mandatory code that goes in the HEAD section of your page), with most features enabled:

<!-- Basic Example -->

<script type="text/javascript">

var showbbc=new rssdisplaybox("bbc", "bbcid", "someclass")
showbbc.set_items_shown(6, 3) //Fetch 6 entries (or total entries if less than 6 available), but display only 3 at a time (pagination links auto created)
showbbc.set_cache_time(60) //Set cache time between fetching of this RSS feed again from the default 30 minutes to 60 instead
showbbc.setpagination("auto", "top") //Automatically generate the interface for the pagination links, plus position it to the top of the RSS Box
showbbc.set_template("titles") //Use "titles" template (see "outputbody.php"), which outputs title + category
showbbc.start() //Required: start script

</script>

The below documents the public methods of the script and the parameters they accept.

Public methods reference

Methods for rssdisplaybox() object
Method Description
rssdisplaybox(rssId, divId, divClass)

* Must be called

Main RSS Display Box object function that displays the RSS feed corresponding to the "rssId" parameter (id of the RSS feed inside "rssbox/main.php".

Parameters:

  • rssId: The id of the RSS feed to display as specified inside "rssbox/main.php"
  • divId: An arbitrary but unique string to be used as the CSS "id" attribute of this RSS box.
  • divClass: An arbitrary but unique string to be used as the CSS "class" attribute of this RSS box.
set_items_shown(items, [items_per_page])

* Must be called

Sets how many RSS items to retrieve, and optionally, to limit shown per page.

Parameters:

  • items: Specifies the number of RSS items to retrieve and show. If you just wish to display all available items within the feed, just enter 0.
  • items_per_page (optional): Specifies the number of items to show per "page." If defined and is less than the first parameter "items" above, pagination links will be created to let the user cycle through the pages.
set_template("templatename")

* Must be called.

Specifies the name of the "template" to use as designated inside "outputbody.php" for formatting the body of each RSS item.

Parameter:

  • templatename: The name of the template inside rssbox/outputbody.php which formats the body of each RSS item shown.
set_cache_time(minutes) Sets the cache time of this RSS feed in minutes.

Parameter:

  • minutes: Integer specifying the cache time of this RSS feed in minutes. Enter 0 to temporarily disable cache- useful while you're debugging/testing the script.

Defaults to "30" if this method is not explicitly called.

setpagination(paginatemode, pos_or_div) In the event where pagination links are actually needed, sets the pagination display mode, plus either the position or id of the pagination div, depending on the mode.

Parameters:

  • paginatemode: Specifies the pagination display mode: "auto" or "manual". In former, the pagination interface is auto generated for you using a predefined template. In later, you specify the template(s) to use to create the pagination interface.
  • pos_or_id: In "auto" mode, specifies the position of the pagination DIV relative to the RSS Box. Valid values are "top" or "bottom". In "manual" mode, donates the ID of the DIV on your page that you wish to be used to contain the pagination interface. See "Manual Pagination Setup" below.

Defaults to "auto" and "bottom" if this method is not explicitly called (and pagination links are indeed needed).

start()

* Must be called.

Creates the RSS box based on the above settings. This is a required method, and should always be called at the very end of the script, following any of the above methods.

Now, the above methods cover all that you'll need to do unless you want to have total control over the format of the pagination interface (by invoking setpagination() and passing "manual" for the first paramater). Read on in this case...

Manual Pagination Setup

This script supports two modes of pagination for spreading the display of the returned RSS items into multiple "virtual" pages. In "auto" mode, the pagination interface is automatically created for you based on a predefined template. However, if you wish to customize the look and format of the interface, you'll want to take advantage of "manual" mode instead. In "manual" mode you get to tell the script exactly what and how to display the pagination interface, based on a selection of "templates" you specify inside a DIV you designate as the pagination DIV.

To get the script to use "manual" pagination mode, do the following in that order:

  1. Define an arbitrary DIV on the page to be used as the pagination interface for a particular RSS box and give it a unique ID first.

  2. Call rssboxinstance.setpagination("manual", "mypaginatediv") following this DIV on the page, where the second parameter is the OD of the above DIV (ie: "mypaginatediv").

In "manual" pagination mode, both rssboxinstance.setpagination() and rssboxinstance.start() MUST be invoked after your pagination DIV is defined on the page, instead of along with the rest of the methods as in the first example at the very top! Here's an example:

<!-- Manual Pagination Example -->

<script type="text/javascript">

var showbbc=new rssdisplaybox("bbc", "bbcid", "someclass")
showbbc.set_items_shown(6, 3) //Fetch 6 entries (or total entries if less than 6 available), but display only 3 at a time (pagination links auto created)
showbbc.set_cache_time(60) //Set cache time between fetching of this RSS feed again from the default 30 minutes to 60 instead
showbbc.set_template("titles") //Use "titles" template (see "outputbody.php"), which outputs title + category

</script>

<div id="mypaginatediv" class="pagination">
<a href="#" rel="previous">Prev</a>  <a href="#" rel="next">Next</a>
</div>

<!-- Initialize manual pagination interface. Below two methods must be called after pagination DIV has been defined on the page! -->
<script type="text/javascript">
showbbc.setpagination("manual", "mypaginatediv") //"Create pagination interface using DIV with id="paginatediv"
showbbc.start() //Required: start script
</script>

The custom pagination interface I've specified in the above example is contained in the DIV:

<div id="paginatediv" class="pagination">
<a href="#" rel="previous">Prev</a> <a href="#" rel="next">Next</a>
</div>

which would render a simple "back" and "forth" text link for users to cycle through the available pages. Here are the available templates you can use within your pagination DIV:

Templates you can use within your pagination DIV
Template Description
<a href="#" rel="previous">Previous</a>

<a href="#" rel="next">Next</a>

<a href="#" rel="first">First</a>

<a href="#" rel="last">Last</a>

Creates links that paginate backwards, forward, to the 1st page, and to the last page, respectively. The link can be created anyway you like (ie: use an image instead), as long as it contains the designated "rel" attribute inside the link.

Examples:

<a href="#" rel="last" style="font-weight: bold">Last Page</a>

<a href="#" rel="previous" style="margin-right: 80px">Prev</a> <a href="#" rel="next" style="font-weight: bold">Next</a>

<a href="#" rel="previous" style="margin-right: 100px><img src="arrowleft.gif" /></a> <a href="#" rel="next"><img src="arrowright.gif" /></a>

 

<select></select> Creates a drop down menu containing all available pages for the user to quickly jump to a specific page. Feel free to style the menu anyway you like.

Note: Synchronizes automatically with the other templates. For example, if a user clicks on a "next" link above to move forward 1 page, the drop down menu changes to select the current page number within it.

Example:

<select style="background-color: lightyellow" class="lighttheme"></select>

<span class="flatview"></span> By inserting this template, a span element with class="flatview", the script will automatically generate a pagination link for every one of the pages within the paginated content within the span. If you have 10 pages for example, 10 links will be generated with the text "1, 2, 3" and so on.

Note: Synchronizes automatically with the other templates. For example, if a user clicks on a "next" link to move forward 1 page, the script highlights the appropriate link within the list of "flatview" links as well.

<span class="paginateinfo">
</span>
By inserting this template, a span element with class="paginateinfo", the script will display the page number of the current page relative to all available pages (ie: Page 2/4).

Note: Synchronizes automatically with the other templates. As the user moves through the pages, this info is updated automatically.

Example:

<span class="paginateinfo" style="font-weight:bold"></span>

 

By picking and combining the above templates inside your pagination DIV as desired, your pagination interface is as unique as you want it to be. For example:

<div id="listingpaginate" class="paginationstyle">
<a href="#" rel="previous" class="imglinks"><img src="roundleft.gif" /></a> <select></select> <a href="#" rel="next" class="imglinks"><img src="roundright.gif" /></a>
</div>

Sweet Ads X