OpenACS Templates

As you can see, ad_page_contract makes it easy to pass
individual text strings to the template. But in many cases,
particularly when retrieving results from a database, we want to
pass lists of values. OpenACS templates take care of this without
any problem. For example, the following .tcl page retrieves the
list of users on the system and places that in a “list” data
source:

As you can see, our SQL query returns a single column, named
users. The OpenACS database API turns this into the Tcl list users,
which we then export as the users' data source. But because we
export it with the :onelist descriptor, an .adp page can iterate
over each individual element:

<master>
<list name="users">
<li> @users:item@
</list>
</master>

Our iterator is <list>, the contents of which execute once
for each element in the list. The current element is available as
@users:item@; the number of the current iteration is available as
@users:rownum@, and the current iteration is available as @users.

If you want to iterate over multiple database rows, your .tcl
page can export a multirow. A multirow contains all of the rows
that were returned, with column names. Here's the Tcl side of
things:

The db_multirow procedure takes three arguments: the name of
an array that will be populated (and exported as a data source),
the name of the query (which is used in conjunction with
database-independent .xql files) and the fallback query that is
used if no .xql file is found. In the .adp template, we can then do
the following:

There are two tricky things to note here. First, the iterating tag
is multiple, even though the data source is exported as a multirow.
Using the wrong name in the wrong place can create
hard-to-understand bugs. More subtly, the element selector within a
<multiple> tag is a period (@users.email@), while it's a
colon (@users:item@) in a <list> tag. I find myself
constantly making mistakes on this and checking previously working
pages of code to ensure that I use the right syntax with the right
page.

Inputs

So far, we have only looked at ways in which ad_page_contract
allows us to export data from the .tcl page to the .adp page. But
.tcl pages can accept inputs as well, via either GET or POST
requests. ad_page_contract allows us to specify which inputs we
expect to receive, to assign default values as necessary and to
check that the inputs are in a particular format:

In the above example, the .tcl page expects to receive a
parameter (via either GET or POST) named foo. The parameter's value
is then used in the creation of a new data source, foo2, which
contains a doubled version of foo.

If someone invokes the above page without passing a foo
parameter, OpenACS automatically produces an error message that
looks like the following:

We had a problem processing your entry:
* You must supply a value for foo
Please back up using your browser, correct it,
and resubmit your entry.
Thank you.

We can give foo a default value if it is not passed, by
making it the first element of a Tcl list and giving a default
value as the second element:

So invoking this page with a parameter of foo=abc will produce
output of “abcabc”, and invoking it without any parameter will
produce output of “blahblah”.

We can add one or more options to each parameter to limit the
types of information that we receive. For example, we can trim any
leading or trailing whitespace from an input parameter or ensure
that we only receive an integer greater than zero:

ad_page_contract {
} {
sometext:trim
anumber:naturalnum
}

You can use multiple options on a parameter by separating
them with commas:

ad_page_contract {
} {
sometext:trim,nohtml
{anumber:naturalnum 50}
}

The above page contract says that anumber must be a natural number,
with a default value of 50 if nothing is specified. sometext will
be trimmed for leading and trailing whitespace but may not contain
any HTML tags. There are related html and allhtml options that
allow safe HTML tags and any HTML tags, respectively.

Page contracts can get even fancier. For example, you can
create a date selection widget with the ad_dateentrywidget
function. So you can imagine a .tcl page that looks like:

In other words, our HTML form will send the contents of the date
widget to date-2, a .tcl page that will display its results in an
.adp page. date-2.tcl could tell ad_page_contract that the incoming
datewidget parameter will contain a simple array. But, we
additionally can declare datewidget to be a parameter of type
date, which automatically gives us four array
elements: