SimplePie Plugin for WordPress

The latest version of this plugin has been completely re-written from scratch as a full-scale WordPress plugin, and includes several new features including:

• A configuration pane under the Options tab in the WordPress software.
• “Multifeeds” support.
• MUCH better control over the plugin’s output. Supports a simple templating system that allows:
  • Simple, easy-to-use tags for nearly every piece of data that SimplePie can output.
  • Support for multiple templates.
  • Global configuration of default values for several configuration options.
  • Ability to override the defaults for any given feed — including giving a feed it’s own output template.
• No need to manually set up cache folders.
• Support for internationalized domain names.
• Support for short descriptions is configurable.
• And more!

These instructions assume that you have a basic familiarity with PHP and know how to add a line of PHP code to your own WordPress templates. If you don't, and you're just getting started, we would suggest you take a look at the following documentation and tutorials:

• Introduction to PHP tutorial
• PHP for Beginners
• WordPress: Blog Design and Layout
• WordPress: Theme Development
• WordPress: Customizing your Sidebar

1. Delete all traces of the previous version of the plugin (specifically deleting simplepie_wordpress.php).
2. Wherever you've called SimplePieWP(), you'll likely end up deleting the options you've already set, or converting them to the updated array syntax for setting per-feed options. These new options are discussed below.

There's a link above to download the SimplePie Plugin for WordPress, which already includes the latest release version of SimplePie. When you download them, make sure you know where you've downloaded them to. Once you've done that, unzip them.

The simplepie_wordpress_2 folder should be uploaded as-is to your WordPress installation, so that it ends up as wp-content/plugins/simplepie_wordpress_2.

Log into your WordPress control panel, go to “plugins”, and enable the SimplePie Plugin for WordPress plugin. If you need more help installing WordPress plugins, check out the WordPress plugin installation instructions. From there, you can go to the new Options → SimplePie panel and configure your default settings.

The SimplePie Plugin for WordPress is now installed!

Usage of this plugin has changed radically since version 1.2.x. First off, there's a new options panel that lets you configure your default settings – meaning the settings that SimplePie will obey unless instructed otherwise. This makes things much simpler as you can configure multiple SimplePie instances directly from the options panel.

Let's start with something basic:

<?php echo SimplePieWP('http://simplepie.org'); ?>

This code sample will display the feed using all of the default settings. If you ever want to change the settings for this feed, you could do everything directly from the options panel, as we're not overriding any settings in this example.

We're also utilizing SimplePie's built-in auto-discovery feature to discover the feed for this particular website even though we only entered the website address.

Additionally, you can override the default settings for any specific SimplePie instance by passing parameters directly to the SimplePieWP() function. Here is an example of what passing parameters could look like:

<?php
echo SimplePieWP('http://simplepie.org', array(
	'items' => 5,
	'cache_duration' => 1800,
	'date_format' => 'j M Y, g:i a'
));
?>

In the above example, we've chosen to accept ALL of the default settings (configured in the options panel), but we've overridden the number of items to display, the number of seconds to cache the feed for, and the date formatting on a per-feed basis.

NOTE: Notice that the value for items is a number (specifically an integer), and is not quoted.

As if all of this wasn't enough, the new version of the plugin also supports what we affectionately call “Multifeeds”. This is where you can merge multiple feeds together and sort the items by time and date (sorting by date requires individual items to have a date associated with them). Using Multifeeds is as simple as passing in an array of URLs instead of a single URL:

<?php
echo SimplePieWP(array(
	'http://feeds.feedburner.com/simplepie',
	'http://laughingmeme.org/category/magpie/feed/'
), array(
	'items' => 5,
	'cache_duration' => 1800,
	'date_format' => 'j M Y, g:i a'
));
?>

If you want to override the default settings on a per-feed basis, these are the options that you can set. You would only use these if you want to override the settings from the options panel.

• 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.
• locale – [String] The locale value to use for displaying localized datestamps.
• local_date_format – [String] The format to use for localized dates.
• 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}.

Another major new feature in this release 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.

• {FEED_AUTHOR_EMAIL} – [SP 1.1] Same as $feed->get_author(0)->get_email().
• {FEED_AUTHOR_LINK} – [SP 1.1] Same as $feed->get_author(0)->get_link().
• {FEED_AUTHOR_NAME} – [SP 1.1] Same as $feed->get_author(0)->get_name().
• {FEED_CONTRIBUTOR_EMAIL} – [SP 1.1] Same as $feed->get_contributor(0)->get_email().
• {FEED_CONTRIBUTOR_LINK} – [SP 1.1] Same as $feed->get_contributor(0)->get_link().
• {FEED_CONTRIBUTOR_NAME} – [SP 1.1] 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_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_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} – [SP 1.1] Same as $item->get_contributor(0)->get_email().
• {ITEM_CONTRIBUTOR_LINK} – [SP 1.1] Same as $item->get_contributor(0)->get_link().
• {ITEM_CONTRIBUTOR_NAME} – [SP 1.1] Same as $item->get_contributor(0)->get_name().
• {ITEM_COPYRIGHT} – [SP 1.1] 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_EMBED} – Same as $item->get_enclosure(0)->native_embed().
• {ITEM_ENCLOSURE_EXTENSION} – Same as $item->get_enclosure(0)->get_extension().
• {ITEM_ENCLOSURE_HANDLER} – Same as $item->get_enclosure(0)->get_handler().
• {ITEM_ENCLOSURE_LENGTH} – Same as $item->get_enclosure(0)->get_length().
• {ITEM_ENCLOSURE_LINK} – Same as $item->get_enclosure(0)->get_link().
• {ITEM_ENCLOSURE_REAL_TYPE} – Same as $item->get_enclosure(0)->get_real_type().
• {ITEM_ENCLOSURE_SIZE} – Same as $item->get_enclosure(0)->get_size().
• {ITEM_ENCLOSURE_TYPE} – Same as $item->get_enclosure(0)->get_type().
• {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.

When processing a single feed, SimplePie stores information about that feed and makes it available via {FEED_*} tags like {FEED_TITLE} for instance. When you process multiple feeds all at once (via Multifeeds), there isn't a single feed to return data for – instead there are multiple feeds with conflicting data.

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.

SimplePie assumes that the default WordPress cache folder is writable (which it normally is). If this isn't the case for you, you'll need to change the file permissions for the wp-content/cache directory to be server-writable.

This setting varies from web host to web host. In the past, I've used iPowerWeb, and they required file permissions of 777 in order to be server-writable. Currently, I use Dreamhost, and they need permissions to be set to 755 to be server-writable. Again, if you're not sure, either go ask your host or you can try various settings yourself. The three to try are 755, 775, or 777.

The specific process of how you change your file permissions differs from FTP application to FTP application. On Windows I use FlashFXP, where you find the remote file or folder that you want to change the permissions of, you right-click on it, and choose Attributes (CHMOD). On Mac OS X I use Transmit, where you find the remote file or folder that you want to change the permissions of, you right-click (or ctrl-click for you one-button-mousers) on it, and choose Get Info. Your specific FTP application will most likely be something similar.