描述

WordPress comes with a default RSS widget, but you get no control over how the feed shows up in your sidebar. Want more control? The KB Advanced RSS widget gives it to you. With it, you can

• Decide which RSS fields to display (as opposed to the default RSS widget, which limits you to link, title, and description);
• Decide how to format the fields (it doesn’t have to be a list if you don’t want it to be);

Be aware that it’s called “advanced” for a reason. You need to know some HTML to use this fully. Also, please note that this is a widget, so you need to be using a widgets-enabled theme.

Before upgrading to v2.8 of the plugin, read this: Because the WordPress developers dramatically re-wrote the widgets API in WP 2.8, I had to rewrite this plugin completely. Updating to v2.8 of the plugin will correct many annoying bugs. But, alas, it will also (most likely) cause you to lose all the options you may have set in a previous version of this plugin. Sorry. I don’t foresee this happening more than once.

Support

If you post your support questions as comments below, I probably won’t see them. If the FAQs don’t answer your question, you can post support questions at the KB Advanced RSS plugin page on my site.
Instructions

Background before we continue: Every RSS feed contains a number of items (e.g. headlines). Each item contains a variety of elements; at a minimum, each item usually has a title, a link, and a description. This plugin uses MagpieRSS (included) to grab and parse RSS feeds.

Example 1: Basic usage

To show how this widget works, let’s use it to parse an RSS feed in exactly the way that the default RSS widget does.
1. The default widget begins with <ul> (to make the feed items a list).
1. Then, it prints out the following line for each item in the feed: <li><a href="LINK" title="DESCRIPTION">TITLE</a></li>.
1. Finally, it closes the feed with </ul> (to end the list).

By default, the KB Advanced RSS widget will do exactly the same thing. But you can change any or all of these three things using the widgets interface. First, you enter the HTML that you want to have precede the widget. In this case, that’s <ul>. Then, you enter the HTML that should follow the widget. That’s </ul> here. Then, you tell it how to parse each item in the feed, using ^ELEMENT$ to specify elements in the feed. To replicate the basic, built-in RSS widget, you would write this: <li><a href="^link$" title="^description$">^title$</a></li>. Easy, isn’t it?

Example 2: Adding another element

How do you know which elements are available? Looking at the RSS feed is a good starting point, but you should be aware that the MagpieRSS parser modifies feeds when it parses them. To see exactly which elements are available, go to any page on your blog, then add ?kbrss=RSS_URL to your blog’s URL (replacing RSS_URL with the complete URL for the feed you are interested in).

For example, if your blog were at example.com, and you were interested in the Yahoo! News Most Emailed Stories feed, you would type this into your browser: http://example.com/?kbrss=http://rss.news.yahoo.com/rss/mostemailed. (That only works if you’re logged in as an admin, so you’ll have to install the plugin and then try it on your own site to see what that does.)

If you do this, my plugin will spit out a copy of the PHP array that MagpieRSS produces when parsing your feed. Each item in the feed shows up as a numbered part of the array. Within each item, you’ll see that you have fields like “title,” “link,” “description,” and possibly others available. Pick any one of these and add it to your KB Advanced RSS widget. Done.

Example 3: Trimming an element

Suppose you want to display each item’s description, but some of the descriptions are way too long. If you wanted to trim the description to 50 characters (or any other number), write ^description[opts:trim=50]$. Note that the [opts:...] comes before the $. If you go the plugin’s page, you’ll see that I used this technique on the example at the bottom of the sidebar.

You can also trim each item from the left. Suppose that each item’s title in your feed starts with the word “News flash!” and you want to get rid of it. Trim the first 11 characters off the title like this: ^title[opts:ltrim=11]$.

If, after removing the first 11 characters, you also want to trim the title to only 10 characters total, you would write this: ^title[opts:ltrim=11&trim=10]$.

Example 4: Displaying dates

Most feeds will use a pubdate fields that produces something ugly like this:

[pubdate] => Thu, 20 Dec 2007 19:32:38 +0000

To modify that, use the date option, using PHP date syntax, like so:

^pubdate[opts:date=F jS Y]$

The F jS Y is PHP date syntax for something like December 20th, 2007.

Example 5: What if an RSS item contains an array of elements?

Okay, now we’ve moved into the really advanced stuff. You probably won’t follow this next part unless you use the ?kbrss= thing from example 2 first and see what I’m talking about. Note that some of the items in Yahoo’s feed contain something that looks something like the following (it will look slightly different):

[media] => Array
        (
            [text] => <p>a bunch of stuff</p>
            [credit] => (Reuters)
        )

There are two ways to display elements from this array.

Use => to access one field from the array. So to access the text field from this array, you would need to type this: ^media=>text$ into the KB Advanced RSS widget options. (In versions 2.0+ of the widget, you can type ^media[opts:subfield=text]$ instead if you want.)

Here’s another example of a feed containing an array, but with a twist. When MagpieRSS parse feeds from some versions of WordPress, for example, MagpieRSS turns the “categories” field in the feed into an array. For example, here’s how MagpieRSS parsed part of my blog’s feed (when it ran on an earlier version of WordPress):

   [title] => KB Countdown update
   [link] => http://adambrown.info/b/widgets/kb-countdown/
   [comments] => http://adambrown.info/b/widgets/kb-countdown/feed/
   [pubdate] => Sat, 31 Mar 2007 22:38:51 +0000
   [author] => Adam
   [categories] => Array
       (
           [0] => KB Countdown
           [1] => Widgets
       )
   [guid] => http://adambrown.info/b/widgets/kb-countdown/

Now, if you only wanted to list the first category, you would write ^categories=>0$, as above. But what if you want to loop through all the categories and print all of them? Then write this: ^categories[opts:loop=true&beforeloop=BEFORE&afterloop=AFTER]$, where BEFORE and AFTER are the html you want to appear before and after each element in the array. For example, you might write this: ^categores[opts:loop=true&beforeloop=<li>&afterloop=</li>]$, or more properly, this: <ul>^categores[opts:loop=true&beforeloop=<li>&afterloop=</li>]$</ul>.

Complete list of options

Now that you’ve learned how to use [opts:...], here’s a complete list of the options available. Note that these options apply to an individual field, not to the feed as a whole.

• [opts:date=...] – For displaying the [pubdate] field nicely.
• [opts:trim=40] – For trimming a field to 40 characters in length.
• [opts:ltrim=50] – For trimming 50 characters off the left (beginning) of a field.
• [opts:bypasssecurity=1] – For allowing a field’s javascript through, if necessary. Use carefully. Disabled in WPMU.
• [opts:loop=true] – For subarrays. See example above. You’ll also use beforeloop and afterloop.
• [opts:subfield=...] – Alternative syntax for displaying a specific field from an array. See example above.

Okay, that’s the basics. Check the FAQ for further details.