CaRP: a caching RSS parser CaRP Evolution API
The extendable version of CaRP: caching RSS parser
 
CaRP Evolution allows plugins to register callback functions for various stages of the processing of an RSS newsfeed. The API for registering callbacks, and the arguments that will be sent to your callback functions are described below.
 
You may use accesskeys.php as a starting point for developing your own plugins. Further documentation and recommendations for plugin development will be added in the future.
 
Registering Callbacks
Register your callback functions like this:
CarpRegisterCallback($object, $function_name, $phase, $option);
  1. $object - If your plugin is object-oriented, pass an actual object instance here. Otherwise, pass an empty string ("" or '').
  2. $function_name - Pass the function or object method name of the callback function here.
  3. $phase - Pass the name of the phase of CaRP's processing where you want your callback function called here. The phases, and the value of any options you may pass in $option for each are:
    • startelement - Called whenever the XML parser starts parsing a new element of the RSS file. $option - You may optionally specify the name of an element, or a regular expression to match the name. If you do, yor callback will only be called when the name matches. The element names will be in the form IMAGE^WIDTH, for example, for the WIDTH child element of an IMAGE element. Any enclosing elements up to and including the CHANNEL element for children of the channel, or ITEM element for children of an item will NOT be included in the name. The callback will be told whether it is inside an item or not, so you will be able to tell the difference between channel and item elements.
    • endelement - Called whenever the XML parser finishes parsing a new element of the RSS file. $option - You may optionally specify the name of an element, or a regular expression to match the name, as with startelement.
    • characterdata - Called whenever the XML parser passes data from between XML tags to CaRP. $option - You may optionally specify the name of an element, or a regular expression to match the name, as with startelement.
    • outputfield - Called whenever CaRP is about to output some data. $option - Optionally, you may specify a field name to only have your function called when processing that field. The field name must be one of the valid values for CaRP's corder or iorder configuration variables (link, desc, url, image, etc.)
    • handlefield - Similar to outputfield, but used with custom field names which have been registered with CaRP using the CarpMapField function. $option - Indicate the name of the custom field.
    • displaychannel - Called just before CaRP displays the channel section of the newsfeed. $option - n/a
    • displayitem - Called just before CaRP displays a newsfeed item. $option - n/a
    • startprocessing - Called a little after CarpShow, CarpFilter or CarpAggregate is called, but before the remote newsfeed is loaded. $option - n/a
    • endprocessing - Called Just before CarpShow, CarpFilter or CarpAggregate completes. $option - n/a
    • carpconfreset - Called whenever CarpConfReset is called, just after CaRP's configuration has been reset to its default values, but before any of them have been overridden if the user has a carpconf.php file. $option - n/a
  4. $option - See the options listed for each $phase above.
You may unregister a callback you have previously registered ike this:
CarpUnregisterCallback($object, $function_name, $phase, $option);
The arguments to this function are the same as for CarpRegisterCallback, but $phase and $option are both optional. If $phase is omitted or blank, the callback will be unregistered for all phases. If $option is ommitted or blank, the callback will be unregistered for all values of the option.
 
Access CaRP Internal Data & Functions
During the callback phases startelement, endelement, characterdata, outputfield, handlefield, displaychannel and displayitem, $carpconf['rssparser'] contains the RSS parser object that is parsing the newsfeed. The following functions and data structures are available for access by your plugin. All others should be considered private and subject to change without notice.
  • $carpconf['rssparser']->GetFieldValue($fieldname); This function returns the value of whichever RSS field is the highest priority field mapped to the internal field name named by $fieldname which contains a value. For example, $carpconf['rssparser']->GetFieldValue('DATE'); may return a value from the RSS pubDate or DC:DATE field, depending on which one the RSS feed contains.
  • $carpconf['rssparser']->SetItemOrder($itemorder); This functions takes a comma-separated list of fields (the value of $carpconf['iorder']) and determines which fields will be displayed, and in what order, in an item.
  • $carpconf['rssparser']->ivalues: This is an array containing the raw contents of the fields of an item. Depending on which phase the callback is for, this data will be more or less complete. The array indices are in the format described as described in the "startelement" section above.
  • $carpconf['rssparser']->cvalues: This is an array containing the raw contents of the fields for the channel.
 
Callback Function Prototypes
The prototypes for your callback functions will differ depending on the phase for which they are registered, as follows:
  • StartElementCallback($initem, $fulltagname, $attributes)
    1. $initem - 0 if not inside an item, greater than zero otherwise
    2. $fulltagname - a string indicating the heirarchy of elements, as described in the section above
    3. $attributes - an associative array listing any attributes of the element
    Return value: n/a
  • EndElementCallback($initem, $fulltagname)
    1. $initem - 0 if not inside an item, greater than zero otherwise
    2. $fulltagname - a string indicating the heirarchy of elements, as described in the section above
    Return value: n/a
  • CharacterDateCallback($initem, $fulltagname, $data)
    1. $initem - 0 if not inside an item, greater than zero otherwise
    2. $fulltagname - a string indicating the heirarchy of elements, as described in the section above
    3. $data - the data passed from the XML parser to CaRP
    Return value: n/a
  • OutputFieldCallback($initem, $fieldname, $itemindex, $itemnumber, $value)
    1. $initem - 0 if not inside an item, greater than zero otherwise
    2. $fieldname - the name of the field (as listed in corder or iorder)
    3. $itemindex - 0 for the first item being displayed, 1 for the second, etc. Items that are skipped ARE counted.
    4. $itemnum - 0 for the first item in the RSS feed, 1 for the second, etc. Items that are skipped because of filtering are NOT counted.
    5. $value - the value which CaRP is about to output.
    Return value: Return $value after making any desired changes.
  • HandleFieldCallback($initem, $fieldname, $itemindex, $itemnumber, $valuearray, $returnvalue)
    1. $initem - 0 if not inside an item, greater than zero otherwise
    2. $fieldname - the name of the field (as listed in corder or iorder)
    3. $itemindex - 0 for the first item being displayed, 1 for the second, etc. Items that are skipped ARE counted.
    4. $itemnum - 0 for the first item in the RSS feed, 1 for the second, etc. Items that are skipped because of filtering are NOT counted.
    5. $valuearray - an associative array contain the raw data from the current item or the channel, depending on the value of $initem. The keys are the heirarchical names of the fields, as described in the previous section.
    6. $returnvalue - the value which CaRP is about to output. If only one callback is handling this field, this field will originally be empty. If multiple callbacks are handling the same field, the field may contain a value set by a prior callback.
    Return value: Return $returnvalue after making any desired changes.
  • DisplayChannelCallback()
    Return value:
    • -1: Don't display this newsfeed at all
    • 0: Don't display the channel information, even if indicated by corder, but continue with the newsfeed items
    • 1: Proceed as usual
  • DisplayItemCallback($itemindex, $itemnumber)
    1. $itemindex - 0 for the first item being displayed, 1 for the second, etc. Items that are skipped ARE counted.
    2. $itemnum - 0 for the first item in the RSS feed, 1 for the second, etc. Items that are skipped because of filtering are NOT counted.
    Return value:
    • -1: Don't display this item or any after it
    • 0: Don't display this item
    • 1: Proceed as usual
  • StartProcessingCallback($functionname, $url)
    1. $functionname - The name of the function that was called: CarpShow, CarpFilter, or CarpAggregate.
    2. $url - The address of the newsfeed to be processed.
    Return value: n/a
  • EndProcessingCallback($functionname)
    1. $functionname - The name of the function that was called: CarpShow, CarpFilter, or CarpAggregate.
    Return value: n/a
  • CarpConfResetCallback()
    Return value: n/a
Purchase CaRP Evolution on the CaRP Homepage
CaRP Evolution Plugins
CaRP Evolution API Documentation