Don't Back Down

MT-Outliner: Access information from OPML files through template tags.
A Plugin for Movable Type

Release 1.0
October 6, 2003

http://www.everitz.com/sol/mt-outliner/index.html

If you find the software useful or even like it, then a simple 'thank you' is always appreciated. A reference back to me is even nicer. If you find a way to make money from the software, do what you feel is right.

Copyright 2003, Everitz Consulting

Licensed under the Open Software License version 2.1

This Movable Type plugin allows you to process an OPML file and pull in the information contained within by using MT template tags.

Installation:

To install, place the Outliner.pl file in your Movable Type "plugins" directory. If you do not have a Movable Type plugins directory, create one, then put the Outliner.pl file in it. Refer to the Movable Type documentationfor more information regarding plugins.

The functionality in Outliner requires the use of the LWP::UserAgent and the HTTP::Request modules, so you'll need to make sure they are installed as well. These modules are fairly common, so you may have them already. You can use something like ModCheck to easily check your installation for the presence of these modules.

You can find both of these modules as a part of the libwww-perl distribution:

http://search.cpan.org/dist/libwww-perl/

With all modules that you put on your server, make sure that they are executable. Permissions of 755 ought to work fine.

Loading an OPML File for Processing:

<MTOutliner>

This tag offers two attributes for retrieving data in OPML format.

The first attribute makes use of your Bloglines user ID or email address to retrieve your subscriptions from the Export function of Bloglines. If you choose this option, make sure that all subscriptions you'd like to see are made public, or else your OPML file may be incomplete. To retrieve an export from Bloglines, simply add the bloglines attribute to the tag:

<MTOutliner bloglines="userid">

The value specified for the bloglines attribute can be either the user id or the email address associated with your account.

If you would like to use any old OPML file, then you can also specify that by the use of an attribute on the MTOutliner tag. The only catch is that the file must be available via URL:

<MTOutliner opmllink="http://example.com/path/to/file/opml">

*** NOTE: If you specify a value for the bloglines attribute, then the opmllink attribute will be ignored!

Tags to Retrieve Document-level Data:

<$MTOutlinerBloglines$> = The Bloglines user ID specified.
<$MTOutlinerDateCreated$> = The date the document was created.
<$MTOutlinerDateModified$> = The date the document was modified.
<$MTOutlinerOPMLVersion$> = Version of OPML used in the document.
<$MTOutlinerOwnerName$> = The name of the owner of the document.
<$MTOutlinerOwnerEmail$> = The email of the owner of the document.
<$MTOutlinerTitle$> = The title of the document.
<$MTOutlinerXMLVersion$> = Version of XML used in the document.

The OPML file contains some information in the header of the document that may be of interest to you. Using these tags, you can pull that information into your template for display. These tags must be used within the MTOutliner container.

With the exception of the MTOutlinerBloglines tag, each of these values comes from the document itself. So if the values are not included in the document, they are not available through the tags! The two date tags will accept the MT format tags for displaying a variety of values.

The MTOutliner tag accepts one more attribute that allows you to customize the message received when a document-level value has not been specified. By default, when an attribute is missing the tag will return "Not Found".

By adding the notfound attribute to the tag, you can say whatever you like:

<MTOutliner bloglines="userid" notfound="Where Is It?">

This attribute applies only to these document-level tags.

The Folders Container:

<MTOutlinerFolders>

Within the MTOutliner tag, you'll likely want to display something. Using the MTOutlinerFolders container, you can list each of the folders found in your document.

The MTOutlinerFolders tag accepts two attributes.

The first is to indicate if you want to include "unfiled" entries. Unfiled entries are those entries that are not found within a particular folder. By default, unfiled entries are not included in any further output. To enable the display of these entries, add the unfiled attribute to this tag:

<MTOutlinerFolders unfiled="1">

The second tag is to specify a folder or a list of folders to include in the output. By default, all folders are included. If you'd like to limit the folders, specify them by using this attribute:

<MTOutlinerFolders folders="Folder 1:Folder 2:Folder 3">

Separate multiple folders with colons. You can use the folders attribute to select folders and also use the unfiled attribute to include the top-level entries that are not filed in folders.

Within this container, there are several conditional tags to control the data that is output:

<MTOutlinerFolderIfItems> = Display if the current folder contains items.
<MTOutlinerFolderIfNoItems> = Display if the current folder contains no items.
<MTOutlinerFolderFiled> = Display if the current items are filed (in a folder).
<MTOutlinerFolderUnfiled> = Display if the current items are unfiled.

While this plugin ought to work with subfolders (folders within folders), that configuration hasn't been tested. Your results with subfolders may vary.

Tags to Retrieve Folder-level Data:

<$MTOutlinerFolderText$> = The text value of the folder (title used if no text).
<$MTOutlinerFolderItemCount$> = The count of items within the folder.

The Items Container:

<MTOutlinerItems>

This tag can be used on it's own inside the MTOutliner tag, in which case it will display all individual items (but no folder information), or it can be used within the MTOutlinerFolder container, in which case it will display the items contained within that folder.

There are no attributes to this container.

Tags to Retrieve Item-level Data:

<$MTOutlinerItemText$> = The text value of the item (title used if no text).
<$MTOutlinerItemDesc$> = The description value of the item.
<$MTOutlinerItemHTML$> = The htmlurl value of the item (url user if no htmlurl).
<$MTOutlinerItemXML$> = The xmlurl value of the item.

You can use this plugin to create a simple blogroll from your OPML file:

<MTOutliner opmllink="http://example.com/path/to/file/opml">
<MTOutlinerItems>
<a href="<$MTOutlinerItemHTML$>"><$MTOutlinerItemText$></a>
<a href="<$MTOutlinerItemXML$>">Syndicate this Site</a><br />
</MTOutlinerItems>
</MTOutliner>

By making use of the folder container, the conditional tags and the other attributes, you can customize your blogroll in most any way you can imagine!

I've tested this plugin with the Bloglines export, some Manila-generated OPML files, a file I believe came from SharpReader's export function, and even the OPML file generated by Feedster's search. If you come across any problems in these formats, or if you have another format that doesn't seem to be working, please send me the information so I can fix the plugin or add support for the format you use.