WordPress.org

How do I use this thing?

Check out the "Other Notes" tab, above, for instructions.

What code do I need to place in my sidebar?

None. This is a widget. If you are using pre-WP v2.2, you need to have the widgets plugin running. No matter what version of WP you're using, you need to be using a widgets-enabled theme. You control all options for KB Advanced RSS from the widgets administration menu.

What can I do with this widget?

Lots of things. The built-in RSS widget will handle traditional headline-style feeds well, but this widget allows you to handle untraditional feeds just as easily. For example:

• Weather. Weather.com provides RSS feeds, but you'll find more flexible feeds at RSSweather.com.
• Upcoming events. If you have an RSS feed of calendar data, give it a go.

Note that finding a suitable feed is up to you. It needs to be RSS, not just XML. (RSS is a sub-type of XML.) If you're not sure whether the feed will work with MagpieRSS's feed parser, then use the widget's built in debugger (see below) to check out the feed in question.

The feeds don't update

They update only once per hour to avoid slowing down your site. After that, they only update if your server is actually able to communicate with the feed's site. Be patient.

I add the widget to my sidebar, but it doesn't show up

In the widget's options, make sure "Hide widget when feed is down" is not checked. Go back to your blog and reload. You'll probably see something like "An error has occured; the feed is probably down." Read on...

"An error has occured; the feed is probably down."

This widget relies on MagpieRSS's feed parsing abilities. MagpieRSS grabs the requested feed then passes it to this widget for formatting. If you are seeing this error, it means one of three things:

1. The feed really is down. Wait a while and try again.
2. Your host is blocking MagpieRSS from fetching the feed (very likely). Read more here.
3. Try updating to the most recent version of Wordpress and of this plugin.
4. Some users of this widget have suggested additional solutions to this problem. Check out the comments on this blog post.

In any case, you may want to first try using Wordpress's built-in RSS widget. If neither it nor my widget can display the feed, then you know for certain that it's one of those three reasons--and not the widget itself--causing the failure.

Which fields are available in the feed? Or: I need to debug the feed.

Begin by looking at the source code for the feed. But note that Wordpress parses feeds in ways that you might not expect. After you've installed my widget, you can add ?kbrss=http://path.to.feed/ to your blog's URL to see exactly which fields are available. (You'll need to be logged in as an admin to do this).

If you see that there is a field called title (there probably is), you would include this in your widget's output by writing ^title$. You would probably want to wrap this in some HTML, like this: <li>^title$</li>. Look under the "Other Notes" tab for more details about how to display RSS feeds the way you want them in your sidebar.

If all you see is array()--or worse, an error message--then there's a good chance that the feed in question is not an RSS feed, at least not one that the MagpieRSS parser knows how to handle.

How do I trim the length of an RSS field?

Check out the "Other Notes" tab.

Some of the available fields are arrays!

No problem. Check out the "Other Notes" tab.

What options are available?

Check out the "Other Notes" tab.

The feed shows up as gobbledygook!

Try checking the "convert to UTF-8" option. (Thanks to Christoph Juergens.)

I'd like to modify the feed before displaying it

For example, suppose your feed has a field called "image" that contains something like this:

<img src="http://example.com/img.jpg" />

and all you want is the URL. Obviously, you'll need to do customizations like this yourself. But here's a couple tips. Usually, the easiest route is to create your own option. Write something like this: ^image[opts:extractUrl=1]$.

Next, open up the plugin file and search for function item_cleanup. Insert your code in there. Something like this:

if (1==$extractURL){
...
}

How do I add additional options?

Read the answer to the previous question. If you think other folks would like the same option, let me know so I can add it to the plugin.

I have a question that isn't addressed here.

Be advised: If you post your support questions as comments below, I probably won't see them. Post your support questions at the KB Advanced RSS plugin page on my site if you want an answer.