Learning Radio

The following was posted to the Radio-Dev list by Jeremy Bowers:

I think one of the biggest hurdles to jump in learning Frontier and
Radio Userland is coming to the understanding that there is no such
thing as Frontier and Radio UserLand from a development point of
view.  There are at least four seperate components interacting:

1. The Object Database, and how that interacts with Usertalk. Normally
one would not mention data structures, but the ODB is so unlike most
data structures most programmers are used to dealing with that it takes
a bit of work to get used to.

2. The language Usertalk, which is "Algol-like" (translation: it has its
own syntax, but it's not a completely foreign language like LISP might be.)

3. The basic web server framework, built in Usertalk and sitting on top
of the ODB (Object DataBase), which for most programmers boils down to
learning about html.getPageTableAddress() and what's there. (Bit of
advice: Create a simple web page that copies the complete contents of
the page table into the "workspace" or "scratchpad" table, and examine
what happens to it as you change the querystring and form submission
stuff. In Radio Userland, pay particular attention to the radioResponder
table.)


4. The application you are trying to work with, be it Manila, or the Radio

Weblog, or the Radio News aggregator, whatever. Learning this depends on
the previous levels, but they are essentially seperate applications, with

their own data structures, API, and metaphors.


There are two basic properties of this list I've built:

1. The further down the list, the more change has occurred recently. The
ODB is virtually unchanged from Frontier 4/5, which Matt's book covers,
and perhaps for longer then that, as I started at the Windows release of
Frontier 5.  Usertalk is also virtually unchanged, except that it has
picked up more built-in verbs that have expanded the power of the system
greatly. Few of these additions, if any, invalidate stuff in Matt's book.

If you REALLY want to learn Radio Userland or Frontier, I'd recommend
proceding down the list, mostly from top to bottom. Learn just enough
Usertalk to play with the ODB for a bit, then play with that until you
mostly understand it. (Frontier/RU's UI makes this easy.) The learn some
Usertalk. (You need not become expert in it.) Then, depending on what
you're doing, start working with 3 and 4 as your application calls for.
Your startup overhead is a little higher, but you'll move faster through
the higher levels of organization.

2. The further down you go, IMHO the more sparse the documentation. The
ODB and Usertalk are abundantly documented. IMHO most of the problem
here is that people don't know this is where they need to start. Then
the website framework is a little less documented, especially as
RadioResponder is still new and not necessarily written in stone yet.
Finally, you get down to the Radio Weblog or something and the only real
documentation is the source itself, because it's still in flux and
really can't be documented yet.

The good news is that if you start from the foundations, you can handle
that. My Custom Blog Post tool was done entirely with just reading the
weblog code and figuring out how to insert posts. Userlands code is
adequately commented for most purposes, and hopefully you can reason out
the rest by the time you're reading it.



So, the real challenge in finding the documentation is knowing where to
start and what to search for, and not trying to jump too far too fast.
Like I said, you don't need to become an expert in Usertalk to do real
interesting stuff, but it'll be difficult to work with your weblog posts
if you have absolutely *no* understanding of Usertalk.  So, to become a
truly effective Frontier user I'd recommend the following ordering:

1 & 2. The ODB and Usertalk: Generally, you learn these together. Dr.
Matt's book is an excellent place to start.
http://www.ojai.net/matt/frontierDef/ch00.html
Any but the simplest macros will have to reach into the ODB, or use
Usertalk verbs beyond the simplest ones.

I recommend reading through and doing to chapter 6 of Dr. Matt's to
start with, plus chapter 12. As needed, consult 7-13. Cover others as
needed. Most things still apply. Hit the Docserver
(http://docserver.userland.com/) to see what's been added since then;
you'll now understand that stuff, having learned the foundation.

Any other Frontier resource that you can find will likely do. Simply
searching Google for "Frontier Tutorial" turns up a likely looking front
  page; I'd just advise staying away from things talking about "Web
pages" unless you're going to use the older frameworks. (One of which
now goes by the name "Static Sites" tool, which I still use for my main
website, so that's not entirely impossible.) Don't be afraid of the age
of the resources. If they talk about doing something and it doesn't work
for you, generally because some table they refer to doesn't exist on
your copy of Frontier/RU, just ignore it and move on. This won't happen
often.

(The outliner comes under this heading; most of what the books say still
applies. If you want to really dig, it may be worthwhile to wait until
Userland swings back around to the outliner. I'm looking forward to
this, the possibilities are interesting.)

3. The basic webserver framework: Frankly, I've learned all I need about
the system by copying the page table into a temp table, looking at it,
and either extracting or changing the parameters I need. (For instance,
there are a couple of points in Custom Blog Post that write the "Title"
attribute of the page table dynamically, depending on what template
you're using.) The best way to understand this for most uses is to take
the black-box approach... here's what it does, here's what happens if I
change this, who cares why. Again, odds are most/all of what you need is
in the pta^.radioResponder table (using the convention that most webpage
scripts have "pta = html.getPageTableAddress()" near the beginning).

You can probably skip this if you're writing website macros that never
take input from the user, but you'll usually even if you think you don't
want input, you will anyhow really soon.

4. The application level: I wish I could just point you at a
three-screen web page that had everything you need to work with, but
it's not that easy.  The ride is not free. But I do promise you the
bang-for-the-buck is quite good. :-)

And there are people who want to help you :-) It's not as bad as it
looks, honest.  A lot of the time you can get by just by looking at data
structures, which now all largely reside in weblogData.root.

To the extent possible, pull the code out into a seperate sub-routine
that is NOT contained in a webpage, so you can use the surprisingly
wonderful Frontier debugging facilities. (I can't speak for Userland,
but I suspect that the nice debugging facilities in Usertalk has a lot
to do with how quickly Userland is able to create and release code.
Harness that advantage for yourself every way you can. Once you learn
debugging, you will literally never want to be without it again. (Poor
debugging facilities is my biggest complaint with Python.))

Finally, this is all my opinion, so add a gigantic IMHO to the whole
message.  But this is the order I learned things in, and it has served
me well.