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

Author Ryan Parman
Version 1.2
Required SimplePie version Beta 3 (not 1.0-compatible)
Main page SimplePie Plugin for WordPress
Download http://simplepie.org/downloads/simplepie_wordpress.zip
Optional Helpers PHPExec, ExecPHP
Plugin Support SimplePie Support Forums

About the Plugin

This plugin does two things for WordPress.

  • First, it includes the necessary SimplePie library and pre-sets some configuration options.
  • Secondly, it makes the SimplePieWP() function available to you.

What Do I Need To Know?

These instructions assume that you have a basic familiarity with PHP, and know how to edit 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?

Replace the old simplepie_wordpress.php with the new one.

Fresh Installation

For the purposes of these instructions, we're going to make a few assumptions. We're going to assume that you have installed WordPress to http://blog.example.com, which would mean that the WordPress plugins folder lives at http://blog.example.com/wp-content/plugins/.

Step 1: Download both the required files above

When you download them, make sure you know where you've downloaded them to. Once you've done that, unzip them. The full SimplePie library is what powers everything, and the WordPress plugin simply makes it available to your WordPress templates.

Step 2: Upload both simplepie.inc and simplepie_wordpress.php to your WordPress plugins folder

This means that these two files will be uploaded to http://blog.example.com/wp-content/plugins/.

Step 3: Create a cache folder inside WordPress' plugins folder

This means that after you create the cache folder, it will live at http://blog.example.com/wp-content/plugins/cache/.

Step 4: Change the file permissions for the cache directory to be server-writable

This setting varies from webhost to webhost. 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.

Step 5: Enable the plugin in your WordPress control panel

Log into your WordPress control panel, go to “plugins”, and enable the SimplePie for WordPress plugin. If you need more help installing WordPress plugins, check out the WordPress plugin installation instructions.

SimplePie and the SimplePie Plugin for WordPress is now installed.

Usage

How to use it

SimplePie Plugin for WordPress adds one function to your WordPress installation: the SimplePieWP() function.

This function simply returns the data. It doesn't actually display it on the screen. To do that, you need to echo or print the function to the screen. For example:

// Wrong
SimplePieWP('http://example.com/feed.xml');
 
// Right
echo SimplePieWP('http://example.com/feed.xml');

Parameters

The SimplePieWP() function accepts 2 parameters:

feed_url

The first parameter is the feed URL. Only passing this will display the default way:

  • An <h3> containing the feed's title, linked back to the originating site.
  • An ordered list, containing all of the news items in the feed.
  • The news item's title, linked back to the originating post.
  • The full HTML description for each news item.

options

The second parameter is an array of keywords and values. For example:

echo SimplePieWP('http://example.com/feed.xml', array(
	'items': 5, 
	'shortdesc': 200, 
	'showdate': 'j M Y'
));

Below are the options that are supported:

  • items – Limits the number of items returned. If you set this value to 5, then you'll get back the 5 most recent posts. If there's a feed with fewer than 5 posts, SimplePie will return all of them. Defaults to all.
  • showdesc – Determines whether the description should be shown or not. If set to false, descriptions are omitted, and the ordered list will display only the linked item titles with no special formatting. Defaults to true.
  • showdate – Displays the date of the news item. Accepts anything that's allowed in PHP's date() function. Defaults to blank.
  • shortdesc – Strips all tags from the item's description and limits the number of characters that are displayed. Accepts any numeric value. If more characters are allowed than are in the description, the entire description will be displayed. If the text wasn't cut at the end of a sentence (ending with a period, exclamation point, or question mark), an ellipsis will be added to the end of the text. Defaults to all characters.
  • showtitle – Determines whether the built-in feed title is displayed or not. Defaults to true.
  • alttitle – Displays a custom title in place of the feed's built-in title. Defaults to blank.
  • error – Displays a custom error message for when there is a problem retrieving the feed. Defaults to the standard error messages.

If you want to apply special CSS styles to the feed display, here's some basic markup that represents what is generated.

<div class="simplepie">
    <h3><a href="http://example.com">Example Site</a></h3>
    <ol>
        <li><strong><a href="...">Item Title 1</a> <span class="date">29 May 2006</span></strong><br />
        The description for the item.</li>
 
        <li><strong><a href="...">Item Title 2</a> <span class="date">28 May 2006</span></strong><br />
        The description for the item.</li>
 
        <li><strong><a href="...">Item Title 3</a> <span class="date">27 May 2006</span></strong><br />
        The description for the item.</li>
    </ol>
</div>

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