CaRP: Caching RSS Parser - Documentation

Sort

Sort is a plugin bundled with CaRP Evolution 4.0.8 and higher. It enables the sorting of feed items by any item field in either ascending or descending order. It can also shuffle items in a random order. Finally, it can be used with your own custom sorting function to provide complex sorting capabilities.
 
Installation:
To install Sort, put sort.php into the "plugins" folder inside the folder containing carp.php. (If no plugins folder exists, create one.)
 
Use:
To tell CaRP Evolution to use Sort, first, enter the following command into your webpage after "require_once '/path/to/carp.php';":
 
     CarpLoadPlugin('sort.php');

Then use use the functions and/or configuration settings listed below to select your desired sorting order.

Important Notes:

• This plugin is compatible only with CarpShow and CarpCacheShow, not with CarpFilter, CarpCacheFilter, CarpGroupFilter, CarpAggregate, and CarpInterleave. If you wish to use it to sort aggregated feeds, create a script that outputs the aggregated feed in RSS 2.0 format using the RSS 2.0 theme, and then use this plugin with CarpShow or CarpCacheShow to display the output of that script.
• When using this plugin and the Filter plugin, be sure to load the Filter plugin and set up your filters before loading this plugin.
• This plugin uses the Processed Data plugin. Other than setting the Processed Data plugin's cache file name, you should not load or configure the Processed Data plugin when using this plugin.
• I recommended not using manual caching with this plugin (ie. specifying a cache file name after the feed URL in calls to CarpShow and CarpCacheShow), because the data in the manual cache will not be used. I do recommend using the Processed Data plugin's "cache" setting when using this plugin.

 
Functions:
Your code may call the following functions from the Sort plugin after you have loaded it as described above:

• SortCarpByOneField($field[, $order[, $type]]): Use this function to tell the plugin to sort items according to the value of any one of the fields from the items.
  • $field: The name of the field to sort by. This must be one of CaRP's internal fields that can be used with the iorder setting (including custom fields you define using CarpMapField).
  • $order: If set to 'ascending' (the default), items are sorted smallest first. If set to anything else, items are sorted largest first (ie. 'descending').
  • $type: If set to 'natural' (the default), the sort order is a case-insensitive "natural language" order. If it is set to any other value, "ASCII code" order is used.
  
   
• SortCarpByOneElement($element[, $order[, $type]]): Use this function to tell the plugin to sort items according to the value of any one element or attribute from the RSS item data.
  • $element: The name of the element or attribute to sort by. Specify it as you would the element or attribute when calling CarpMapField.
  • $order: If set to 'ascending' (the default), items are sorted smallest first. If set to anything else, items are sorted largest first (ie. 'descending').
  • $type: If set to 'natural' (the default), the sort order is a case-insensitive "natural language" order. If it is set to any other value, "ASCII code" order is used.
  
   
• SortCarpByDate($order): Use this function to tell the plugin to sort items by their date stamps.
  • $order: If set to 'ascending', items are sorted oldest first. If set to anything else (the default), items are sorted newest first (ie. 'descending').
  
   

 
Configuration:
The Sort plugin has the following settings, which are members of the array $sortcarpconf. In most cases, you'll use the functions listed above to control these settings:

• function: The name of the sorting callback function to use. The default is SortCarpOneField, which sorts according to the value of the field named in the "fields" setting. If this setting is empty, the items are shuffled in random order.
   
• fields: A comma-separated list of field names that will be used in sorting. In most cases, there will be only one field named. However, if you wish to perform complex sorting using multiple fields (for which you will have to write a custom sorting callback function), you may list more than one.
   
• order: Either "ascending" or some other value as described in the function descriptions above.
   
• type: Either "natural" or some other value as described in the function descriptions above..
   
• max-items: If set to anything but 0 (zero), this setting controls the maximum number of items that will be displayed. When set to 0, CaRP's "maxitems" setting contols the number of items displayed. In either case, CaRP's "maxitems" setting controls the number of items that this plugin sorts and selects from among. So if you wish to sort an entire feed but display only a few items from it, set CaRP's "maxitems" higher than the number of items in the feed, and this setting to the number you wish to display.
   

Example Code:
To sort the entire feed alphabetically by title:

<?php
require_once '/YOUR/PATH/TO/carp/carp.php';
CarpLoadPlugin('sort.php');
CarpCacheShow('http://example.com/videos.rss');
?>

To display 3 items in random order:

<?php
require_once '/YOUR/PATH/TO/carp/carp.php';
CarpLoadPlugin('sort.php');
$sortcarpconf['function']='';
$sortcarpconf['max-items']=3;
CarpCacheShow('http://example.com/videos.rss');
?>

The following code sorts Slashdot's feed by the number of comments attached to each item and displays only the title link and the number of comments. Note that it is not necessary to call CarpMapField to display the comment count because this plugin automatically maps "slash:comments" (the sort field) to "sortslash:comments" (which you see specified in the "iorder" setting):

<?php
require_once '/YOUR/PATH/TO/carp/carp.php';
CarpLoadPlugin('sort.php');
SortCarpByOneElement('slash:comments','descending');
CarpConf('iorder','link,sortslash:comments');
function ShowCommentCount($initem,$fn,$ii,$in,$va,$rv) {
   global $carpconf;
   return 'Comments: '.($carpconf['rssparser']->GetFieldValue('sortslash:comments')).'<br />';
}
CarpRegisterCallback('','ShowCommentCount','handlefield','sortslash:comments');
CarpCacheShow('http://slashdot.org/index.rss');
?>

Home | About Us | Contact

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