Hacking Radio Part 1

DocSpotting

I've been using Radio 8 about a month now, playing on my weblog, getting somewhat addicted to the outliner (and then very annoyed with its lack of some Very Simple Features like multi-level undo, but that's another story). One of the attractions of the suite was that it's not so much a weblogging application, as a platform that comes with a weblogging application attached. Being a web application programmer by trade, that sounded pretty nifty to me.

So today being a slow day, I decided to give Radio the programming environment a spin. My plan was to write a simple To-Do list application - which in practice basically comes down to "fill in a form, submit it, store the results in the object database, then read them back and list them." Simple enough, should be a good introduction to the bare bones of the system.

I started with Dave Winer's Hello World sample. Neat, it worked. Then I thought "what if instead of calling clock.now(), I write my own script in the database, and call that? I messed around with Radio.root a bit, changed the page, and viola! It worked. I was feeling pretty good at this point, so I went down to HMV and bought the new NIN live CD, and "Origin of Symmetry" by Muse.

It was when I came back that I ran into trouble. Maybe Trent Reznor and web applications just don't go together. Or maybe it was the terrible information architecture of the Radio homepage. Click on the "Developers" link, and you get a neat Hello World tutorial, and then follow-through links to two slightly more advanced Hello World tutorials. Tutorials are great, as introductions, but they only teach you how to do exactly the thing described in the tutorial. A ten line example UserTalk script is useless without a link entitled "And this is the page you read to learn the syntax of UserTalk". In the first tutorial there was a link to the directory of Frontier verbs, but without any context, that was totally useless.

I rushed around the site a bit. I looked at the hideously reader-hostile Directory. I tried the Search Engine, which like the search engines on all Manila sites, seems designed to give you everything except what you're looking for. I trawled through the discussion group until I found that the page I was really looking for was Radio UserLand: Programming Pointers, which seems to only be linked to from that discussion group post, not from anywhere I could find in the main structure of the site. I bookmarked that page, because I knew I'd never find it again if I didn't.

Okay. Making progress. I devoured the page on the Object Database. Cool. I finally found the references for script writing and UserTalk. Neato. Now to find out how the web stuff ticks. W00t! There's a Website and Scripting Tutorial.

Oh great. This has absolutely nothing to do with the way things seem to be done in Radio. In fact, it's not what I want at all. I hunted through all the links I'd amassed in my searches thus far, and was well and truly stumped.

Writing a web application is dead easy. I've done web programming in Java, Perl, PHP, ASP, Ruby, even Unix shell scripts, and it's always the same formula. A request comes in. You look at the request, find out from it what the user wants, do it, and then send back a reply. Given that the middle bit is what we call at work a "simple matter of programming", this means that the important things to find out from your application environment are:

1. How do I get at the stuff in the request?
2. How do I send stuff back?

I figured after completing "Hello World", I had the second one sorted. The first was the problem. After half an hour of poking the website in vain, I found absolutely nothing that could answer this simple question for me. Not willing to let something this trivial daunt me, I decided to look at the way the website built into Radio functions. It only took me another half hour to find the script that powers the News page, which answered my question. There's this thing called the Page Table, which you get from the html.getPageTableAddress() verb. Finally. More progress.

But what is in the Page Table? What indeed. I spent the next futile forty-five minutes trawling the Frontier site again, catching glimpses here and there of the elusive Page Table, but never getting a full description of what it could do, or how. Once again, the search function was no help at all - doing a search on "pagetable" on frontier.userland.com didn't find half the stuff I found manually. Grrr.

In the Website and Scripting Tutorial, there was a link Your Fourth Macro: the Page Table, which had some cursory information about the Page Table. There was a "More about the page table" section at the end, with a link that pointed back to... The frontier homepage. Useless.

On another page, I was helpfully pointed to a section of the root database where I should have been able to find the Page Table for the most recently rendered page. But this being Radio, not Frontier, the table wasn't there.

It's at this point I gave up. This story may or may not continue - on one hand I don't like being beaten by software, it's a pride thing. On the other hand, there are so many other development environments out there that I'm quite willing to forego the niftiness of Radio for something slightly less nifty, but significantly more effectively documented.