CaRP Evolution Documentation
CaRP Evolution Documentation
twitter youtube linkedin google-plus
CaRP Evolution Box
Web This Site

CaRP: Caching RSS Parser - Documentation

CaRP Interactive FAQ
Getting Started: Free Download | Purchase | Install
Reference: Functions | Plugins | Themes | Full Index
Etc.: Display Formatting | Example Code | Affiliates

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

Register a callback function with CaRP Evolution
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.

  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: