--> kmw (~youth@adsl-63-205-44-50.dsl.lsan03.pacbell.net) has joined #openacs
<kmw> Jim would you please set me in the right direction to correct the links from the main site page for attachments and notification and new-portal?
<jim> kmw: do you have those packages mounted?
<jim> I don't believe they have a user interface, at least not an index.html-like-thing
<jim> so, if you click on those links, it's normal for them to say "url not found"
<jim> kmw: what you might get into now is the templating system
<jim> and use such knowledge to edit /web/$service/www/index.{tcl,adp}
<jim> where $service is the name of your service (examples from your server of possible values of $service: "learn" "caltek")
<jim> kmw: would you wanna do something like that?
<jim> (I'm thinking that maybe the "Congratulations" page wasn't what you had in mind as a front page for your site?)
<kmw> ok I've printed some of the docs for the design guide portion of the templating system
<jim> kmw: cool... it's a good possibility you want to familiarize yourself with tcl?
<jim> if not already that is... I know you had an early acs or openacs, both of which had tcl available as a quick scripting language
<kmw> yes I'm very interested in learning tcl
<jim> ok...

Little Tiny Introduction To A Little Tiny Piece Of TCL

<jim> either on your machine at home... or else on the vserver... see if you have a program called tclsh
<kmw> I did the tclsh at the command line and it gave me %
<jim> ok, that's the tcl prompt...
<kmw> so i figure it's there and running now.
<jim> try these commands:
<jim> set this_variable "foof"
<jim> puts $this_variable
<kmw> ok I did those two commands
<jim> kmw: the second command should have printed "foof"
<jim> (if I remember the print command :)
<kmw> and yes I know about and have read parts of the tcl for for web nerds....and yes it did print "foof"
<jim> ok, now: put yourself in the documentor's seat...
<kmw> I'm logging this file...is that what you mean?
<jim> if you were to go about explaining those lines to the next programmer, what would you say?
<kmw> ok
<jim> (note!! the "next programmer" could be -you yourself- six months from now!)
<jim> programmers forget everything they ever learned from time to time... it's a law :)
<kmw> I'd say the first line (set this_variable "foof") creates a variable field and places foof in that variable
<jim> so, what would you put in this "time capsule"?
<jim> yes, good!
<davb> jim: i was going to say something, but I forgot what it was...
<kmw> and then the puts $this_variable prints it.
<jim> davb: umm, what was your irc nick again?? :)
<kmw> the stored content of the variable "this_variable"

More Advanced (by One Single and Simple Step)

<jim> interesting you should quote the name of the variable...
<kmw> why
<jim> because: tcl is capable of using variable names which are themselves values of variables
<jim> set this_variables_name "this_variable"
<kmw> not sure I understand fully
<jim> puts $this_variables_name
<kmw> oh I get it.
<kmw> which itself is a variable into the variable.
<jim> set $this_variables_name "hmm, where does this text end up??"
<jim> puts $this_variables_namne
<jim> oops
<jim> puts $this_variables_name
<jim> puts $this_variable
<kmw> set $this_variables_name "hmm, where does this text end up??"
<kmw> puts $this_variables_name
<jim> well, you want to put that in your tcl shell window :)
<kmw> I'm typying in the wrong window just a minute
<jim> (the reasons I'm going in this direction...
<jim>  - you suggested the direction by quoting the variable name
<jim>  - I respond by showing the significance of quoting
<jim>  - Wanted to drive home the point that $name is the -value- of the variable; name is the -name- of the variable)
<kmw> by quoting a variable it can be included as a variable in other variables?
<jim> yes, kinda works like a referral
<jim> person X looks for a job at place A
<jim> THe manager at A says: Hmm, X, looks like you'd be able to do job I...
<jim>                        yaknow, place B is looking for someone that can 
<jim>                        do job I...
<jim>                        I have a buddy at B, HERE IS HIS PHONE NUMBER
<jim> (the all-caps passage is the "reference")
<kmw> ok the value contained is reference by $variable and varialbe is just the name to refer to the variable.
<jim> yes... you'll use that occasionally... it's important to see that possibility of expression in this language
<kmw> ok

