Home
XML and RSS
RSS Display Boxes
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.
| 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:
|
| 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:
|
| 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:
|
| set_cache_time(minutes) | Sets the cache time of this RSS feed in minutes. Parameter:
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:
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...
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:
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.
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:
| Template | Description |
|---|---|
<a href="#" rel="previous">Previous</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"> |
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>
