<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Using Templates in OpenACS 5.0.0d</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter�11.�Development Reference"><link rel="previous" href="db-api.html" title="The OpenACS Database Access API"><link rel="next" href="permissions.html" title="Groups, Context, Permissions"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><th width="60%" align="center">Chapter�11.�Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="templates"></a>Using Templates in OpenACS 5.0.0d</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="templates-overview"></a>Overview</h3></div></div><p>
The OpenACS 5.0.0d Template System (ATS) is designed to allow developers to
cleanly separate <span class="emphasis"><em>application logic</em></span> from <span class="emphasis"><em>display
logic</em></span>. The intent is to have all of the logic related to
manipulating the database and other application state data in one
place, and all the logic related to displaying the state of the
application in another place. This gives developer's quicker
customization and easier upgrades, and also allows developers and
graphic designers to work more independently.
</p><p>
In ATS, you write two files for every user-visible page in the
system. One is a plain <tt>.tcl</tt> file and the other is a
special <tt>.adp</tt> file. The <tt>.tcl</tt> file runs a
script that sets up a set of name/value bindings that we call <span class="emphasis"><em>data
sources</em></span>. These <a href="/doc/acs-templating/guide/data.html" target="_top">data sources</a> are generally the results of Tcl and/or database queries
or some combination thereof. The template system automatically makes
them available to the <tt>.adp</tt> file, or the display part of
the template, which is written in a combination of HTML, special
template related tags, and data source substitutions.
</p><p>
In the overall context of our example OpenACS Notes application, this
document will show you how to set up a simple templated page that
displays a form to the user for entering new notes into the system. In
later sections of the DG, we'll discuss how to develop the pages that
actually add notes to the database, how to provide a separate instance
of the Notes application to every user and how to design appropriate
access control policies for the system.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="templates-entering-notes"></a>Entering Notes</h3></div></div><p>
In order for the Notes application to be useful, we have to allow
users to enter data into the database. Typically, this takes two
pages: one that displays a form for data entry, and another page that
runs the code to update the database and tells the user whether the
operation failed. In this document, we will use the template system to
build the first of these pages. This isn't a very interesting use of
the system since we won't be displaying much data, but we'll cover
more on that end later.
</p><p>
The <tt>.tcl</tt> file for the form entry template is pretty
simple. Here, the only thing we need from the database is a new ID for
the note object to be inserted. Open up a file called
<tt>note-add.tcl</tt> in the <tt>ROOT/packages/notes/www</tt>
directory, and put the following code in it:
</p><pre class="programlisting">
ad_page_contract {
Form to add a note in OpenACS Notes.
@author Jane Coder
@creation-date 11 Oct 2000
} -properties {
note_id:onevalue
submit_label:onevalue
target:onevalue
page_title:onevalue
} -query {
}
set user_id [ad_verify_and_get_user_id]
db_1row user_name {
select first_names || ' ' || last_name as user_name
from users
where forum_id = :user_id
}
set page_title "Add a note for $user_name"
set submit_label "Add"
set target "note-add-2"
set note_id [db_nextval acs_object_id_seq]
ad_return_template "note-add"
</pre><p>
Some things to note about this code:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The procedure <a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a> is
always the first thing a <tt>.tcl</tt> file calls, if it's under
the www/ directory (i.e. not a Tcl library file). It does validation
of input values from the HTTP request (i.e. form variables) and in
this case, the <tt>-properties</tt> clause is used to set up the
data sources that we will ship over to the <tt>.adp</tt> part of
the page. In this case, we only use the simplest possible kind of data
source, called a <tt>onevalue</tt>, which hold just a single
string value. Later on, we'll see how to use more powerful kinds of
data sources for representing multiple rows from an SQL query. You
also include overall documentation for the page in the contract, and
OpenACS has automatic tools that extract this documentation and make it
browsable.
</p></li><li><p>
After being declared in the <tt>ad_page_contract</tt>, each
property is just a simple Tcl variable. The template system passes the
final value of the variable to the <tt>.adp</tt> template when the
<tt>.tcl</tt> file is processed.
</p></li><li><p>
The call <tt>ad_return_template</tt> tells the template system
what <tt>.adp</tt> template page to fetch to display the
properties that have been processed. By default, the template system
will look for a file by the same name as the <tt>.tcl</tt> file
that just ran, but with an <tt>.adp</tt> extension.
</p></li></ul></div><p>
Next we write the corresponding <tt>.adp</tt> page. This page
outputs HTML for the form, and also contains placeholders whose values
are substituted in from the properties set up by the <tt>.tcl</tt>
file. Create a file called <tt>note-add.adp</tt> in your editor,
and insert this text:
</p><pre class="programlisting">
<master src="master">
<property name="title">@page_title@</property>
<property name="context_bar">@context_bar@</property>
<form action=@target@>
<p>Title:
<input type="text" name="title" value="">
</p>
<p>Body:
<input type="text" name="title" value="">
</p>
<p>
<center>
<input type=submit value="@submit_label@">
</center>
</p>
</form>
</pre><p>
The main point to note here is: when you want to substitute a value
into a page, you put the name of the data source between two "@"
characters. Another point to note is the use of a master template:
Master templates allow you do centralize display code that is used
throughout an application in a single file. In this case, we intend to
have a master template that does the standard page headers and footers
for us - create the <tt>master.adp</tt> file, which looks like
this:
</p><pre class="programlisting">
<%= [ad_header $title] %>
<h2>@title@</h2>
<%= [eval ad_context_bar $context_bar] %>
<hr>
<slave>
<br clear="all">
<%= [ad_footer] %>
</pre><p>
The main subtlety in this code is the inline Tcl code for running
procs to build the header, footer, context bar, etc. Also, note the
property substitutions that happen here, the values of which are set
up in the <tt><property></tt> tags in the slave page.
</p><p>
After putting all these files into
<tt>ROOT/packages/notes/www</tt>, you should be able to go to
<tt>/notes/</tt> URL for your server and see the input form.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="templates-summary"></a>Summary</h3></div></div><p>
Templates separate application logic from display logic by requiring
the developer to write pages in two stages, one file for database
queries and application logic, and another for display. In OpenACS 5.0.0d, the
logic part of the page is just a <tt>.tcl</tt> that sets up
<span class="emphasis"><em>data sources</em></span> that are used by the display part of the page. The
display part of the page is an <tt>.adp</tt> file with some
special tags and notations for dealing with display logic and
inserting properties into the text of the page. Later on we'll get
into templates more deeply, and show how to use database queries as
data sources.
</p><div class="cvstag">($Id: templates.html,v 1.12 2003/08/20 16:20:17 joela Exp $)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr><tr><td width="40%" align="left">The OpenACS Database Access API </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Groups, Context, Permissions</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/templates.html#comments">View comments on this page at openacs.org</a></center></body></html>