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:

ad_page_contract {
    Comments and CVS information go here.
} {
    users:onelist
}

set users [db_list get_all_users {
    SELECT PE.first_names || ' ' ||
           PE.last_name as users
      FROM Parties PA, Persons PE
     WHERE PA.party_id = PE.person_id
  ORDER BY PE.last_name, PE.first_Names }]
 ad_return_template

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:

ad_page_contract {
} {
} -properties {
    users:multirow
}
db_multirow users get_info "
    SELECT PE.first_names || ' ' ||
           PE.last_name as name,
           PA.email FROM Parties PA, Persons PE
     WHERE PA.party_id = PE.person_id
  ORDER BY PE.last_name, PE.first_names"
ad_return_template

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:

<master>
  <ul>
  <multiple name="users">
    <li>
    <a href="mailto:@users.email@"
    @users.name@</a>
   </multiple>
   </ul>
</master>

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.

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:

ad_page_contract {
} {
    foo
} -properties {
    foo2:onevalue
}
set foo2 "$foo$foo"
ad_return_template

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:

ad_page_contract {
} {
    {foo "blah"}
} -properties {
    foo2:onevalue
}
set foo2 "$foo$foo"
ad_return_template

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:

ad_page_contract {
} {
} -properties {
    datewidget:onevalue
}
set datewidget [ad_dateentrywidget datewidget]
ad_return_template

The accompanying .adp page, which will display this date widget, then looks like:

<master>
    <form method="POST" action="date-2">
    @datewidget@
    <input type="submit" value="Send the
date">
    </form>
</master>

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:

ad_page_contract {
} {
  datewidget:array,date
} -properties {
  date_month:onevalue
  date_day:onevalue
  date_year:onevalue
  date_full:onevalue
}
  set date_month $datewidget(month)
  set date_day $datewidget(day)
  set date_year $datewidget(year)
  set date_full $datewidget(date)
  ad_return_template

Our .adp page, date-2, can now display the date information in a variety of formats:

<master>
    <p>Month: @date_month@</p>
    <p>Day: @date_day@</p>
    <p>Year: @date_year@</p>
    <p>Full text: @date_full@</p>
</master>

Note that the full version of the date widget is perfectly acceptable for SQL queries. This comes in handy when entering dates or when using them in comparison queries.