Optimal OPML Browser & WordPress Plugin

Description and Features

Optimal renders valid OPML from any source in a tree-like view ideal for browsing. Links to external OPML files as well as RSS, RDF, and Atom feeds are expanded in place.

Optimal can be installed as a WordPress plugin -- it is the successor to my OPML Renderer for WordPress plugin.

Use Cases

Using Optimal as a WordPress plugin
- Optimal can be installed as a plugin in your WordPress blog. This is the best way to use Optimal on your site because you don't need to rely on the availability of the optimalbrowser.com server.
- Installation
  - 1. Unzip optimal.zip into your plugins directory. This should automatically create a new subdirectory named 'optimal'.
  - 2. Ensure that the directory 'optimal/_cache' is world-readable and world-writeable (i.e., chmod 777 optimal/_cache)
  - 3. Activate the plugin via the WordPress administration interface.
  - That's about it!
- Usage
  - The Optimal plugin is invoked through either the new content filter or the new template function.
  - To access the content filter, use the following in a page or post (without spaces):
  - !OPMLRender : url,updatetime,css class,depth,flags
  - To access the template function, use the following from your template file (e.g., in sidebar.php) (without spaces in the PHP tags):
  - < ?php OPMLRender('url','updatetime','css class','depth','flags'); ? >
  - 'url' is the OPML file to render. This is a required parameter.
  - 'updatetime' is the number of seconds to cache a file before requesting an update. This is an optional parameter. The default is 14400, or 4 hours.
  - 'css class' indicates the CSS class to be applied to the <div> that wraps the rendered outline. This is an optional parameter. When using the content filter, the default class is 'opmlPage.' When using the template function, the default class is 'opmlSidebar.'
  - 'depth' indicates how many levels to initially expand the outline (excluding inclusions). This is an optional parameter. When using the content filter, the default depth is '1.' When using the template function, the default depth is '0.'
  - 'flags' is the sum of the display flags you wish to set TRUE (currently, '1' = 'Print a header with links to Expand/Collapse all nodes' and '2' = 'Print a footer with a link to the source OPML file'). This is an optional parameter. The default is '2.'
Using Optimal Installed On Your Own Server
- Requirements
  - Either (1) PHP 4.3+ with domxml and libxslt or Sablotron support or (2) PHP 5+ with XSLT support.
  - PHP with curl or with allow_url_fopen enabled.
- Installation
  - 1. Unzip optimal.zip into the top level directory of your server. This should automatically create a new subdirectory named 'optimal'.
  - 2. Ensure that the directory 'optimal/_cache' is world-readable and world-writeable (i.e., chmod 777 optimal/_cache)
  - That's about it! Your Optimal installation should be available at http://your-domain-name/optimal/optimal.php.
