WordPress.org

How do I use this thing?

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

I'm using WP 2.5+, and there's some funny text in the admin screen when I first add the widget to my sidebar.

Just hit "save changes" and it will go away. I'm still working on this bug.

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 Countdown from the widgets administration menu.

If you really want to use this in your theme and not as a widget, open the plugin file and search for function kb_rss_template. You'll find some notes there explaining what to do.

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 Wordpress'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 (as coded in wordpress/includes/rss.php). If they don't update after more than a couple hours, look in the top of kb_advanced_rss.php for this line:

define('KBRSS_FORCECACHE', false);

and change it to true. This will manually delete the cache if it's more than 1 hour old. In newer versions of Wordpress, manually deleting the cache in this manner might cause a small error next time you load the page. Instead of displaying your feed, it will say "An error has occured, the feed is probably down." Just reload the page.

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 Wordpress's feed parsing abilities (look in wordpress/includes/rss.php). Wordpress 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 Wordpress from fetching the feed (very likely). Read more here.
3. Wordpress's feed parser isn't working. Try updating to the most recent version of Wordpress.
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 Wordpress 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.