CaRP: Caching RSS Parser - Configuration Manual: Display Formatting

CaRP: Caching RSS Parser - Manual
Version 3.5.4 (10/7/2004)

NOTE: This version of CaRP is obsolete. This documentation is being left here for those who have not yet upgraded to the current version.

Old documentation: Version 2

Configuration
Configuration is done by changing the values in the array $carpconf. You may change the defaults by modifying carp.php itsself. You may override the defaults for a particular RSS feed by inserting lines like "CarpConf('cachepath','/my/private/cache/path');" after the line where you "require_once" CaRP, and before calling CarpShow().

The following options are defined in $carpconf, and are color-coded based on the likelihood that you'll want to change them, as follows: usually changed, often changed, sometimes changed, rarely changed

Naming conventions:
The configuration settings for many display related items contain the following abbreviations:

b: "before"
a: "after"
c: "channel"
i: "item"
trunc: "truncate" or "truncated"

Newsfeed Anatomy:
An RSS feed is divided into two main sections: the channel section and the items.

» Channel:
The channel section contains information about the newsfeed itsself. CaRP supports the display of the following channel fields (the names in bold are CaRP's names for the fields, which may be different from the field names specified in the RSS feed). Note that not all fields will be included in every newsfeed:

image: an image or logo associated with the newsfeed (CaRP Koi and CaRP Evolution only).
title: the title of the newsfeed.
url: the address of the web page that the newsfeed is associated with.
link: the link field is a combination of the title and url fields--the title is displayed as a clickable link to the associated website.
date: the date the newsfeed was last published (CaRP Koi and CaRP Evolution only).
desc: a description of the newsfeed.

Data from the channel section can be displayed before and/or after the items in the newsfeed. For example, you could display the channel image before the items, and the channel link below the items. When using the functions CarpFilter and CarpAggregate to combine multiple newsfeeds, channel data can be displayed before and/or after each item to show which newsfeed it is associated with.

To specify which channel fields you wish to display before the items, do the following (using whichever of the field names you wish to display):

CarpConf('cborder','image,link,desc');

This example will display the channel image, link and description, in that order, before the newsfeed items. To specify channel fields to display after the items, change "cborder" to "caorder" ("channel before order" and "channel after order").

» Items:
The newsfeed items contain the individual news summaries, blog entries, or whatever the content of the newsfeed is. CaRP supports the display of the following channel fields:

image: an image or logo associated with the item (CaRP Koi and CaRP Evolution only).
title: the title or headline of the item.
url: the address of the web page that the item is associated with--often the full version of a story introduced in the newsfeed item.
link: the link field is a combination of the title and url fields--the title is displayed as a clickable link to the associated website.
date: the date the item was published (CaRP Koi and CaRP Evolution only).
author: the author of the item (CaRP Koi and CaRP Evolution only).
desc: a description of the item--often a summary of a longer story that can be found by following the link.

To specify which channel fields you wish to display before the items, do the following (using whichever of the field names you wish to display):

CarpConf('iorder','link,author,date,desc');

Controlling the Appearance of the Newsfeed:
Configuration options are shown in [square braces]. Default values are already set for each of these options, so you only need to set those you wish to change.

» Channel:
Except as noted, the following settings apply to the channel items, whether displayed before ("cborder") or after ("caorder") the items.

[bcb]			"before channel before": Insert any text or HTML you wish to have appear before the channel section which appears before the items ("cborder") here (use "bca" ("before channel after") for the section that appears after the items ("caorder"). For example, you may use a command like CarpConf('bc','<span style="Font-Family:Arial,sans-serif">'); to set the font of the channel section. If you do this, be sure to use a command like CarpConf('ac','</span>'); below to match the opening tag. If you want to set the same font (or other setting) for the entire newsfeed rather than just the channel section, you do not need to use CaRP settings to do that. Instead, simply insert the appropriate HTML formatting before the part of your webpage where you use CaRP.
	[bcimage]<a href="image link" target="[linktarget]"><img src="image source" height="image height or [setcimageh or defcimageh or maxcimageh]" width="image width or [setcimagew or defcimagew or maxcimagew]" border="0" alt="image alt text"></a>[acimage]		If the newsfeed does not specify image dimensions and defcimagew (default channel image width) and/or defcimageh (default channel image height) are set, the defaults are used. Otherwise, no dimensions are specified, and the image is displayed in its actual dimensions. If maxcimagew (maximum channel image width) and/or maxscimageh (maximum channel image height) are set and the newsfeed specifies image dimensions, the image dimensions are reduced as necessary. When either dimension is reduced, the other is reduced by the same percentage to maintain the proper aspect ratio. If setcimagew (set channel image width) and/or setcimageh (set channel image height) are set, the other settings are ignored and the image is scaled to the specified dimensions. If only one of the two is set, the other is scaled by the same percentage to maintain the proper aspect ratio.
	[bctitle]		"before channel title"
		<a href="channel link" class="[clinkclass]" style="[clinkcstyle]" title="channel title" target="[linktarget]">channel title[atruncctitle]</a>	"channel link class", "channel link style", "channel link target", and "after truncated channel title": If clickclass is blank, the 'class="[clinkclass]"' section will be omitted. The same is true for clinkstyle. If the channel title is truncated by the maxctitle (maximum channel title length) setting (see below), atruncctitle will be added to the end of the remaining portion of the channel title. See below for more information about linktarget.
		- or -	If corder (described above) contains "link", the above is displayed. If it contains "title", the following is displayed.
		<span class="[clinkclass]" style="[clinkcstyle]">channel title[atruncctitle]</span>	"channel link class", "channel link style", "after truncated channel title": See notes above.
	[actitle]		"after channel title"
		[bcdate]date[acdate]	"before channel date", "after channel date": The format of the date is controlled by the cdateformat option (see below). If the "pubdate" and "dc:date" fields are both blank, this section will be omitted.
		[bclink]date[aclink]	"before channel link", "after channel link": If no channel link is specified in the newsfeed, this section will be omitted.
	[bcdesc]channel description[atrunccdesc][acdesc]		"before channel description", "after truncated channel description", "after channel description": If the channel description is truncated by the maxcdesc (maximum channel description length) setting (see below), atrunccdesc will be added to the end of the remaining portion of the channel description. If the channel description is blank, this section will be omitted.
[acb]			"after channel before", or "aca" ("after channel after") (see "bcb" above)

» Items:
The following settings apply to the items section of the newsfeed. The order in which the item fields are displayed is controlled by the iorder setting, as described above.

[bitems]			"before items": this appears once before the list of items
The following section is repeated once for each news item displayed.
	[bi]		"before item": You could use this item to create a bulleted list by using the command CarpConf('bi','• '); Or, you could use the commands CarpConf('bitems','<ul>');, CarpConf('aitems','</ul>'); and CarpConf('bi','<li>'); to create an indented bulleted list.
	[biimage]<a href="image link" target="[linktarget]"><img src="image source" height="image height or [setiimageh or defiimageh or maxiimageh]" width="image width or [setiimagew or defiimagew or maxiimagew]" border="0" alt="image alt text"></a>[aiimage]		See the notes above for the channel image.
		[bilink]	"before item link"
		<a href="item link" class="[ilinkclass]" style="[ilinkstyle]" title="title" target="[linktarget]">title[atruncititle]</a>	"item link class", "item link style", "item link target", "after truncated item title": See the channel title section above for details on display of the item link or title.
		[ailink]	"after item link"
		[biauthor]author[aiauthor]	"before item author", "after item author" If the "author" and "dc:creator" fields are both blank, this section will be omitted.
		[bidate]date[aidate]	"before item date", "after item date": The format of the date is controlled by the idateformat option (see below). If the "pubdate" and "dc:date" fields are both blank, this section will be omitted.
		[bilink]date[ailink]	"before item link", "after item link": If no item link is specified in the newsfeed, this section will be omitted.
		[bidesc]idesc[atruncidesc][aidesc]	"before item description", "after truncated items description", "after item description": See the channel description section above for details, subtituting maxidesc and atruncidesc for maxcdesc and atrunccdesc.
	[ai]		"after item"
End of section repeated once for each news item.
[aitems]			"after items": this appears once after the list of items
[poweredby]			By default, this displays the message "Newsfeed formatting by CaRP" with a link to our site. If you remove this link, we would very much appreciate your posting a similar link somewhere on your website.

Additional Display Settings:
The following options also affect the display format and behavior of links:

linktarget: 1 to open a new window when someone clicks a link, 2 to open in the same window, but ensure that it is not in a frame, 0 to follow the link in the current window (and frame, if in a frame set), or the name of the frame in which to open the link if in a frameset (NOTE: the name of the frame must contain at least one character that is not a digit).
maxctitle: The maximum length for the channel title. If it is longer, it will be truncated and have atruncctitle added to it (see above).
clinktitles: 1 (the default) to add a "title" element to the channel link, containing the entire channel title, if it has been truncated because it was longer than maxctitle. The purpose of this is to display the entire title as a "tool tip" if it has been trucated. If set to 2, the title element will be inserted whether the title is truncated or not. If set to 0, it will never be inserted.
maxcdesc: The maximum length for the The maximum length for the channel description or 0 to display everything. If it is longer, it will be truncated and have atrunccdesc added to it (see above).
maxitems: The maximum number of items to show--if the RSS feed contains more items, the rest will be discarded.
maxititle: The maximum length for the the item titles (they will be truncated and have atruncititle added to them if they are longer).
ilinktitles: The same as clinktitles (see above), but for the item titles.
defaulittitle: The text to display if a particular item does not have a title
maxidesc: The maximum number of characters to display from the description field, or 0 to display everything. If it is longer, it will be truncated and have atruncidesc added to it (see above).
idateformat: This setting determines the format of the date/time. See this page in the PHP manual for more information.