CaRP: Caching RSS Parser - Documentation

CarpRegisterCallback( object, function, phase [, option [, first]] );

Register a callback function with CaRP Evolution

Evolution	LE	Koi	SE
All	n/a	n/a	n/a

Description:
This function is used primarily by plugins to register their functions with CaRP. CaRP will then call those functions at specific points during newsfeed processing.

Arguments:

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.
   • getfieldvalue - [CaRP >= 4.0] Called when a specific piece of data from the feed is being requested. option - You may optionally specify the name of the field, which may be one of CaRP's internal field names, or one added using CarpMapField.
   • outputfield - Called whenever CaRP is about to output a piece of 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 cborder/caorder 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 while displaying a single feed using CarpCacheShow or CarpShow, or before processing an item when using CarpGroupFilter, CarpCacheFilter or CarpFilter. option - n/a
   • aggregateitem - Called just before CaRP displays a newsfeed item while aggregating multiple feeds using CarpAggregate or CarpInterleave. option - n/a
   • output - [CaRP >= 4.0.3] Called when CaRP is about to either echo data to the web browser or add it to $carpoutput. 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
   • cachemiss - Called the next time CaRP has to load a remote feed because the a processed version of the feed wasn't found in its cache. If no manual cache filename was specified, this function will be called. Functions registered for this phase are automatically unregistered after they've been called once. Use this phase to load plugins and perform configuration that is only necessary when not pulling a feed from the manual cache. option - n/a
4. option - See the options listed for each phase above.
5. first - [CaRP Evolution >= 4.0.12] Set to 1 to add this callback to the beginning of the list of callbacks for this phase (so that it's called first). By default, callbacks are added to the end. If your callback does not need to be called before other callbacks for any reason, use the default value. If additional callbacks are registered after this one and they set first to 1, they will be called before this one.

Return value: none

Usage Example: Refer to one of the plugins included with CaRP Evolution for an example.

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
• CharacterDataCallback($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
• GetFieldValueCallback($initem, $fieldname, $value)
  
  1. $initem - 0 if not inside an item, greater than zero otherwise
  2. $fieldname - the name of the field (as listed in cborder/caorder or iorder)
  3. $value - the value for that field that was taken from the feed
  Return value: $value, modified as desired
• 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 cborder/caorder 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 cborder/caorder 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 cborder or caorder, 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
• AggregateItemCallback($itemindex, $itemnumber, $key, $data)
  
  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.
  3. $key - a key used by CaRP when aggregating feeds. Its value is usually the UNIX timestamp for the item plus a decimal part less than zero.
  4. $data - the content of the item as it was formatted by the filter function (CarpGroupFilter, etc.)
  Return value:
  • -1: Don't display this item or any after it
  • 0: Don't display this item
  • 1: Proceed as usual
  • any text: Display the return value instead of $data and then continue as usual.
• OutputCallback($data)
  
  1. $data - the data that is about to be displayed. It may be either an array of single lines or a string, and callback functions must be able to detect the difference and handle either.
  Return value: The data to be output: Either an array of lines or a string.
• StartProcessingCallback($functionname, $url, $continuing)
  
  1. $functionname - The name of the function that was called: CarpShow, CarpFilter, or CarpAggregate.
  2. $url - The address of the newsfeed to be processed.
  3. $continuing [CaRP >= 4.0.5] - 1 if no other plugins have told CaRP not to continue processing after processing all the callbacks for this phase. 0 if any plugins have cancelled further processing.
  Return value: n/a for CaRP version 4.0.4 and earlier. Beginning with 4.0.5, return -1 to cancel further processing, or anything else to continue.
• EndProcessingCallback($functionname, $continued)
  
  1. $functionname - The name of the function that was called: CarpShow, CarpFilter, or CarpAggregate.
  2. $continued [CaRP >= 4.0.5] - 1 if no callbacks in the startprocessing phase told CaRP to cancel further processing, and 0 if any did.
  Return value: n/a
• CarpConfResetCallback()
  Return value: n/a
• CacheMissCallback()
  Return value: n/a

Home | About Us | Contact

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