How To Use Simple Variable Substitution in OpenACS Templating

1. From The Designer's Perspective (or, USING a data source)

<jim> now...
<jim> you know how to alter the contents of a variable (set name value) 
<jim> and
<kmw> yes
<jim> you know how to refer to a variable in TCL
<jim> $name
<jim> another example of this same concept...
<jim> acs templating system can use values of TCL variables
<kmw> ok
<jim> let's create an example...
<kmw> great!
<jim> lessee...
<kmw> can we work on practical pages that I need to do anyway?
<jim> given that neither learn nor caltek has a customized front page...
<kmw> yes yes yes
<jim> let's muck around with that :)
<kmw> good idea
<kmw> exactly what i need to do.
<jim> would you like to edit the front page first, or create a new page for now?
<kmw> edit the front page.
<jim> either way, ssh to (your server) as nsadmin
<kmw> ok I'm there.
<jim> ok, remember where the learn server files are located? (where were you when you did the cvs checkouts)
<kmw> I think it's /web/(my service)
<jim> yes, exactly
<kmw> i'm there
<jim> the main pageroot for the learn server is /web/(your service)/www
<kmw> i'm there
<kmw> default-master.tcl
<jim> ok, notice lots of files that start with "index"...
<kmw> 5 of them
<jim> yes... 
<kmw> only 1 .tcl
<jim> some of those are relative to database functionality
<kmw> ok
<jim> the actual template is two files:
<jim> index.tcl
<jim> index.adp
<kmw> ok
<jim> the basic idea is this:
<jim> index.adp is where the augmented html stuff goes
<jim> (augmented, that is, by the extra tags in the templating system)
<kmw> ok
<jim> you said you printed the designer's guide? (http://(your server)/doc/acs-templating/designer-guide.html)
<kmw> yes I have it here now.
<jim> take a look at your printout and see how to form a reference to a TCL variable
<kmw> I do not see form a reference to a TCL variable on this page
<jim> ok... 
<jim> do you see anything whose words might suggest something similar?
<kmw> embed a dynamic variable in a templte
<kmw> repeat a template section for each object
<jim> that first one sounds like the one
<kmw> var
<kmw> is the word that they link to the details page
<kmw> Simple variable are referenced bysurrounding the variables named first_name and last_name and substitute ther values in the output
<jim> so, what do you have to do to the name of a TCL variable to get the .adp to interpret it by replacing it with the value?
<jim> surrounding? with what?
<kmw> put them in quotes
<jim> quotes? no...
<jim> look again :)
<kmw> variable name sith the at signs or @
<jim> yes!
<jim> so... say I have a tcl variable called var
<kmw> oh it quoted "commercial at"
<kmw> ok
<jim> how would I have the templating system replace that variable (called var) with its value?
<kmw> then we reference it in a .adp file by @var@
<jim> YES!
<jim> this is the simplest example of a "data source"...

Aside: About Data Sources, and Separating Programmer and Designer

