Forum OpenACS Development: Passing a multirow to template::adp_parse?

I have a proc that should return a fragment of html that is made
up of as many table cells as the number of rows returned from a
query. The fragment is then supposed to be placed somewhere in
the middle of templated pages. I'd like the html fragment to be
built up in the templating system rather than in the proc (html
should not be mixed with tcl). So my question is, can I achieve
this with template::adp_parse or with some other method, and if
so, how?

Has someone figured out a way to pass a multirow to the template

No matter how hard I try, I've not been able to achieve what I

Posted by Dave Bauer on

Try using upvar to create an array variable in the callers namespace.

Then build the multirow from the calling proc. Doing that you should be able to create the table in the template.

Posted by Jeff Davis on
Ola, there is a "template::multirow upvar" function that should allow
you to do what you want but I can't find an example of it anywhere in the code
(other than in the template::multirow code itself).  You might try
spitting out [adp_level], the [info level] at a couple other places
and there is a stack trace function to tell you where you are as well
(can't remember the name off the top of my head).

Once you have it all figured out you can send us a little snippet
to document it for everyone else.

Posted by Peter Alberer on
Hi Ola,

have you tried to simple pass the multirow you get from the database to an include file? You can do the formating in the included adp file. Look at the docs at your server at:


Posted by Jun Yamog on
Hi Ola,

I am unsure what you want to do. But this might help..

On you proc make an upvar

ad_proc get_foo {
   upvar package_key_foo package_key_foo
   db_multirow package_key_foo get_items "SQL"

Call get_foo on your tcl, then on your adp file you can now do

<multiple name="package_key_foo">
Another alternate is using db_list_of_lists on your proc, get result on a list, then convert the list using this. You can see the discussion here on how to use it.

Although you should only use the list of lists thingy if your proc is something that is reused on other stuff. The upvar and multirow combo is simpler. Sorry if this is out of context... my head is really fuzzy this days... too much code craming.

Posted by Dan Wickstrom on
If you use db_multirow with the -local switch you can compile and eval a template locally:

openacs4:nscp 13> db_multirow -local people get_people "select first_names, last_name from persons"
openacs4:nscp 14> set template "<multiple name=people><tr><td>@people.first_names@</td><td>@people.last_name@</td></tr></multiple>"
openacs4:nscp 15> set code [template::adp_compile -string $template]
openacs4:nscp 16> set out [template::adp_eval code]

Posted by Drazen Kacar on
Unless somebody removed it from the templating code (anybody dares to touch that, BTW? :-), a certain undocumented, experimental, yada, yada feature should work.

Here's an example:

foo.tcl file:
multirow create multi one two
multirow append multi 1 2
multirow append multi 3 4

foo.adp file:
<include src="bar" &multi=multi>

bar.adp file:
  <multiple name=multi>
If I understand correctly, this is what you want to do.
Posted by Dave Bauer on
That undocumented feature does work. The new forums package uses it.
Posted by Roberto Mello on
Oh that's great. Users of the system are aware of an undocumented feature, write a new package that use it, but don't take 5 minutes to document the feature.

Until our community starts taking documentation seriously, the toolkit is going to continue to suck for new developers. It already sucks today because there are plenty of web technologies out there that don't follow the RTFSCA (Read The Fine Source Code Already) philosophy.

I quote from our first ever full article on a major magazine (that I'm aware of - LinuxJournal this month):

"There's no way getting around it: OpenACS is a complex beast. Although the software is generally excellent, it requires an experienced UNIX/web/database hacker to use and modify it. Even the installation procedure is long and complicated, and I can assure you from personal experience that it's often hard to understand where you have made a mistake. The documentation is improving but there are many gaping holes and difficult-to-understand table structures that can be confusing."

Now it seems that that's the way our community _wants_ the toolkit because we keep writing code without function documentation, without user documentation, without any documentation; packages without even a description in the .info file. We have blatant holes in our documentation but still only one or two people touch our docs.

If that's the kind of toolkit we want (not me), than that's the kind of toolkit we'll have.

Undocumented feature? I think not...

The mechanics of passing a data source by reference via <include> was documented in /doc/acs-templating/tagref/include.html of a default ACS 4.2 install. I just checked and it looks like it hasn't been removed from the OpenACS docs either...

Which, of course, should not be interpreted as an argument against the need for more consistant documentation, just a clarification in this instance. ;-)

Posted by Drazen Kacar on
Ah. I've never seen it mentioned in the documentation. I've found it in the source when I wanted to mess with the templating system, so I thought it was undocumented. The source comment said "Experimental", I think. But it's possible that I just missed it in the docs somehow, of course.
Of course, its also worth pointing out that as newbies are the ones who generally press harder for more documentation, then perhaps we should make it easy for them to add to it, as they find holes!

Also, one of the problems with documentation is that it gets easily out of sync with development. Its also not always a good reference (whereas the code always is)...

This is hardly unique to the OpenACS. Virtually all OS projects suffer from it...

As for the comments on the OpenACS being difficult... hmmm.. has he ever tried getting JBoss/Tomcat going I wonder....?

The reality is that this is human nature. Many of the contributors here (I daresay) have to do docs as part of their job. I cn easily understand why they may be reluctant to do it for volunteer projects. After all documentation is not one of the most inspiring tasks to do is it.

Thats not to say we shouldn't bother, but I suspect we need to come up with a different/better way of documenting that works with, rather than against human nature.

Or... we end up with a dreadful scheme such a has.. i.e. you have to *pay* for the documents!... Yurrck....

Any suggestions?

I think the first thing we could do is remove/hide/defer to a less visible place, much of that 'orrible design documentation that lingers from 4.2...

Whilst its good tech doc, unless you're pretty clued up anyway its dry and complex in the extreme.

Perhaps a simple re-organisation of documentation already there (there is quite a bit) is in order first. Perhaps grouping things according to reader, rather than by-package/code..

I.e. a simpler, newbie user guide, a more details developer guide and a full on system guide... each containing the same stuff, just with varying levels of detail.

Most of the things people ask for in docs, are often there... they're just not that easy to find...

Some kind of web interface for editing the docs would be extremely helpful.  I have run across numerous additions/corrections that I could have easily made if helping out with documentation was as simple as firing up a web browser.

Of course, it's easy to ammend current documents in this kind of model, but getting th new, original documentation written would still require a more organized effort.

Posted by Roberto Mello on

We have comments enabled on the docs available at For 4.6, following an idea by Jeff Davis, we'll have a link at the bottom of every acs-core-docs page saying "Click here to comment on this document" and it'll take you to the appropriate page on

Whoever wants to work on documentation, let me know. There's plenty of work to be done (I'm reviving the "Documentation Status" with what needs to be done).

What about package documentation?  A lot of the clarifications/additions to the documentation I could have added would be part of acs-templating.
Posted by Roberto Mello on
Package documentation is trickier since we'd have to figure ouot a way to have the documentation viewable and commentable without installing the packages. If you can come up with a way and send a patch, that'll speed things up :-)
Posted by Torben Brosten on

