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

  • spacer Using Optimal as a WordPress plugin
    • spacer 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.
    • spacer Installation
      • spacer 1. Unzip optimal.zip into your plugins directory. This should automatically create a new subdirectory named 'optimal'.
      • spacer 2. Ensure that the directory 'optimal/_cache' is world-readable and world-writeable (i.e., chmod 777 optimal/_cache)
      • spacer 3. Activate the plugin via the WordPress administration interface.
      • spacer That's about it!
    • spacer Usage
      • spacer The Optimal plugin is invoked through either the new content filter or the new template function.
      • spacer To access the content filter, use the following in a page or post (without spaces):
      • spacer !OPMLRender : url,updatetime,css class,depth,flags
      • spacer To access the template function, use the following from your template file (e.g., in sidebar.php) (without spaces in the PHP tags):
      • spacer < ?php OPMLRender('url','updatetime','css class','depth','flags'); ? >
      • spacer 'url' is the OPML file to render. This is a required parameter.
      • spacer '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.
      • spacer '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.'
      • spacer '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.'
      • spacer '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.'
  • spacer Using Optimal Installed On Your Own Server
    • spacer Requirements
      • spacer Either (1) PHP 4.3+ with domxml and libxslt or Sablotron support or (2) PHP 5+ with XSLT support.
      • spacer PHP with curl or with allow_url_fopen enabled.
    • spacer Installation
      • spacer 1. Unzip optimal.zip into the top level directory of your server. This should automatically create a new subdirectory named 'optimal'.
      • spacer 2. Ensure that the directory 'optimal/_cache' is world-readable and world-writeable (i.e., chmod 777 optimal/_cache)
      • spacer That's about it! Your Optimal installation should be available at your-domain-name/optimal/optimal.php.
    • spacer Usage
      • spacer Including Optimal output in an br
        • spacer This is probably the easiest way to use Optimal on your website.
        • spacer Use the widget wizard (your-domain-name/optimal/wizgetwiz.php) to generate the HTML you need to include in your page.
        • spacer Here are some other examples (obviously, you cannot use spaces in the query string -- they're here so the display can wrap nicely):
        • spacer <br src="/img/spacer.gif"> &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.
        • spacer <br src="/img/spacer.gif"> &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 <br> will open in the main browser window.
      • spacer Including Optimal output with PHP script
        • spacer If you're using PHP and you don't like <br>s, this is another way to use Optimal on your website.
        • spacer 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.
        • spacer 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.
  • spacer Using Optimal Via optimalbrowser.com
    • spacer 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.
    • spacer Visit www.optimalbrowser.com/widgetwiz.php to generate the HTML you can include in your page.
spacer

Several variables may be passed via the query string:

[ Expand All | Collapse All ]
  • spacer url
  • spacer widget
  • spacer standalone
  • spacer nohead
  • spacer node
  • spacer jsinclude
  • spacer xslfile
  • spacer linktarget
  • spacer depth
spacer

Gotchas

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

  • spacer Version 0.4c
  • spacer Version 0.4b
  • spacer Version 0.4a
  • spacer Version 0.4
  • spacer Version 0.4pre1
  • spacer Version 0.3a
  • spacer Version 0.3
  • spacer Version 0.2b
  • spacer Version 0.2a
  • spacer Version 0.2