<jim> in all data sources, you write TCL code to "supply" the value of the source (which goes in the .tcl part of the template)... 
<jim> and you write various forms in the .adp part of the template to -use- the data source
<jim> reason for separating this way:
<jim> the programmer can be just a programmer, and leave graphics to the designer...
<kmw> wow that's great!
<jim> and the graphics designer/html coder can be just that, having to learn a handful of tags while leaving the programming aspect (technical details of forming or creating data sources) to the programmer
<jim> the programmer stays -away- from how the page will look
<jim> and gives the data to the graphic designer
<jim> who -decides- how that data is to look on the page
<jim> specifically...
<jim> the programmer writes the .tcl (and also includes a "contract" of data sources)
<kmw> that's what the contract module is about?
<jim> the graphic designer writes the .adp (and looks at the programmer's contract to see what data sources are available and what they are)
<jim> no, acs-service-contract is for something else
<jim> I haven't figured it out all the way myself

End of aside. Now, put on your Graphic Designer hat!

<jim> kmw: ok, you're now a designer...
<jim> and you see in the contract (-properties section) this:
<jim>    time_of_day : onevalue
<kmw> hey the concept is heavy and it confirms why tcl is a good graphical UI.
<kmw> where is the contract...in the .tcl file?
<jim> this means time_of_day is available to the .adp as @time_of_day@
<jim> the contract would be there, yes... at the top...
<jim> (thing is... we haven't yet put the variable there :)
<kmw> ok I'm in the index.tcl file and it has ad_page_contract
<kmw> I need to get back to using emacs
<jim> use any editor you want
<jim> we're going to start with the .adp first
<kmw> ok
<kmw> It has <master> at the top
<jim> we're -pretending- you (with your designer hat on) see: 
<jim>    time_of_day : onevalue
<kmw> this refers to a template...
<kmw> can I add it. here.
<kmw> ??
<jim> yes, it is itself a template, and it uses also, a master template
<jim> let me make that statement once more
<jim> yes, index.adp is itself a template, and index.adp uses also, a master template
<kmw> got it.
<jim> sometimes you feed values to the master
<jim> but we're just going to put stuff in the index.adp template
<jim> does the <master> have some <param ... > lines after?
<kmw> no
<jim> OK...
<jim> have you noticed most acs pages have a header, a horiz rule, the content, anothe horiz rule and a signature?
<kmw> at least I do not think they are param it says <property name="title">@system_name@</property>
<kmw> kind of noticed that.
<jim> property, yes, that's the name I was thinking of
<kmw> it has two lines with that tag
<jim> those are examples of how to feed values into the master template
<jim> ok, what's the next thing after that?
<kmw> so it lists the master and then it feeds variables into the master templete that it's loading?
<jim> yes, and the master template then does anything it wants with those values
<kmw> Congratulations.
<kmw> then it starts a table after that.
<jim> ok, now, make it look like this:
<jim> Congratulations. The time of day is @time_of_day@.
<jim> that's an example of the designer using the "time_of_day : onevalue" contract item
<kmw> and also put the : onevalue" and contract item???
<jim> no, make the .adp look exactly as I said earlier
<jim> just this:
<jim> Congratulations. The time of day is @time_of_day@.
<jim> ok, if you did that part, save the file
<kmw> ok it saved the index.adp file

How To Use Simple Variable Substitution in OpenACS Templating

2. From The Programmer's Perspective (or, CREATING/ESTABLISHING a data source)

<jim> (right now your index page is broke... we'll fix it now...)
<kmw> now go check, right?
<jim> nono
<jim> it's not ready yet
<jim> because: the data source is not created or contracted
<kmw> ok i see that.
<jim> it should have given you this long error message, the jist of which is "I don't even know the time_of_day"
<jim> essentially, we're using something like a mailbox that hasn't been built yet
<kmw> i reloaded the page that already has me logged in so who knows....
<jim> so there's no place to store time_of_day yet
<jim> but now, let's make one
<kmw> so now do i open the .tcl file?
<jim> yes
<kmw> oh one moment it gave me cannot open file for saving...
<kmw> hi candy
<kmw> I'm not logged in as nsadmin
<kmw> i'll save it to another file and then copy it over once I login as nsadmin
<jim> ok
<jim> sounds like a potential time-saving plan, whose premise is "I don wanna type this thing again!"
<kmw> ok i've changed it and now I'm in the index.tcl file.
<jim> ok, now, do you see other data sources listed in the contract?
<kmw> I'm looking
<kmw> I see properties with system_name:onevalue 
<kmw> I see $user_id == 0
<jim> there we go, yes, this is a section of the contract called the properties section
<jim> so first, you should add a line in the properties section
<kmw> it lists about 7 of them
<jim> what you're adding should be lined up with theirs on the left, and should read: time_of_day : onevalue
<kmw> does it matter where in the properties and it already has 12 of them not 7
<jim> shouldn't matter which of the (13?) it is
<jim> howbout putting it first or last...
<kmw> it';s last
<jim> so you can get rid of it when you didn't want it :)
<jim> ok... now, you want to get totally outside the contract...
<kmw> I do want it. I will edit out some of the others though
<kmw> ok
<kmw> I figure the } closes it.
<jim> now, put this: set time_of_day "the ONE thing Natalie Portman forgot to give me yesterday"
<jim> once you save that, try reloading the page
<kmw> done
<kmw> ok
<jim> you should get the time of day in really big letters :)
<jim> (why is it really big?)
<kmw> I get a request error can't read "time_of_day":...
<jim> where did you put the set?
<kmw> oh I had not saved the .tcl fine...it's big because it's in a set of <h2> tags. I'll fix it, now.
<jim> :)
<jim> you got it
<kmw> try it now.
<jim> :)
<jim> it works!

