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:
          $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
  • [+/-]widget
  • [+/-]standalone
  • [+/-]nohead
  • [+/-]node
  • [+/-]jsinclude
  • [+/-]xslfile
  • [+/-]linktarget
  • [+/-]depth


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.


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.


  • [+/-]Version 0.4c
  • [+/-]Version 0.4b
  • [+/-]Version 0.4a
  • [+/-]Version 0.4
  • [+/-]Version 0.4pre1
  • [+/-]Version 0.3a
  • [+/-]Version 0.3
  • [+/-]Version 0.2b
  • [+/-]Version 0.2a
  • [+/-]Version 0.2
  • Version 0.1


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.


  1. I uploaded the whole folder to my WP/root, just like the OPMLRenderer folder I already had but it doesn’t show up in my plugin Admin panel. I’ll just wait for the instructions. I ran your test script though:

    Current PHP Version: 4.3.11
    You have CURL installed.
    You have allow_url_fopen enabled.
    You have DOM_XML support.

  2. Billy, this isn’t a replacement for the WordPress plugin. It’s a different application altogether. However, I will be updating the WP plugin with the new features of Optimal when I get a chance, so stay tuned.

  3. I understood that Optimal is completely seperate from the Renderer plugin but I’ve loaded its folder into the WP root and then plugin directory but the added code that you offer above:

    which I included on a new WP PAGE, does not do anything for me besides show my that code again. I’m sure it is just my placement of your code so if you wouldn’t mind helping me out again…

    I could understand if that php code should not go on a new PAGE and instead may need to go in my sidebar or something but where does the Optimal folder itself go? TIA.

  4. Billy, what do you mean when you say you included the code snippets on a WP PAGE? Not the page contents in the WP admin interface, but the source, right? And did you include the full path for the location of optimal_functions.php.inc in the line require_once('optimal_functions.php.inc');?

  5. I want to do this in WP.

    Since it doesn’t seem small enough to fit in the sidebar, I assumed I would put it in a new WP PAGE (as in Admin Panel, Write, Write Page). I added the first 2 bullets of code that you have listed above:

    ?php require_once(‘optimal_functions.php.inc’); head_JS(); ?
    ?php renderXML($url, ”, ”, ‘OPML’, TRUE); ?

    directly to the new blank Page but that obviously isn’t correct.

    On top of that, I still don’t know where to put the Optimal folder in my host server folder (I tried the plugins and WP root directory), where should it be placed?

    When I substitute the url pointing to my OPML file, do I do it for $url or just url?

    I see it working at several sites so I know it’s just my dumbass but if you could supply me with these answers, I’m sure I can get it from there. TIA.

  6. Billy, trying to use code in your posts (or pages) that way is a little tricky. Review the WordPress Codex on this topic. If the page is always going to render the same file, you’d be better off creating a new page template with the code snippets in the PHP source of that new template.

    As for where to put the Optimal folder, it doesn’t matter as long as you create a subfolder named “_cache” which you can make writable by your web server (usually, “chmod 777”). More importantly, if you don’t install it in the same directory as the script that contains these code snippets, you’ll need to change require_once to use the full path to the location of that script.

    In the renderXML function, “$url” refers to a variable defined as the URL you want to render. If you would rather hard-code that URL in the function call, you could do that.

  7. Thx for posting that, I had no idea about that whole second paragraph lol!

    I don’t need that first link because that is for writing code in a post, I want to have a new WP PAGE.

    As I said above, creating the PAGE is no problem, it’s where to put that code you have listed above.
    You grazed that when mentioning your second link because yes it will be the same file everytime, my OPML file,
    then the new page link (which I have a new page) but the next part is where I get hung (which is why I came
    back in the first place). “with the code snippets in the PHP source of that new template” – where does this go?
    Assuming I don’t want to use the iFrames solution and want to use the PHP setup, does the PHP snippets go inside my WP loop (index.php)? I know of no way to do what I just quoted from you accept to add the php code snippets to the new blank page (as I have several other PAGES right now which are working just fine) but you started off your last comment saying it is tricky (apparently it is lol).

    Maybe now that I know about that whole second paragraph in your last post, having the PHP code on a new blank PAGE will work just fine. Either way, I won’t bother you on it anymore. Thx for your time.

  8. Billy,

    FYI, writing code in a “post” is the same as writing it in a “page.” Don’t ignore this link: WordPress Codex on this topic.

    If you create a new page template, you’d probably want to insert the example code snippets in place of the template call: the_content. Or, if you’re going to add some page content in the admin interface, then don’t replace the_content, put the code snippets above or below it as you see fit.

  9. I was working with a new plugin yesterday and they wanted users to setup a new template file for a new PAGE and I immediately thought of you. Hopefully, this whole time what I didn’t understand that you wanted was for the code to be in a xxx.php file (a new template file) and not in the “loop” or sidebar like I was thinking the whole time.

    That is why I said I couldn’t understand where to put the code for a new page other than right there in the admin panel after Write > Page created a new blank page. I think that what you want is for me to create a new blank xxx.php file with the php snippets you provided up above which of course is simple to do, I just never created a template (blank php file) so was ignorant to the concept. I created all my PAGES by doing Write > Page and throwing in a tag cloud script or HTML list.

    Now that I think I got that straight, I suppose i could just go create a new php file name it whatever for the new page name and insert this in the php file when I’m creating it (vs inserting it in the new blank page that shows up in the admin panel):

    ?php require_once(‘optimal_functions.php.inc’); head_JS(); ?
    ?php renderXML($url, ”, ”, ‘OPML’, TRUE); ?

    substituting the $url for the url to my OPML file.

    (which of course means I don’t have to keep making trips to OPML Manager to update my OPML file for others to see when they can see it on my own dedicated blog page, especially since I accidentally added my del.icio.us backup to the base node the other day which contains over 2200 tags/links and I haven’t heard back from them yet about deleting my account so I can start over because I can’t find a way to delete them other than manually and I’m not going there!)

    fyi: Your last para threw me but I’ll see how it goes since hopefully the light has turned on lol.

    sorry + thx

  10. Amy, Firefox considers “domain.com” and “www.domain.com” to be different domains when it protects you from JavaScript cross-site scripting. So, you’re right — it wasn’t working.

  11. This is so cool!

    I tried implementing the scripts on my site–and immediately had problems including the spot in the instructions which says to use head_JS(); whereas the script actually declares headJS();

    Still couldn’t get things to go after that, but it’s working ok from your server. Hope to get it running here so I can get the css the way I need.

  12. I’m trying to get this to work in my installation of WP, but… when I try to publish a Gada.be OPML file on-demand in a post, I’m still unclear as to how I should go about doing that? All I get is… the text that you said I should use printing in an entry? Help? πŸ™‚

  13. Thanks, Chris. I emailed you a bug fix — which introduced another minor bug, which I’ve also fixed. :-[ The download linked above is the latest.

  14. I installed. But i can’t work it out. Help please.

    Current PHP Version: 5.2.0
    You have CURL installed.
    You have allow_url_fopen enabled.
    You have PHP 5 or greater, and XSLT is available.

    And i put code in new page (i created). Code:

    !OPMLRenderer : url,updatetime,css class,depth,flags

    Code in my page:


    What is the mistake?

    It appears nothing. Mistake in what?
    in code?
    in opml file?


  15. Hi.

    I get the error
    # Error reading OPML file:
    OPML URL: http://racewalkingrecord.com/opml/fixtures.opml
    Cache file: 1e516f3bdd29ba5d4e5deced5c874235.opml.xml

    If the cause is related to the Gotcha above – you do not explicitly say what the manual edit that is required to optimalPlugin.php on lines 38 an 41…

    But I don’t know if there is another cause…. this OPML file could be read on Avtivernderer on RadioUserland…. but i’m just getting acquainted with WordPress.

    Thanks, Tim

  16. Tim,

    Looks to me like you’re getting the wrong error message for some reason. I’m just a hobbyist so these things happen. 😳

    Anyway, when I browse to your installation and try to render the sample file, I get an error say no XSLT processor is found, which would mean that your PHP installation won’t work with Optimal. Check this out.

  17. When I activate the plug-in in WP, I get the error messages below. Not being very php knowledgeable, I don’t know if this is an easy and obvious problem or not. Any assistance?

    – Nick

    Warning: fopen(/home/nickn/public_html/wp-content/plugins/optimal/settings.optimal.inc): failed to open stream: Permission denied in /home/nickn/public_html/wp-content/plugins/optimal/optimalPlugin.php on line 37

    Warning: fwrite(): supplied argument is not a valid stream resource in /home/nickn/public_html/wp-content/plugins/optimal/optimalPlugin.php on line 38

    Warning: fclose(): supplied argument is not a valid stream resource in /home/nickn/public_html/wp-content/plugins/optimal/optimalPlugin.php on line 39

    Warning: Cannot modify header information – headers already sent by (output started at /home/nickn/public_html/wp-content/plugins/optimal/optimalPlugin.php:37) in /home/nickn/public_html/wp-includes/pluggable-functions.php on line 272

  18. Nick – Those errors indicate to me that the plugin directory is not writeable by the web server. The first time the plugin runs, it needs to drop a file in the “wp-content/plugins/optimal/” directory that contains various file and server path information. Please either (1) make sure the “wp-content/plugins/optimal/” directory is world-readable and world-writeable (i.e., chmod 777) or (2) manually create the file “wp-content/plugins/optimal/settings.optimal.inc” (i.e., touch settings.optimal.inc) and make sure that this new file is world-readable and world-writeable (i.e., chmod 666).

  19. Greetings!
    Looks like an impressive bit of software. Regarding the *other* Nick’s question and your response, does the /plugins/optimal/ folder need to forever stay chmod777? or just long enough for its first launch to deposit the settings.optimal.inc file? then take it back to 755 or leave 777?

    also, I’m wanting to put the optimal list in the sidebar of my wordpress blog. the sidebar file is called from sidebar.php in the theme folder. when i put the
    !OPMLRender:url,updatetime,css class,depth,flags
    with all the appropriate strings in the sidebar.php file, all it does is print the above string, not the data; it works fine in a post or page. is Optimal limited as such? Is there any way to get it to render in sidebar.php? much appreciated!

  20. Nick (Normal) – After the file settings.optimal.inc has been created, you can change the directory permissions back.

  21. Tahir, I haven’t tested the plug-in with WP > 2.0. 😳 Maybe the function I use in my plug-in code got deprecated. Sorry about that. I’ll let you know if I figure it out.

  22. !OPMLRender : url,updatetime,css class,depth,flags

    Well, not quite… There isn’t supposed to be a space after the colon, otherwise that is counted as part of the URL. Am I really the only one who has had this problem?:oops:

  23. You might be, David. The instructions say right above it, in bold letters, “without spaces.” πŸ˜‰

  24. First of all, thank you for this wonderful plugin. I was about to write my own when I saw it.

    One small comment – I am installing WP 2.2 and I ran into a small issue with this plugin. I have my WordPress files in a different directory than the site itself (as described here). The image files in the plugin would not work until I replaced the line get_bloginfo(‘url’) with get_bloginfo(‘wpurl’).

  25. I think it’s time to clean up the directions. Too much good stuff in the comments that needs to be in a FAQ.

    The line of code to enter into WP templates is empty. Above it, it’s says “To access the template function, use the following from your template file”.

    What is the code I should paste into my WP template to display the OPML file in my document root?

  26. Dan,

    Cool tool. However I am stuck in the Gotcha situation, using optimal.php I do not have a settings.optimal.inc to edit and editing the $optimal var is still getting errors.
    # E.g., $optimal = new optimal (‘E:/00_Projects’, NULL, ‘/optimal’, $_SERVER[‘DOCUMENT_ROOT’]);

    Is there any way to using something similar to the ‘test script’ to determine above array?


Leave a comment

Your email address will not be published. Required fields are marked *