Simon writes:

Perhaps a simple re-organisation of documentation already there (there is quite a bit) is in order first. Perhaps grouping things according to reader, rather than by-package/code..

I.e. a simpler, newbie user guide, a more details developer guide and a full on system guide... each containing the same stuff, just with varying levels of detail.

.."working on a manageable doc re-organization" and swamped with other obligations (singing: refrain) ..altogether now...=)

Seriously, anticipating the needs of readers and writers while getting a grip on the status of the system (and documentation procedures) from fragmented documentation has been challenging --but I think a workable framework is taking shape, including the new forums (to be created), Roberto's and Vinod's continued editing and mastering of Docbook SGML, and the vast number of helpful comments/questions posted on the boards by everyone.

Is there a place to post draft documentation on OpenACS -so writing/editing can be more easily shared and progress reports made self evident?

Posted by Roberto Mello on
Torsben writes:

"Is there                                                                                a place to post draft documentation on OpenACS  -so writing/editing can be more                                                                                easily shared and progress reports made self evident?"

Unfortunately not yet. However, I suspect that having such area is not the problem. If someone would like to volunteer to write documentation, even if not at first in Docbook, they would do it, as happenned with the "Top OpenACS things I learned" document that was written.

If someone is interested in writing anything for OpenACS, please write to me saying what you'd like to write. It's preferrable to get it written directly in Docbook XML (it's not hard, see tho OpenACS Documentation guide at, but at the current state of our user documentation (that would be pathetic), I'd accept text (but no HTML, it's too painful to re-write all the tags for Docbook. I did it for the "Permissions Tediously Explained" document).

Posted by Robert Locke on
> Package documentation is trickier since we'd have to figure out
> a way to have the documentation viewable and commentable without
> installing the packages

I believe Jun has already done something similar. Check out:

Posted by Roberto Mello on
Jeff Davis has already committed Jun's patch for displaying documentation for non-installed packages.