End Of Simple Variable Substitution In OpenACS

<kmw> now how do I put the actual time in there?
<jim> the idea behind this, is a programmer who knows tcl or is learning it would be the one to edit the .tcl, and the designer who for all intents and purposes doesn't want to know what the programmers do, or learn TCL or SQL
<kmw> this is a very good way to learn.
<kmw> I have a designer that is like that.
<kmw> I spoke to him for over and hour, today.
<kmw> he gave up on oacs last year because it was too complicated.
<jim> he won't need to know any of this stuff :)
<jim> otoh, he can learn if he chooses to get back on the horse
<kmw> but now he will give it another chance so I will walk him through it.
<jim> all he will need, is the extra tags, and how to read the contract, and what tag to use with what kind of data source
<jim> before we get to actual time...
<kmw> ok
<jim> I want to point you to a few different places you should read at this point
<kmw> ok
<kmw> also I want to know what I should put in attachments and notifications...not sure I understand why the are on the main site.
<kmw> plus the new-portal link doesn't go where it should...I'm wondering of the permissions have something to do with that.
<kmw> then there's figureing out how people can be a dotLRN user once they become a user.
<kmw> without me having to add them as a dotLRN user.
<kmw> one by one.
<vct> you guys have done alot, Ken I am heading back to the office in 10 minutes
<kmw> great! see what headset she is using, please.
<jim> first, http://(your server)/doc/acs-templating/tagref/variable.html
<jim> read thru that... here's some more places to look at:
<jim> . http://(your server)/doc/acs-templating/demo
<jim> look at the very first demo ("simple variable substitution")
<jim> (there are four things to look at: what the tcl code looks like, what the adp template looks like, the combined form of the template that is finally interpreted, and lastly, the resulting page
<jim> )
<kmw> I have the first one printed out and the second one as well, I think I'll check
<kmw> oh the second one is the demo
<kmw> I understand the first 2 and the last one but where will I find the combined form?
<jim> you won't, generally... it shows you that so you know what that internal form looks like
<kmw> oh I see it in the table of links from the demo table...that's neat. It should be link to from an obvious place in the docs.
<jim> yes, if you look at the first page of the acs templating docs (from /doc), you'll see it at the bottom
<kmw> this Sample demo page is great.
<jim> the demos show what can be done with the templating system
<jim> and also give examples of how

Using A Multi-Row Data Source To Capture And Display An SQL Query Result

1. From The Programmer's Perspective (Making The Data Source Available)

