Playing With ZenWeb

Note: I found this while ego-surfing through the Wayback Machine recently. It's vintage 2002, and I'm not sure how much of it applies to ZenWeb in its current form. Still, it's sort of like documentation, and ZenWeb could use a little bit more of that!

This is the index page of a site created with ZenWeb. Let's see how it goes, okay? If this works out, we'll eventually redo all the static pages of the site with the ZenWeb tool.

So how does this thing work?

Create a directory to contain the raw, unprocessed pages of the site
Create a directory to contain the fruits of ZenWeb's labor.
Ummm...
Create a holder ruby file to define important site stuff
- index (this page)
- SiteMap (the sitemap page, yes?)
- MetaData.rb (directives for ZenWeb)
run 'ruby CNHZenWeb.rb'

Formatting is a problem. ZenWeb is supposed to feature a nifty text2html converter, but it just ain't happening for me. Is it my imagination, or are there extra newlines in there? Plus, where do I set the title?

Digging through the demo index, title seems to be set with a line like this at the top:

 #title Demo Site

True confession time. 'CNHZenWeb.rb' is just the TestZenWeb.rb copied and stripped of testing code. Maybe a more disciplined approach is in order?

Changed hash-line to actual location of ruby location
(this is cygwin, so it's a little funny-looking)
Copied "ZenWeb.rb" to "/usr/local/bin/ZenWeb"
Made a proper project directory for CNH site
- cnh
  - raw (holds preprocessed pages)
  - output (holds generated HTML)

Okay, that's a good start. Now, how about activating ZenWeb from a direct command line? No "ZenWeb --help", "--usage", or "-h" sort of options. That's always my favorite way to see what I'm supposed to be doing. Oh, well. You do get usage information when you type the command all by itself

 $ ZenWeb
 /usr/local/bin/ZenWeb:1608: Usage: /usr/local/bin/ZenWeb datadir \
 (ArgumentError)

That's kind of helpful, isn't it? It's good enough for my needs. Here's my interpretation:

datadir is a required option. It tells ZenWeb the location of your unprocessed files. You can also provide an optional sitemapurl, which is the name of the file containing your site map. Is sitemapurl relative to datadir? I dunno, but we'll probably find out soon enough.

Whoops. Hold on. I shoulda double-checked the source code. I don't need an output directory, since ZenWeb automatically constructs one within the source directory. A quick reshuffling of files should fix that... Instead of "raw" and "output", I'll just create a "pages" directory and put my raw pages in there.

So here's my command line and the output that goes with it:

 $ ZenWeb pages/
 Preprocessing website...
 Generating website...
 /index.html
 /SiteMap.html
     2 ZenDocument.parseMetadata
     1 ZenSitemap.initialize

Now I have an index page. No header or footer, though. I can worry about that in a second. Meanwhile, I am lazy enough that "ZenWeb pages/" sounds like too much typing after a while. Let's create a simple Makefile to help with this process.

 # Makefile for ZenWeb construction of the CNH site
 all:
         ZenWeb pages/

I did say simple. After I've coaxed ZenWeb into making pages all nice and neat, I can add a "make install" target.

Time for MetaData

I think metadata.txt is where I'm supposed to be telling ZenWeb about headers and footers, and maybe text2html formatting stuff.

Let's start with what looks like a simple setup for ZenWeb:

 "renderers" = [ 'SubPageRenderer', 'MetadataRenderer', 'TextToHtmlRenderer', \
 'HeaderRenderer', 'FooterRenderer']
 'header' = '<html><head><title>title</title></head><body><h1>title</h1><hr>'
 'footer' = '</body></html>'

We'll need to define what sort of renderers to use. Renderers apparently define how to build the pages. You create a Ruby list of each of the renderers you will be using. Order is important, as is remembering to use commas in between each list item. ZenWeb comes with a handy default HtmlTemplateRenderer, which makes pages that look just like what you'll find at the ZenSpider site. Pretty handy for Ryan, no doubt ;-). Me, I tend to fuss with my pages a little bit.

SubPageRenderer
MetaDataRenderer
TextToHtmlRenderer
HeaderRenderer
FooterRenderer

Hey, guess what? You don't have to use a string of text for the header! The somewhat deceptively suffixed metadata.txt is processed as a Ruby file, so you can use Ruby code for the values of your metadata. Instead of a painfully long string, I just use a statement that evaluates to a string, like so:

 'header' = File.open('/home/na/projects/sites/cnh/data/header').readlines.join

It's not ZenWeb's business to go checking if the header file has changed, so I'll have to make clean && make anytime I update the header file.

What About Metadata Substitution?

Okay, we're moving along nicely, but I still haven't figured out how to get the page title inserted into my header once it's processed.

 # title = "Playing With ZenWeb"

No, that doesn't work. I get a vague message about failure, without really describing the nature of the failure. Dangit, I hate being the proof that nothing is foolproof.

 # 'title' = "Playing With ZenWeb"

Okay, I didn't get an error message this time, but I still didn't get variable substitution. Hmmm ... What about directly embedding the metadata into this page?

The title of this page is Playing With ZenWeb.

Yup, that works. Since I know that the metadata is being processed, how might I access that from the header? AAARGH!!! I'm going to send off an email to Ryan asking about this, and play with Python for a little while.

The Next Day ...

Had a stray thought. What if I used HtmlTemplateRenderer as an example, and built my own Renderer subclass to handle the details I'm thinking of? Yeah, that might work. Gonna take a little more reorganizing, though.

Put a copy of ZenWeb.rb into the ruby site_packages directory.
Create a build script along the lines of what I started with.
Once the build script works as intended,start subclassing!

So this is the build script I came up with. It defines basic information that ZenWeb needs to know about locations and what-not.

 #!/usr/local/ruby -w
 
 #
 # build.rb
 # A simple script which will utilize ZenWeb in building the COOLNAMEHERE site
 #
 
 require "ZenWeb.rb"
 
 # Site data
 datadir    = "pages"
 htmldir    = "html"
 sitemapUrl = "/SiteMap.html"
 
 # Create an instance of ZenWebSite to render the pages.
 web = ZenWebsite.new(sitemapUrl, datadir, htmldir)
 web.renderSite()

With this script in place, ZenWeb is building pages in the same format it was with the Makefile. To get an idea of what sort of page a template Renderer might produce, we'll add the HtmlTemplateRenderer in metadata.txt.

Whoops, it still adds my header and footer stuff. Forgot about that. Just remove the HeaderRenderer and FooterRenderer from metadata.txt.

Danger Will Robinson!

Aw, crap. While I've been sitting here playing with ZenWeb, some shmuck has gone and compromised IIS. So now http://www.coolnamehere.com/ consists of an apology page. That's it. Now I'm cranky.

Hold on ... this could be a perfect opportunity to put ZenWeb to the test building a moderate-sized site! Of course, I don't have time to create my own template right now - that will have to wait until the actual content is back up.

Let me take a few minutes to copy everything I need into my working directory. Hey, this works pretty smoothly! There are a few formatting things that I needed to take care of. Working my way through those one at a time. Oh, and what's up with the SiteMap page?

And Another Day Passes

TGIF, right? It's a sad, sad person that starts their day off with a half-gallon of coffee and an hour programming. Or maybe just your everyday geek. I made my own CssPageRenderer class for the site, and gosh, it's pretty. I'm inspired now. Next up are CssSubpageRenderers and touching up the navbar so that it's a little more friendly to my grotesque CSS manipulations.

And the sitemap stuff, of course.

I think now is a good time to share the fruit of my labours with the Seattle.rb.