SimplePie 1.5 is now available!

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

This is an old revision of the document!


SimplePie Plugin for WordPress

The Basics

Main page SimplePie Plugin for WordPress
Author Ryan Parman
Plugin Version 2.0
Compatible WordPress version 2.x
Download Download
Required SimplePie version 1.x
Optional Helpers PHPExec, Exec-PHP
Plugin Support http://simplepie.org/support/viewforum.php?id=14

About the Plugin

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!

What Do I Need To Know?

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:

Installation

Upgrading from an older version?

  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.

Fresh Installation

Step 1: Download the plugin above

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.

Step 2: Upload the entire plugin folder to your WordPress plugins directory

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.

Step 3: Enable the plugin in your WordPress control panel

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

Getting Started

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.

Overriding Settings

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.

Multifeeds

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'
));
?>

Usage Details

Override Settings

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

Template Tags

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

Item Looping Tags

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

Item-Level Tags to be used with Multifeeds

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.

Troubleshooting

Cache Error

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.


plugins/wordpress/simplepie_plugin_for_wordpress.1191828601.txt.gz · Last modified: 2011/03/06 03:56 (external edit)