<jim> next...
<jim> you understand what an sql table is?
<kmw> I think so.
<kmw> it's like a spreadsheet
<jim> look at it like a specially set up spreadsheet
<jim> (yep :)
<kmw> with one record per row
<jim> right, and one column per column :)
<jim> each column is a named item of data
<kmw> one column per field or variable
<jim> yes, that's right
<jim> let's unbreak the page a bit...
<kmw> sounds good to me.
<jim> html comments look like: <!-- html comments go here and the end of the comment is -->
<kmw> Yes
<kmw> less than bash
<jim> so now, comment out the part where we added the time of day
<jim> in the .adp
<jim> the effect of that, the code will still all be in place but won't actually read that variable
<kmw> the whole thing or just the response. I figure the whole thing for now.
<jim> yeah, just the thing we added
<kmw> do I need to do both the time_of)day:onevalue and the set part?
<kmw> or just the set part?
<jim> no, you can leave both of those
<jim> I'm talking about -just- in the .adp
<kmw> I must be in the .tcl file.
<jim> (comments in .tcl look like: # comment)
<kmw> ok I did it..I better check it.
<kmw> ok it's back to the way it was.
<jim> "I better check it" YES. EVERY time.
<jim> that goes in my "practice what I preach" file :)
<kmw> I've learn to do that from all of the html stuff I've done.
<jim> now, we're going to try to get rows from a database table
<kmw> fantastic....
<jim> AND we're going to separate it, just like before, into roles of designer and programmer
<kmw> can we do it with a form?
<jim> we're going to start with programmer first
<kmw> makes it easier to understand.
<kmw> ok
<jim> I was thinking we'd jsut do a simple query first
<kmw> fine with me
<jim> before we go forward, we've seen a tiny little bit of TCL, and actually used everything we saw
<jim> it's time to start you with studying "TCL for Web Nerds" for the next week or so
<jim> http://philip.greenspun.com/books/tcl
<kmw> great!
<jim> you know where to get it?
<kmw> I've read some of it before so it should go pretty quick
<jim> ok...
<kmw> yes I do.
<jim> good.
<jim> cool :)

Properties Of Languages (Means Of Combination, Means Of Abstraction)

