Starting Questions
This document will attempt to show you how renderers work and how to create your own to make a website render the way you want it to.
The first step is to decide that you really need to write code to do what you want to do. There is a chance that the software already does what you want. Take a look at what Text-To-HTML options exist for you. If it is a style issue, it might be addressed by a variable listed there.
If however, this is a structural issue (eg, you don’t like the navbars provided by HtmlTemplateRenderer) then you’ll probably have to write some code. If you think that your extension is generally useful, please email support and tell me about it. I might be willing to write it for you if I get the chance to extend the capabilities of the system. That way everyone wins. But, if this is something specific to your site, and not terribly reusable, read on…
The second step, assuming you get this far, is to decide if your change requires an extension to an existing renderer (eg, modify the navbar supplied by HtmlTemplateRenderer), or if it requires an entirely new renderer (eg, something like XsltRenderer).
Extending an Existing Renderer
Lets say you hate the navbar supplied by HtmlTemplateRenderer. Customizing it is pretty easy and involves these steps:
- Copy XXXRenderer to MyHtmlTemplateRenderer.
- Globally replace “XXX” with “MyHtmlTemplate”.
- Change the require statement from ‘ZenWeb/GenericRenderer’ to ‘ZenWeb/HtmlTemplateRenderer’.
- Change the superclass from ‘GenericRenderer’ to ‘HtmlTemplateRenderer’.
- Instead of defining ‘render’, change it to ‘navbar’.
- Write the code to return the type of navbar you want.
- Fill in remaining “YYY” sections (mostly doco) w/ appropriate verbage.
Writing a New Renderer
Lets say you want to write XsltRenderer, not that I have a clue about XSLT… Creating a new renderer is fairly easy:
- Copy XXXRenderer to XsltRenderer.
- Globally replace “XXX” with “Xslt”.
- Define render. In this example, it might be difficult, but some of the renderers are dirt simple and small… Check them out for examples and help.
- Fill in remaining “YYY” sections (mostly doco) w/ appropriate verbage.
Renderer Requirements
A renderer is dirt simple. It simply needs to define the method render, which takes an array of input, and returns an array of output. Other than that, you are free to do whatever you want.
GenericRenderer Utilities
GenericRenderer has a few utility methods. First, GenericRenderer instantiates an instance variable called @result. You need not use it at all, but the utility methods do. GenericRenderer also provides the following methods:
- push(obj) - appends obj to @result. If obj is an array, it recursively calls push on each item in obj. If it is not an array, it calls to_s on it and pushes onto @result.
- unshift(obj) - like push, but prepends.
Other Notes:
Other things to remember:
- @document is the instance of the ZenDocument that you are rendering. url and subpages are useful methods of this class.
- @sitemap is the instance of the ZenSiteMap for this site. documents or doc_order might be useful to you.
- @website is the instance of the ZenWebsite for this site. Not too much useful here, that I’ve used anyway… It’s mainly a manager class…