A template in the OpenACS system consists of an ADP page (HTML augmented with additional tags) with an optional TCL script. The two have the same name, differentiated only by extension. In other words, the template foo consists of two files, foo.tcl and foo.adp.

Conceptually, the TCL file is executed and the output blended with the ADP file to form the page that's returned to the user's browser.

A major engineering standard for the OpenACS project is that Tcl code should not be included in ADP files, and HTML should not be included in TCL files. When you read .LRN-specific packages, you'll learn that the vendor did not always follow this guideline. It is bad practice, we are slowly cleaning up that code. Do not write such code yourself.

In addition to special tags (described later), there are two special constructs (with variants) that are of crucial importance:

• @tcl_var@ tcl_var is a simple Tcl variable that has been defined using the set command in the TCL script associated with this template. The value of tcl_var is substituted into the template code after being HTML-quoted (HTML tags are turned into plain text).

• @tcl_var;noquote@ Same as the above but HTML tags are not turned into plain text. You should make sure that the value has been stripped of potentially dangerous tags and checked for tags that have not been properly closed first (we have tools to do this).

• @tcl_array_var.index@ Same as the simple variable case, but refers to the Tcl array element $tcl_array_var(index). The noquote variant is supported for array references, too.

• #message_resource# The identifier refers to an acs_lang message key and is replaced in the templated with the localized message value.

As you read the code, you'll see that older packages which have not been internationalized have ADP files with literal strings written in English. Newer packages contain ADP files which are a bit more cryptic, consisting mostly of structural HTML tags, variable references, and message keys.