<jim> so, as far as the TCL for web nerds thing, that will give you some ideas, rules, language elements and especially means of combining
<kmw> right. I'm looking at the website now.
<jim> "means of combining" is, "how do I take the little primitive things and build bigger things from the pieces?"
<kmw> ok
<kmw> combine and resuse
<kmw> reuse
<jim> something else that we did deal with today, is "means of abstraction"
<kmw> was that the variable of variables?
<jim> which is, how do I take things (things that are primitive OR things I have built into bigger things) and giving them names...
<kmw> abstraction
<kmw> so that's what that means.
<jim> after you give something a name, you can use it exactly as if it's always and forever been part of the language
<kmw> wow
<jim> so...
<jim> if you take "means of combination" (the ability to build big things out of smaller things) and "means of abstraction" together, 
<jim> you come up with a system that is wholly extendable
<jim> take that in reverse..
<jim> if someone tells you that their favorite language is really cool...
<jim> you can ask: "Why?? Tell me the means of combination available in the language! (How can I build things?) Tell me the means of abstraction! (How can I name things?)"
<kmw> I like these concepts. I'm trying to apply them to other things.
<kmw> like compreshion and art
<kmw> compression and art relating to abstraction and combining
<jim> Look at Escher...
<jim> he did a lot of repetitive pieces
<kmw> right
<kmw> or even dali or background images.
<jim> in many things he did, the next piece is the current piece after applying some steps of a process to it
<kmw> ic
<kmw> combining and abstraction..it's good to understand what they mean
<jim> yes
<kmw> in the context of what we are doing.
<jim> (that part of this was taken almost directly from a lecture I saw from a video)
<jim> ahh...
<davb> which was a guess of appropriate SQL syntax.
<jim> ok... kmw: edit that index.tcl
<kmw> ok
<jim> in the contract, put this into the properties section:
<jim>     user_attributes : multirow
<paje> somebody said multirow was a db_multirow.
<jim> got that part?
<kmw> ok I added it
<jim> ok, cool...
* GEM catches up and wishes that he had enough brain to have actually read through the tutorial
<GEM> http://openacs.org/wp/display/491/
-oacs-chump/#openacs- A: http://openacs.org/wp/display/491/ from GEM
<GEM> A:|Skeletal "What to do after you have installed OACS" guide
-oacs-chump/#openacs- titled item A
<jim> when the designer reads that, he says: "Oh, that means I can put something like '<multiple name="user_attributes"> ..... </multiple>' in my .adp file!"
<kmw> ok
<jim> a multirow data source is simply a holding area for something that's the same shape as an sql table
<kmw> i get it.
<GEM> kmw: do you know about the blog of this channel?
<kmw> is that what davb has on his site?
<GEM> I just put the URL for my "what to do after COngratulations" presentation there for everyone to see :-)
<GEM> yes, at http://www.thedesignexperience.org/openacs/ircblog/index.html
<kmw> is that the same one that's on the openacs.org/wp/display/491?
<GEM> Yes, it is
<kmw> I'm there now.
<GEM> I just put it where you can find it without me being around
<kmw> thanks.
<GEM> It is just beginning, now.  I should steal things that Jim has been telling you to improve it
<jim> GEM: the transcript of the leading-up-to-congratulations page is available too :)
<kmw> it will be good to work with Jim and we can add to it.
<GEM> Jim: I was hoping so
<jim> look at 12.155.172.152/files
<GEM> Anyone want to collaborate with me on the presentation?
<jim> not me for awhile at least... I dumpped many units on myself yesterday :)
<kmw> I'm tempted to try...I can at least work through and add things that I can.
<jim> kmw: ok, what I want here, is for the database to pass me back first name and last name of each user
<kmw> ok
<jim> that information happens to be in the persons table
<kmw> ok
<kmw> user table?
<jim> that is, the way the aD people set it up,
<kmw> I read about the party table as well.
<jim> they split up the original acs-3 users/groups setup
<kmw> it make sense to me why the did it.
<jim> into users, groups, parties, persons and at least one more that I'm forgetting
<kmw> it adds another level of abstration...did I say that right?
<kmw> abstraction...if I can spell it right.
<jim> yes, and also offers different means of combination that may or may not have been available before
<kmw> ok
<jim> but for now, we're just interested in first and last name...
<jim> I think the query goes like this: select first_names, last_name from persons
<kmw> ok where do I go to do that?
<jim> that will give us every row in persons, but only give the first_names and last_name field
<kmw> in the same /web/(my server)/www folder?
<jim> kmw: we're going to put that in the index.tcl file
<kmw> ok I'll open it, now.
<jim> but tcl doesnt know sql... so we have to do something after to have tcl ask postgres to run this query
<kmw> it is open I last added the user_attributes:multirow
<kmw> ok
<jim> in your browser, go to /api-doc
<jim> (on any server you have rights to see that)
<kmw> i'm there.
<jim> you're looking to search for the aD TCL proc called db_multirow
<jim> read that description... and I'll be back in a few
<kmw> I'll be back in a few minutes....
<kmw> ok Jim I read the db_multirow (public) document  so I know a bit more about what it does..think I'm ready for a practical example, now

How To Read Command Line Syntax Specifications (simple; maybe not complete)

