metaRenderer Example

By Mark Woods, 10/29/02

About metaRenderer

I have been playing around with Oliver Wrede's metaRenderer. This renderer is intended to be a Manila plug-in, but accessible to Radio users that are editing Manila sites. I grabbed the renderer code itself, patched up a couple of lines of code, and threw it into Radio's user.html.renderers table. Now I have a cool new renderer at my disposal.

Is metaRenderer Useful? A good question. It sounds useful. The idea behind metaRenderer is to enable an author to use multiple renderers within a single outline. This is useful when you are writing a story, perhaps using the twoLevelOutline renderer, and want to embed a table rendered with the tableOutliner. Without metaRenderer you had to create a separate outline (in a separate file), then use a macro to render the table from within the main story. This technique was covered in the Renderers BWG. Oliver's metaRenderer allows you to switch renderers for a subsection of the outline. That means you can use the effects from multiple renderers all within a single outline story. For example, this story was rendered using metaRenderer (see the screenshots below). The table that follows is embedded in the same outline as the rest of the story, but is separately rendered using my own customized copy of the newTableOutliner.

The Good	The Bad
It works. You can freely switch renderers so long as you obey some simple rules (to be covered).	Setting up metaRenderer as a Radio renderer is not very intuitive, but then, it was meant to work in Manila, not Radio.
It is very easy to render tables within a story, using Radio's tableOutliner, without writing any HTML table code.

This is useful stuff. If you do a lot of writing using Radio's outliner, then you should be using Radio's renderers (to avoid writing a lot of messy HTML). If you are using renderers, then you have probably at least once desired the ability to momentarily switch to another renderer from within the same outline. If so, then metaRenderer may be for you.

Using metaRenderer

metaRenderer is invoked just like any other Radio renderer. Refer to the Renderers BWG for general information on using Radio's outliner and renderers to create stories. Use the #renderOutlineWith directive to tell Radio you want the metaRenderer used. Note that metaRenderer does not, by itself, actually render anything. It follows your instructions to invoke specific renderers for specific subsections of the outline. metaRenderer then pieces the results together for you. metaRenderer will use the pikeRenderer by default (in the absence of any other specification), but you can change this by setting user.metaRenderer.prefs.defaultRenderer to the name of the renderer you want metaRenderer to default to.



Switching renderers is accomplished with a pseudo-directive named .renderWith at the beginning of a line (it can be at any level within the outline). The pseudo-directive must be followed by the name of an existing renderer in the user.html.renderers table. For example, ".renderWith newTableOutliner". It took me a while to figure this out, but only subheads to the .renderWith pseudo-directive are passed to the renderer. It makes sense, but it also means following some unusual practices, like coding directives as subheads. Oh yes, you can specify renderer-specific directives when you switch renderers. So long as the metaRendererData.prefs.allowDirectives flag is set to True (the default).



In the example above, the highlighted section is rendered with "newTableOutliner". Only subheads to the .renderWith pseudo-directive are passed to the newTableOutliner renderer. The following summit (indented at same level as .renderWith pseudo-directive) will revert to the previous renderer - pikeRenderer in this case. It is worth noting that the use of newTableOutliner is nested within the use of pikeRenderer. metaRenderer lets you do as much of this nesting as you want. That might be handy for doing a table within a table. Like so:



Installing metaRenderer

With Oliver's permission, I am posting the Radio metaRenderer script for public download. Since the interface and function are unchanged, I am keeping the name the same. Let me know if you run across any problems (I have done enough testing to be confident that it does not break anything).

Install Instructions: Download the script (IE users can right-click and download target), saving it in whatever directory you like to keep Radio scripts in (a temp location is fine). Open Radio (from the System Tray), then using Radio's File/Open menu to open the script. Radio will prompt you for a location to load the script. Accept the default location - if you change it, Radio will never find the renderer later.