SimplePie 1.3.1 is now available. Upgrade now!

SimplePie Documentation.  Learn how to use this thing.  It's way better than going to school.

You are here: Documentation » SimplePie Plugins and Integration » WordPress » SimplePie Plugin for WordPress » Customization

Customization

Nearly every aspect of SimplePie Plugin for WordPress is customizable. You can create multiple templates, customize those templates, choose the settings that work best for you, and even edit and alter the feed data after it's read from the feed but before it's displayed on the page! These are the customization options available as of the latest version of the plugin.

Navigation

Per-Feed Settings

If you want to override the default settings on a per-feed basis, these are the options that you can set (as discussed in Getting Started: Overriding Settings (Basic)). You would only use these if you want to override the settings from the options panel.

OPTION/ATTRIBUTE DATATYPE DESCRIPTION
date_format string The date format to use for English dates. Supports anything that PHP's date() function.
enable_cache boolean Whether the given feed should be cached or not.
enable_order_by_date boolean Whether to force-reorder items into chronological order. Only works when items have dates associated with them.
items integer The number of feed items to display. Will display this value, or all of the items in the feed – whichever is less.
items_per_feed integer The number of feed items to display per-feed (e.g. setting this to 3 will only merge 3 items from each feed). Only works when merging multiple feeds and obeys the items setting.
locale string The locale value to use for displaying localized datestamps.
local_date_format string The format to use for localized dates.
processing string The file to use for post-processing the feed. Can use the name of any process listed in the options panel, preferably lowercased with spaces replaced by underscores.
set_cache_duration integer The number of seconds to consider the cache file fresh.
set_max_checked_feeds integer When using auto-discovery, this is the number of links to check for the existence of a feed.
set_timeout integer The number of seconds to wait for a remote website while fetching a feed.
strip_attributes string A space-delimited list of HTML attributes to remove from the feed's content.
strip_htmltags string A space-delimited list of HTML tags to remove from the feed's content.
template string The template to use for displaying the feed. Can use the name of any template listed in the options panel, preferably lowercased with spaces replaced by underscores.
truncate_feed_description integer The number of characters to shorten the feed's description to. Only used with {TRUNCATE_FEED_DESCRIPTION} and {TRUNCATE_ITEM_PARENT_DESCRIPTION}.
truncate_feed_title integer The number of characters to shorten the feed's title to. Only used with {TRUNCATE_FEED_TITLE} and {TRUNCATE_ITEM_PARENT_TITLE}.
truncate_item_description integer The number of characters to shorten the item's description to. Only used with {TRUNCATE_ITEM_DESCRIPTION}.
truncate_item_title integer The number of characters to shorten the item's title to. Only used with {TRUNCATE_ITEM_TITLE}.

Template Tags

Another major feature is that instead of being locked into a single, simple layout, you can create your own layouts in the form of templates. The following is a list of template tags you can use. Feel free to take a look at the ones that were supplied in the templates folder.

Plugin Tags

These are tags that are related to the plugin, but not necessarily anything with the SimplePie API.

{PLUGIN_DIR} Returns the web URL of the SimplePie plugin directory. This is useful for linking to images or other files that are stored inside the SimplePie plugin directory.

Error Tags

These tags are used for displaying error messages.

{IF_ERROR_BEGIN} Marks the beginning of where the error message would display if there was one.
{IF_ERROR_END} Marks the end of where the error message would display.
{ERROR_MESSAGE} The error message that SimplePie throws.

Feed/Anywhere-Level Tags

These tags can be used anywhere in the template.

{FEED_AUTHOR_EMAIL} Same as $feed->get_author(0)->get_email().
{FEED_AUTHOR_LINK} Same as $feed->get_author(0)->get_link().
{FEED_AUTHOR_NAME} Same as $feed->get_author(0)->get_name().
{FEED_CONTRIBUTOR_EMAIL} Same as $feed->get_contributor(0)->get_email().
{FEED_CONTRIBUTOR_LINK} Same as $feed->get_contributor(0)->get_link().
{FEED_CONTRIBUTOR_NAME} Same as $feed->get_contributor(0)->get_name().
{FEED_COPYRIGHT} Same as $feed->get_copyright().
{FEED_DESCRIPTION} Same as $feed->get_description().
{FEED_ENCODING} Same as $feed->get_encoding().
{FEED_FAVICON} Same as $feed->get_favicon().
{FEED_IMAGE_HEIGHT} Same as $feed->get_image_height().
{FEED_IMAGE_LINK} Same as $feed->get_image_link().
{FEED_IMAGE_TITLE} Same as $feed->get_image_title().
{FEED_IMAGE_URL} Same as $feed->get_image_url().
{FEED_IMAGE_WIDTH} Same as $feed->get_image_width().
{FEED_LANGUAGE} Same as $feed->get_language().
{FEED_LATITUDE} Same as $feed->get_latitude().
{FEED_LONGITUDE} Same as $feed->get_longitude().
{FEED_PERMALINK} Same as $feed->get_permalink().
{FEED_TITLE} Same as $feed->get_title().
{SUBSCRIBE_URL} Same as $feed->subscribe_url().
{TRUNCATE_FEED_DESCRIPTION} Same as $feed->get_description() except that it obeys the appropriate “truncate text” setting.
{TRUNCATE_FEED_TITLE} Same as $feed->get_title() except that it obeys the appropriate “truncate text” setting.

Item Looping Tags

These tags mark the beginning and end of items.

{ITEM_LOOP_BEGIN} Marks the beginning of where we should begin looping through items.
{ITEM_LOOP_END} Marks the end of where we should stop looping through items.

Item-Level Tags

These are tags that can be used inside the item loop. These will NOT work outside of the item loop and there will be a PHP error if you try.