<jim> ok, see those things enclosed in brackets?
<kmw> this aurguments and options?
<jim> ues
<kmw> yes usage:
<jim> exactly... brackets means that part is optional (or, more definitively, "can appear either once or not at all")
<kmw> ok
<jim> so, what is the first thing in db_multirow that -has- to be there?
<kmw> column
<kmw> rownumber
<kmw> the are automatic
<jim> no... look in the usage statement
<kmw> [ -local]
<jim> that's enclosed in brackets, so it doesn't have to be there...
<kmw> ok  var_name
<jim> yes :)
<kmw> var_name: 1
<jim> we want db_multirow to dump its results into the variable we named earlier, in the contract
<jim> what name is that?
<kmw> user_attributes
<jim> yes!
<jim> so far, our statement reads:
<jim> db_multirow user_attributes
<kmw> ok
<jim> what is the next necessary part?
<kmw> then we need statement-name
<jim> yes... here, we can be sorta arbitrary...
<jim> the statement_name is used if the query is different between oracle and postgres
<jim> (if that were the case, then we'd store two different versions in these other files that also start with index)
<kmw> ok
<jim> but the query we have so far is very simple, and it does work with both
<kmw> ok
<jim> but we should give our statement a name... we can call it get_user_attribs
<jim> and so, our statement so far is
<jim> db_multirow user_attributes get_user_attribs
<kmw> so now we have db_multirow user_attributes get_user_attribe
<jim> so far, you can clearly see that there are three things in this statement
<jim> the command name, the variable name and the statement name
<kmw> now one or two more things...ic sql and code_block
<jim> ok, the sql
<jim> we defined that earlier... we were going to use select first_names, last_name from persons
<kmw> ok

A Means Of Combination In TCL: a TCL list

<jim> (look at what I just typed... can you easily tell my narration from the sql query?)
<kmw> and the code_block?
<jim> we're not going to supply a code block
<kmw> just because I'm following along on the printed sheet
<jim> ahh :)
<jim> reason we might supply a code block: if we would do some special calculation that happens every row, or if we want the ability to knock out rows
<kmw> ok
<jim> but all we want to do is put all the data from the query into this holding area (which we are calling user_attributes)
<kmw> ok
<jim> we defined that earlier... we were going to use select first_names, last_name from persons
<kmw> that's the first_name and last_name, right?
<jim> (look at what I just typed... can you easily tell my narration from the sql query?)
<kmw> kinda
<jim> you can because you quickly understand english...
<kmw> right.
<kmw> it's in English
<jim> you probably have seen the word select before, too
<kmw> not sure what you are referring to.
<kmw> the word select
<jim> so you figure the query probably starts from the word select and goes to the end of the line I typed
<jim> we were going to use select first_names, last_name from persons
<kmw> yes
<jim> TCL doesn't understand english :)
<jim> TCL has no way of discerning narration from active items
<kmw> ok
<jim> notice when you look at the page that describes db_multirow, that the parameter called sql looks like -one- entity
<kmw> yes
<jim> consider the following possible completion of our statement:
<jim> db_multirow user_attributes get_user_attribs select first_names, last_name from persons
<kmw> ok
<jim> here's what TCL is going to think:
<jim> user_attributes is the variable name
<jim> get_user_attribs is the name of the database statement
<jim> select is the sql (umm...)
<jim> first_names, is the code block
<jim> ERROR: extra garbage at the end: "last_name from persons"
<kmw> ic
<jim> so, we need a means of combination
<kmw> ok
<jim> we need to make select first_names, last_name from persons look like -one- thing
<kmw> will quotes do it?
<jim> (instead of 5 things)
<jim> Yes, it will.
<jim> but so also will {}
<kmw> curley brakets?
<jim> yep
<jim> makes it -one- list
<jim> so, instead of the FIVE words select first_names, last_name from persons
<jim> we will have the ONE list {select first_names, last_name from persons}
<jim> so, our completed statement now reads:
<jim> db_multirow user_attributes get_user_attribs {select first_names, last_name from persons}
<jim> db_multirow now sees THREE arguments (not seven)
<kmw> or so we have 3 objects in the statement
<jim> right!
<jim> go ahead and put that in there, in a similar place you put the set from before (outside of the ad_page_contract)
<kmw> ok
<jim> the programmer is done with this data source :)
<jim> now, the designer can use it
<jim> (save the .tcl, take off your programmer hat, put on your graphic designer hat, and open index.adp)

Using A Multi-Row Data Source To Capture And Display An SQL Query Result

2. From The Designer's Perspective (Deciding How The Data Will Look)