- Usage
  - Including Optimal output in an IFRAME
    - This is probably the easiest way to use Optimal on your website.
    - Use the widget wizard (http://your-domain-name/optimal/wizgetwiz.php) to generate the HTML you need to include in your page.
    - Here are some other examples (obviously, you cannot use spaces in the query string -- they're here so the display can wrap nicely):
    - <IFRAME SRC="optimal.php?url=http://.....opml &standalone=1 &nohead=1"/> - This will display the OPML without the usual Optimal home page elements and with only the <body> element of the OPML file.
    - <IFRAME SRC="optimal.php?url=http://.....opml &standalone=1 &nohead=1 &linktarget=_top"/> - This will display the OPML without the usual Optimal home page elements and with only the <body> element of the OPML file. In addition, all links within the <IFRAME> will open in the main browser window.
  - Including Optimal output with PHP script
    - If you're using PHP and you don't like <IFRAME>s, this is another way to use Optimal on your website.
    - Somewhere on your page (before any output is printed) you'd add:
      <?php require_once('class.optimal.php'); $optimal = new optimal; ?>
      N.B. You may need to include the full path to class.optimal.php.
    - You'll now have the object '$optimal' available. Have a look through class.optimal.php to see all the properties and methods that are available. Also have a look at optimalPlugin.php (particularly the OPMLRender function) to get usage hints.
Using Optimal Via optimalbrowser.com
- I don't recommend that you rely on this method. My hosting company may be out of service. My account may have exceeded its bandwidth allocation. Etc. Etc. That being said, it's REALLY easy.
- Visit http://www.optimalbrowser.com/widgetwiz.php to generate the HTML you can include in your page.

Several variables may be passed via the query string:

[ Expand All | Collapse All ]

url
- This is the URL of the OPML file you want to browse.
widget
- A "widget" value of 1 acts as sort of a meta-flag that translates as: standalone=1&nohead=1&node=0.
standalone
- A "standalone" value of 1 will output a page without the usual Optimal home page elements, such as the headings, URL input form, etc.
nohead
- A "nohead" value of 1 will output only the <body> element of the OPML file in the resulting page. A "nohead" value of 1 together with a "standalone" value of 1 results in output that is ideal for including on your own website (such as within an <IFRAME>) or, for Firefox users, using as a bookmark that opens in a Sidebar.
node
- The "node" parameter is primarily used only by the AJAX part of the script to signal to itself that the requested URL is going to be a new node beneath an existing node.
- A "node" value of "opml" or "rss" will output the resulting OPML or feed without any JavaScript or CSS, without the usual <ul> element surrounding the display, and, in the case of OPML, with only the <body> element of the OPML file displayed.
- See the use cases for an example of how to use this parameter.
jsinclude
- A "jsinclude" value of 1, when passed in conjunction with a "node" value of "opml" will precede the output of the rendered OPML with the Optimal's usual JavaScript and CSS, thereby making the expand/collapse buttons functional, etc.
- See the use cases for an example of how to use this parameter.
xslfile
- You can use an alternative XSLT stylesheet you have added to your installation by passing the basename (without suffix) of the stylesheet as a query string parameter.
linktarget
- You can specify the value of the target attribute of every link with this parameter. The predefined target values are "_top", "_parent", "_self" and "_blank".
- See the use cases for an example of how to use this parameter.
depth
- You can specify the initial expansion state of the OPML file with this parameter. The default is to expand the first level and collapse the rest.

Optimal tries to automatically discover where you've installed it. When that works, it makes your life easier. When it doesn't work, it can be an aggrevating experience. (Thanks for hanging in there, Chris!)

If you're getting weird errors, especially "Error reading XSL file," you've probably been bitten. To solve this issue, you'll need to manually edit either (1) the plugin file optimalPlugin.php on lines 38 an 41, if you're using the plugin or (2) the file optimal.php on line 41, if you're not using the plugin. There are four path values: (1) the top-level file directory, (2) the top-level URL, (3) the path to your Optimal installation relative to the top-level, and (4) if different from the top-level file directory, the directory where any local OPML files are stored. After you've made any changes, you'll need to delete the file settings.optimal.inc if present in the directory where you've installed Optimal.

Download

The current version of Optimal is 0.4c.

I strongly encourage you to download Optimal and install in on your own site, rather than relying on the availability (and using the bandwidth) of optimalbrowser.com.

You can download it here.

See the installation instructions, above. If you run into problems, feel free to leave a comment. I think the majority of problems will be related to either an incompatible server configurtation (PHP 5+ or 4.3+ with domxml and libxslt or Sablotron support: this test script, when run from your server, should tell you if your server is compatible) or failure to ensure your "_cache" subdirectory has world-writeable (777) permissions.

Changes

Version 0.4c
- Fixed/enhanced installation directory autodiscovery.
Version 0.4b
- Attempted bugfixes -- don't use
Version 0.4a
- Attempted bugfixes -- don't use
Version 0.4
- Fully compatible with PHP 5+ and WordPress 2+.
- Extensively revised to make the code more maintainable and to synchronize the code between this and the WP plugin.
- Added a child item, description, for each RSS item.
- Added a function to make all links (including in the RSS description) open in the target specified by the 'linktarget' parameter.
- Added a query string parameter: widget, which acts as sort of a meta-flag that translates as: standalone=1&nohead=1&node=0.
- Added a widget to generate IFRAME code for easy inclusion on users' web sites.
Version 0.4pre1
- Added a query string parameter for the initial expansion state: depth. The default is to expand one level deep (changed from two levels deep).
- Added links to expand/collapse all nodes and removed the "Go Back" link which isn't necessary because of in-place inclusion.
- Changed the link to feed enclosures. Now there are both a link to download the enclosure and a link to play the enclosure, the latter of which will open Jeroen Wijering's Flash MP3 Player below the link. So I guess you can call Optimal a "podgrazer" or something like that.
- Optimal is now OPML 2.0 ready (I think). Support for the "include" type attribute and <ownerId> element are present, at least.
- Rewrote "string replace" sections of optimal.xsl to use my own template rather than the EXSLT template, which was problematic to implement.
- Lots of code cleanup, but I'm still unhappy with the modularity of it, so I may do a complete (or near complete) rewrite.
Version 0.3a
- Enlarged the expand/collapse icon to make it a little easier to click.
- Added support for Atom 1.0 feeds.
- Added indicator of and link to feed enclosures.
- Implemented support for the "include" type, which will become part of the OPML 2.0 spec.
- Enhanced case-insensitivity of some XPath tests.
- Added link to source URL and cachefile, if any, in debug info displayed in error messages.
Version 0.3
- Added a query string parameter, linktarget, to permit, for example, IFRAMEs to open links in the parent window.
- Changed the feed icon to the new standard icon.
Version 0.2b
- Fixed another path bug.
- Added a bookmarklet to the Optimal main page.
Version 0.2a
- Fixed cURL setting to follow feed redirects (especially prevalent with FeedBurner users).
- Added a query string parameter, jsinclude, which when set to 1 and used together with node=opml, affords another way to embed a rendered outline in your web page.
Version 0.2
- Fixed path bug to permit installation in directory other than the www document root. Thanks to Adam Green to pointing this out.
Version 0.1

History

Optimal is based on my earlier OPML Browser, but was extensively rewritten to bring its code into closer synchronization with my OPML Renderer plugin for WordPress. This is now done, and Optimal can be installed as a plugin for WordPress.

Optimal was named not out of sheer ego or to imply that it is the best OPML browser, but rather because "optimal" was the only good word I could think of in which I could camel-case OPML (i.e., OPtiMaL). However, the camel-casing is merely a meme, not the proper name.

67 comments

Winston says:

September 12, 2007 at 5:26 pm

Dan,

Or for instance.. if I ran a test file with phpinfo(); in the optimal install directory, what values would I be looking for?
Winston says:

September 14, 2007 at 10:59 am

I got the $optimal path issue resolved. but today your site throws an error parsing my opml files.. they worked yesterday. maybe you are hackin away over there…
Dan says:

September 30, 2007 at 9:31 pm

@David Evans – Fixed that missing code snippet. Thanks.
Dan says:

September 30, 2007 at 9:32 pm

@Winston – Glad you fixed your problem. The errors you were seeing on my end should be fixed – bad server setting after a package upgrade. I think everything is fine now.
Pingback: Optimal OPML Browser | Calyptratus
Tibor says:

January 18, 2008 at 9:59 am

Dan, thanks for this wonderfull plugin! However, I have two questions:

– Is it possible to limit the amount of feed items being fetched from each feed in the rendered opml file?

– I would like the title of the feed (as exposed next to the rss logo) turn into a link back to the website that offers it.

Any suggestions?

Thanks in advance!
Jonathon says:

February 24, 2008 at 4:38 pm

I know OPML Renderer is deprecated, but can I use the OPML Renderer plugin instead of Optimal? Optimal seems to be a large file to load – i.e. it seems it will slow my site.

Or does Optimal only load when a .opml file is called?
Dan says:

March 19, 2008 at 10:44 am

Jonathon, feel free to use whatever version you like, but I cannot imagine how Optimal would slow your site any more than the older OPML Renderer.
Neville Hobson says:

April 6, 2008 at 10:29 am

Dan, a great plugin, thanks. Installed 0.4c on my WP blog, works a treat. (Btw, my blog is running WP 2.5 and the plugin works fine).

One thing I’d like to do but can’t figure out how: on initial display, the plugin just shows a single line, the name of the OPML file. You then click on the little icon/arrow to expand the display to show the individual feed names within the OPML file.

You can see it in place on my blog here: http://www.nevillehobson.com/connections/

That’s great but I’d like the display to be all of that from the start. I think the switch is the ‘depth’ variable? Well, I’ve tried all sorts of numbers there, nothing happens.

I guess I’m missing something. Would you let me know how I can do what I’d like to? thanks.
Pingback: Adding Related Feeds to Your Wordpress Posts | Stephan Miller
Nick Normal says:

May 31, 2008 at 12:10 pm

hi! I’ve been bitten!
I get the “Error reading XSL file” error!

I used to have your plugin running on my blog, it was fine. i migrated my service to MediaTemple, and now I get this odd error! The instructions “There are four path values…” however I cannot properly figure out. I’ve modified those lines to fit what I think should be the proper variables, and then I just get an error in web-browser reporting some break on line 38. can’t figure it out. can you be more specific with what those lines, ABSPATH, DOCUMENT_ROOT, url, etc. should be?

love the live loading of xml documents inside the plugin by the way. very smart. thanks!
Pingback: The Ultimate DoFollow Blog List | Stephan Miller
Pingback: Wordpress: Compartir tus Feeds Rss | Metsu 3.0
Pingback: OPML e dintorni | Quasi.Me
Pingback: My Web Handbook
R. Richard Hobbs says:

June 3, 2009 at 5:52 pm

I have the optimal plugin installed on my self-hosted WP installation and it seems to serve the intended purpose. look on my links page f usage /link-page/

One problem the past few months is that Optimal and / or Simple Pie are generating enormous .core files from feed errors and / discontinued feeds I am aggregating – I get disk warning messages from my host about once every two weeks – the .core files are always found in my wp-content/plugins/optimal folder.

Am sure it would help if I went in and chk’d the error log and cleaned up dead feed links – any other insights?

thx
Dan says:

June 3, 2009 at 10:25 pm

Hi, Richard. Thanks for the feedback. I have no idea what’s dropping core dumps — Optimal is certainly not set up to do that, and the last time I saw a core dump of any kind was probably 5 years ago playing with a buggy Mandrake Linux beta.

The only things I can suggest are: (1) make sure that neither PHP nor Apache (or whatever web server you’re running) is compiled with a “debug” flag enabled, and (2) do check your httpd error logs and see if you can find any errors that coincide with the creation date/time of the core dump file.

While Optimal could certainly use some work to more gracefully fail upon feed errors, I have never seen it crash and cause a core dump.