{ITEM_AUTHOR_EMAIL} Same as $item->get_author(0)->get_email().
{ITEM_AUTHOR_LINK} Same as $item->get_author(0)->get_link().
{ITEM_AUTHOR_NAME} Same as $item->get_author(0)->get_name().
{ITEM_CATEGORY} Same as $item->get_category(0)->get_label().
{ITEM_CONTENT} Same as $item->get_content().
{ITEM_CONTRIBUTOR_EMAIL} Same as $item->get_contributor(0)->get_email().
{ITEM_CONTRIBUTOR_LINK} Same as $item->get_contributor(0)->get_link().
{ITEM_CONTRIBUTOR_NAME} Same as $item->get_contributor(0)->get_name().
{ITEM_COPYRIGHT} Same as $item->get_copyright().
{ITEM_DATE} Same as $item->get_date().
{ITEM_DATE_UTC} Same as $item->get_date() except that a GMT/UTC timestamp is displayed.
{ITEM_DESCRIPTION} Same as $item->get_description().
{ITEM_ENCLOSURE_BITRATE} Same as $item->get_enclosure(0)->get_bitrate().
{ITEM_ENCLOSURE_CHANNELS} Same as $item->get_enclosure(0)->get_channels().
{ITEM_ENCLOSURE_DESCRIPTION} Same as $item->get_enclosure(0)->get_description().
{ITEM_ENCLOSURE_DURATION} Same as $item->get_enclosure(0)->get_duration().
{ITEM_ENCLOSURE_EMBED} Same as $item->get_enclosure(0)->native_embed().
{ITEM_ENCLOSURE_EXPRESSION} Same as $item->get_enclosure(0)->get_expression().
{ITEM_ENCLOSURE_EXTENSION} Same as $item->get_enclosure(0)->get_extension().
{ITEM_ENCLOSURE_FRAMERATE} Same as $item->get_enclosure(0)->get_framerate().
{ITEM_ENCLOSURE_HANDLER} Same as $item->get_enclosure(0)->get_handler().
{ITEM_ENCLOSURE_HASH} Same as $item->get_enclosure(0)->get_hash().
{ITEM_ENCLOSURE_HEIGHT} Same as $item->get_enclosure(0)->get_height().
{ITEM_ENCLOSURE_LANGUAGE} Same as $item->get_enclosure(0)->get_language().
{ITEM_ENCLOSURE_LENGTH} Same as $item->get_enclosure(0)->get_length().
{ITEM_ENCLOSURE_LINK} Same as $item->get_enclosure(0)->get_link().
{ITEM_ENCLOSURE_MEDIUM} Same as $item->get_enclosure(0)->get_medium().
{ITEM_ENCLOSURE_PLAYER} Same as $item->get_enclosure(0)->get_player().
{ITEM_ENCLOSURE_REAL_TYPE} Same as $item->get_enclosure(0)->get_real_type().
{ITEM_ENCLOSURE_SAMPLINGRATE} Same as $item->get_enclosure(0)->get_sampling_rate().
{ITEM_ENCLOSURE_SIZE} Same as $item->get_enclosure(0)->get_size().
{ITEM_ENCLOSURE_THUMBNAIL} Same as $item->get_enclosure(0)->get_thumbnail().
{ITEM_ENCLOSURE_TITLE} Same as $item->get_enclosure(0)->get_title().
{ITEM_ENCLOSURE_TYPE} Same as $item->get_enclosure(0)->get_type().
{ITEM_ENCLOSURE_WIDTH} Same as $item->get_enclosure(0)->get_width().
{ITEM_ID} Same as $item->get_id().
{ITEM_LATITUDE} Same as $item->get_latitude().
{ITEM_LOCAL_DATE} Same as $item->get_local_date().
{ITEM_LOCAL_DATE_UTC} Same as $item->get_local_date() except that a GMT/UTC timestamp is displayed.
{ITEM_LONGITUDE} Same as $item->get_longitude().
{ITEM_PERMALINK} Same as $item->get_permalink().
{ITEM_TITLE} Same as $item->get_title().
{TRUNCATE_ITEM_DESCRIPTION} Same as $item->get_description() except that it obeys the appropriate “truncate text” setting.
{TRUNCATE_ITEM_TITLE} Same as $item->get_title() except that it obeys the appropriate “truncate text” setting.

Newbie Note: Missing Data with Multifeeds

You're merging multiple feeds together and you try to access data from {FEED_TITLE} or {FEED_DESCRIPTION} but there doesn't seem to be anything. Let's say that you're merging together 3 feeds, each with their own titles, descriptions, etc. We'll use Digg, Slashdot, and Apple as examples. Digg has its own title, so does Slashdot, and so does Apple. If there are 3 competing pieces of data, what should {FEED_TITLE} return?

Well, put simply, SimplePie has no idea which data to show, so it doesn't display anything.

So what do we do? If you merge together a feed from Digg and a feed from Slashdot, some items will be from Digg while others are from Slashdot – obviously. As you narrow down a specific item, you can get the feed-level information for that specific item using {ITEM_PARENT_*} tags like {ITEM_PARENT_TITLE} for example.

To use these tags, simply replace the FEED part of each of the feed-level tags above with ITEM_PARENT. {FEED_TITLE} becomes {ITEM_PARENT_TITLE}, {FEED_DESCRIPTION} becomes {ITEM_PARENT_DESCRIPTION} and so on. These tags only work properly between the {ITEM_LOOP_BEGIN} and {ITEM_LOOP_END} tags.

This is used in a few of the sample templates that came bundled with the plugin, so feel free to check them out to get a better feel for how they're used.


plugins/wordpress/simplepie_plugin_for_wordpress/customization.txt · Last modified: 2011/03/05 19:56 (external edit)