<kmw> ok
<jim> pick a spot in the page, howbout right after the commented-out section that displayed the time_of_day?
<kmw> ok
<kmw> before or after the <hr> line?
<jim> remember you ran into a phrase in the docs that said "repeat a section of template for each object"?
<kmw> kinda
<jim> that's what <multiple ... >   (repeated section)   </multiple> does
<kmw> ok
<jim> but it sequences through the ROWS... the repeated section is repeated one time for each row in the multirow data source
<kmw> ok...i get that
<jim> let's try a first cut of rendering your user names...
<kmw> ok
<jim> in the place you have chosen, put this: 
<jim> <multiple name="user_attributes">@user_attributes.first_names@ @user_attributes.last_name@ </multiple>
<jim> or, let's try a -really- first cut... (make it look not too good ;)
<jim> <multiple name="user_attributes">@user_attributes.first_names@@user_attributes.last_name@</multiple>
<kmw> that's what I thought...what's the difference between the two times you typed it in above?
<jim> <multiple name="user_attributes">@user_attributes.first_names@@user_attributes.last_name@</multiple>
<jim> kmw: I figure a first cut might involve trying no spaces first
<kmw> i broke it at the @@
<jim> ok, save the file and let's see if it works :)
<kmw> ok
<kmw> done
<jim> view the page, tell me what you see
<kmw> it put our names in there.
<jim> lemme add a few more users...
<jim> actually, I'll hold off on that for now...
<jim> is there anything wrong with the listing you see?
<jim> or maybe more than one thing?

[Note to reader: If you are now following along by actually doing the
examples, please view the resulting page, and form opinions based
on what you see, then continue from here]

<kmw> not sure what you are talking about.
<jim> (remember two things: you're the graphic designer... you have all these -standard- html tags you can use...)
<kmw> the listing...yes
<jim> what do you see?
<kmw> they are not seperated by commas or spaces
<jim> commas? ok...
<jim> put a comma right at the end, just before </multi
<kmw> ok
<kmw> done
<jim> ok, I see the commas now...
<jim> ok, next...
<jim> put the word 'start' before <multi (no spaces)
<jim> and put the word 'end' after tiple>
<kmw> done
<jim> ok, I see the start...
<jim> and end
<jim> so, notice you can put things that do not repeat before and after the repeating section
<kmw> ok
<jim> can you think of html tags that are similar to that?
<kmw> so that it loops through
<kmw> no I can't think right now.
<jim> oh, uhoh :)
<kmw> <html>
<jim> toomuchinfo?
<kmw> from several sides at once.
<kmw> i'm multi tasking
<jim> ahh
<kmw> but you are priority so you have the main pipe
<kmw> I try to respond quickly
<jim> can you think of a set of standard html tags that have one beginning, possibly repeating in the middle and one ending tag?
<kmw> table
<jim> yes :)
<jim> that's one, can you think of another?
<jim> howbout ul and li? or ol and li?
<kmw> list yes yes yes
<kmw> what should i put?
<jim> so... notice however, that you have -successfully- rendered the output of an sql table! (maybe it doesn't look good/cool/the way you want, but you got the data from the table on the web page. -big- success. you used templating to display an HTML table.)
<kmw> exactly
<kmw> I feel empowered...
<jim> so will your graphic designer
<jim> you already did one thing successfully... but now, we will assume/pretend you're not satisfied with the look, and you want to try a different look
<jim> replace the word start with <ol>
<jim> replace the word end with </ol>
<jim> put <li> right after <multiple name="user_attributes">
<kmw> ldone
<jim> look now :)
<kmw> refresh it now.
<jim> replace <ol> with <ul>
<jim> replace </ol> with </ul>
<jim> ahh, no more comma
<kmw> done
<kmw> bullets
<jim> ok, cool
<jim> replace <ul> with <table><tr><th>First Name</th><th>Last Name</th></tr>
<jim> replace </ul> with </table>
<jim> replace <li>@user_attributes.first_names@ @user_attributes.last_name@
<jim> with
<jim> <tr><td>@user_attributes.first_names@</td><td>@user_attributes.last_name@</td></tr>
<kmw> done
<jim> ok...
<jim> replace <table> with <table border="1">
<kmw> ok
<jim> that gives you a few ideas...

End of Using A Multi-Row Data Source To Capture And Display An SQL Query Result

At this point, we have seen two of the approximately 14 extra tags that
the OpenACS Templating System introduces to the set of plain, standard
HTML for use in .adp files.

See demos of the others in http://(your server)/doc/acs-templating/demo/ 
which will also show how they achieved the result you see. In addition
to the result, you can get: the HTML fragment that goes in the template,
the TCL code that produces the data sources rendered by the template, and
the raw code produced for running the template.