about

contents

progress

opmlRender

today

#title "opmlRender"

#opmlStory "http://radio.weblogs.com/0104487/gems/opml/opmlRender.opml"

#renderOutlineWith "activeRenderer"

What is opmlRender ?

opmlRender is a UserTalk macro command that renders, or translates, an OPML outline into HTML.

Why use it at all ?

I find it easier to manage some of the content published in a Radio weblog as outline files.

Some of those outlines are rendered directly in s l a m 's #homeTemplate file.

The headlines, home, tracks and resources sections for instance, are all outlines.

I created those outlines directly in Radio, and saved them as opml documents (Radio's default format for external outlines).

Installing opmlRender.

Simple enough, just save a copy of opmlRender as a text file in your Radio application Macros folder.

If you're a user of activeRenderer, opmlRender is part of the tool, it is already installed. Neat uh ?

How does it work ?

Insert <% opmlRender ( "url" ) %> anywhere you want the "url" outline to be rendered.

"url" must be a regularly formed uniform resource locator for the outline to render.

A local url uses the file:// header. It could be something like: file:///C/Program%20files/Radio%20UserLand/www/instantOutliner/yourOutline.opml.

A remote url uses the http:// header. As in http://radio.weblogs.com/0104487/instantOutliner/marcBarrot.opml.

The style of the html that opmlRender outputs can be customized using Cascading Style Sheets.

Every node in the outline is rendered in a paragraph with a CSS class attribute.

The default class name used by opmlRender is "l" (lowercase l), a bit terse maybe :-)

You can substitude any other name by supplying a name string as the second argument to opmlRender.

For instance : <% opmlRender ( "file:///Data/Marc/Radio%20UserLand/www/gems/opml/tracks.opml", "track" ) %>.

There's a catch: the string you supply, or the default "l" string, is not rendered directly as class="string".

The macro adds a suffix, which is the level in the outline of the node being rendered. All outline summits are at level 1, their children are at level 2, and so on.

This very node of the opmlRender outline is rendered as a class="story5" paragraph (I entered <% opmlRender ( "file:///Data/Marc/Radio%20UserLand/www/gems/opml/opmlRender.opml", "story" ) %> in the story text for the html version of this tutorial - still with me :-) ?

You've got to provide for the matching CSS style definitions in the header part of the file where you insert opmlRender macros.

I inserted the following line in the <header> section of the template for this (and all) stories:

<link rel="stylesheet" type="text/css" href="http://radio.weblogs.com/0104487/gems/css/stories.css">

The stories.css file is where all styling rules are specified.

It gets worse, you can specify an optional third parameter to opmlRender, that defines the way the outline is expanded before rendering.

If you do not specify a third parameter, or enter false (or 0), the outline is rendered as it was saved: collapsed nodes are not visible and skipped entirely in the rendered version.

If you enter true, or 1, as third parameter, all the outline nodes are fully expanded before rendition.

The fourth and fifth optional parameters are specially useful if you've specified true as third argument.

I promise, those are the last ones :-)

The 4th optional argument is the maximum depth level rendered in the outline.

It defaults to 0, no limit.

If an outline has a depth of 4 levels, but opmlRender's 4th argument is 2, all nodes of level 3 and 4 are ignored at rendering time.

The 5th optional argument is the maximum number of summit (level 1) nodes rendered in the outline.

It defaults to 0, no limit as well.

If an outline includes 4 summits, but opmlRender's 5th argument is 2, only the first 2 summits and their children are rendered, the remaining 2 are ignored.

Some additional examples.

The headlines section at the top of s l a m 's home page :

<% opmlRender ( "file:///Data/Marc/Radio%20UserLand/www/gems/opml/headlines.opml", "headline", true, 2, 1 ) %>

The resources section in s l a m 's home page :

<% opmlRender ( "file:///Data/Marc/Radio%20UserLand/www/gems/opml/resources.opml", "track", true, 3, 0 ) %>

Dave Winer's instant outline, in HTML attire, why not :-)

<% opmlRender ( "http://radio.weblogs.com/0001015/instantOutliner/daveWiner.opml" ) %>

Credits

The opmlRender macro was born 'renderCss' quite some time ago.

renderCss was based on some interesting work by Carlos Granier and Andy Fragen.

© copyright 2004
by Marc Barrot.