CaRP: Caching RSS Parser - Documentation

Page

Page is a plugin bundled with CaRP Evolution 4.0.12 and higher. It makes it easy to enable your website visitors to navigate through the items in a feed a page at a time, displaying a limited number of items on each page.
 

Installation:

To install Page, if "page.php" is not already found in your "plugins" folder, upload it to that folder.
 

Use:

To tell CaRP Evolution to use the Page plugin (see the example code below for details):

1. If you are aggregating multiple feeds, prepare them for aggregation as usual using CarpFilter, CarpCacheFilter or CarpGroupFilter.
2. Load the plugin.
3. Set CaRP's "maxitems" setting to tell CaRP how many items to display per page.
4. To tell the plugin how many pages of items to skip (for example, to display the second page, tell it to skip 1 page), do one of the following:
   • Set the plugin's "skip-pages" setting ($carppageconf['skip-pages']).
   • Use the CarpPageLinks function (see below).
5. Display the feed or feeds using the usual feed display functions (CarpCacheShow, CarpAggregate, etc).

 

Functions:

The Page plugin has a function that generates the links to go to the previous and next pages of items in a feed, as follows:

• CarpPageLinks($url, $skip_pages, [$top_text, $bottom_text, $left_top_bottom, $page_arg_name, $max_page])
  • $url: The URL of the page -- you may enter just the filename rather than the full URL, for example, "mypage.php". The URL may contain arguments, for example, "mypage.php?id=foo".
  • $skip_pages: The number of previous pages of items to skip. For the first page, enter 0.
  • $top_text: (optional) - if set, this overrides the "top-text" configuration setting (see below).
  • $bottom_text: (optional) - if set, this overrides the "bottom-text" configuration setting (see below).
  • $left_top_bottom: (optional) - if set, this overrides the "left-is-top-or-bottom" configuration setting (see below).
  • $page_arg_name: (optional) - if set, this overrides the "page-arg-name" configuration setting (see below).
  • $max_page: (optional) - if set to anything other than -1, this overrides the "max-page" configuration setting (see below). If set to -2 (which should only be done after calling the function to display the feed -- see the example below), Page attempts to determine whether there are any items left in the feed for display on the next page. If not, no "next" link is displayed. (If the current page contains the last item in the feed, one extra "next" link to a blank page will be displayed).
  If you wish to set any of the optional arguments, you must set all of the previous optional arguments too. If you set them to empty strings (''), the plugin's default configuration values will be used.
  
  This function returns a string of HTML code that can be used to display "forward" and "back" links for paging through the feed.

 

Configuration:

The Page plugin has the following settings, which are members of the array $carppageconf. In most cases, you'll use the function CarpPageLinks to control these settings. All of the settings except "skip-pages" affect only the output of CarpPageLinks:

• skip-pages: The number of pages of items to skip. For example, to display the third page of items, set this to "2".
   
• max-page: The highest page number to allow the visitor to click through to. If set to zero, there is no limit. You may use this setting if you know how many items appear in the feed to prevent visitors from clicking through to a page that doesn't exist.
   
• page-arg-name: The name of the "argument" that the page number is set in. For example, using the default setting of "page", you could load page 3 with a URL like http://example.com/my-paged-feed.php?page=3.
   
• left-is-top-or-bottom: Tells CarpPageLinks whether the link on the left should take the visitor closer to the top of bottom of the feed. The default value is "top". Any other value is equivalent to setting it to "bottom".
   
• top-text: The text for the link that takes visitors closer to the top of the feed. In most feeds, the newest items appear at the top, so you might set this setting to "Newer". The default value is "Previous" (meaning previous page, with page 1 containing the newest items).
   
• left-symbol: The symbol (if any) to display to the left of the left link. The default is "« ", which displays a "left angle quote" («) followed by a space.
   
• bottom-text: The text for the link that takes visitors closer to the bottom of the feed. The default value is "Next" (meaning nexty page, with page 1 containing the newest items).
   
• right-symbol: The symbol (if any) to display to the right of the right link. The default is "» ", which displays a space followed by a "right angle quote" (»).
   
• left-right-divider: What to display between the left and right links. The default is " | ".
   

Example Code:

Assuming the name of your file was "paging.php", you could use this code to display the feed, 5 items to a page, with bold, enlarged paging links centered above and below the feed:

<?php
$page=isset($_GET['page'])?$_GET['page']:0;
require_once '/YOUR/PATH/TO/carp/carp.php';
CarpConf('maxitems', 5);
CarpLoadPlugin('page.php');
$pagelinks='<p style="font-weight:bold;text-align:center;font-size:115%;">'.
	CarpPageLinks('paging.php', $page).'</p>';

echo $pagelinks;
CarpCacheShow('http://example.com/the-feed.rss');
echo $pagelinks;
?>

To have CarpPageLinks attempt to determine whether or not there are enough items in the feed to display a "next" link, set CaRP's "outputformat" setting to 2, set $carppageconf['skip-pages'], call the display function, then call CarpPageLinks with "-2" as the final argument:

<?php
$page=isset($_GET['page'])?$_GET['page']:0;
require_once '/YOUR/PATH/TO/carp/carp.php';
CarpConf('maxitems', 5);
CarpConf('outputformat', 2);
CarpLoadPlugin('page.php');
$carppageconf['skip-pages']=$page;
CarpCacheShow('http://example.com/the-feed.rss');
$pagelinks='<p style="font-weight:bold;text-align:center;font-size:115%;">'.
	CarpPageLinks('paging.php',$page,'','','','page',-2).'</p>';
echo $pagelinks.$carpoutput.$pagelinks;
?>

When aggregating multiple feeds, be sure to set "maxitems" to the maximum number of items you wish displayed for any particular feed before calling the "filter" function. After calling the filter function, set it to the total number of items to display per page.

<?php
$page=isset($_GET['page'])?$_GET['page']:0;
$feeds=array(
	'http://www.geckotribe.com/press/rss/pr.rss'=>'gt-pr',
	'http://www.example.com/rss/feed1.rss'=>'ex-1',
	'http://www.example.com/rss/feed2.rss'=>'ex-2',
	'http://www.example.com/rss/feed3.rss'=>array('ex-3','ISO-8859-1'),
	'http://www.example.com/rss/feed4.rss'=>array('ex-4','US_ASCII'),
);

require_once '/YOUR/PATH/TO/carp/carp.php';
CarpConf('maxitems',10);
$cachefiles=CarpGroupFilter($feeds);

CarpLoadPlugin('page.php');
CarpConf('maxitems',15);
$pagelinks='<p style="font-weight:bold;text-align:center;font-size:115%;">'.
   CarpPageLinks('paging.php', $page).'</p>';

echo $pagelinks;
CarpAggregate($cachfiles);
echo $pagelinks;
?>

Home | About Us | Contact

Copyright © 2002-2024 Gecko Tribe, LLC, All rights reserved.
PO Box 5835, Grand Island, NE 68802