CaRP: Caching RSS Parser - CarpRegisterCallback Function

CaRP: Caching RSS Parser - Documentation

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

GPL	Koi	Evolution
n/a	n/a	>=3.3

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:

object - If your plugin is object-oriented, pass an actual object instance here. Otherwise, pass an empty string ("" or '').
function_name - Pass the function or object method name of the callback function here.
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 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. 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
option - See the options listed for each phase above.

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
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 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
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