| Prev | Chapter�11.�Development Reference | Next |
|---|
By Pete Su
+ +The OpenACS Template System (ATS) is designed to allow developers to cleanly separate application logic from display logic. The intent is to have all of the logic related to @@ -12,12 +13,12 @@ graphic designers to work more independently.
In ATS, you write two files for every user-visible page in the
-system. One is a plain .tcl file and the other is a
-special .adp file. The .tcl file runs a
+system. One is a plain .tcl file and the other is a
+special .adp file. The .tcl file runs a
script that sets up a set of name/value bindings that we call data
sources. These data sources are generally the results of Tcl and/or database queries
or some combination thereof. The template system automatically makes
-them available to the .adp file, or the display part of
+them available to the .adp file, or the display part of
the template, which is written in a combination of HTML, special
template related tags, and data source substitutions.
@@ -28,7 +29,7 @@ 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. -
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 @@ -38,10 +39,10 @@ the system since we won't be displaying much data, but we'll cover more on that end later.
-The .tcl file for the form entry template is pretty
+The .tcl 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
-note-add.tcl in the ROOT/packages/notes/www
+note-add.tcl in the ROOT/packages/notes/www
directory, and put the following code in it:
@@ -68,74 +69,74 @@
where forum_id = :user_id
}
-set page_title "Add a note for $user_name"
-set submit_label "Add"
-set target "note-add-2"
+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"
+ad_return_template "note-add"
Some things to note about this code:
The procedure ad_page_contract is
-always the first thing a .tcl file calls, if it's under
+always the first thing a .tcl 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 -properties clause is used to set up the
-data sources that we will ship over to the .adp part of
+this case, the -properties clause is used to set up the
+data sources that we will ship over to the .adp part of
the page. In this case, we only use the simplest possible kind of data
-source, called a onevalue, which hold just a single
+source, called a onevalue, 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.
-After being declared in the ad_page_contract, each
+After being declared in the ad_page_contract, each
property is just a simple Tcl variable. The template system passes the
-final value of the variable to the .adp template when the
-.tcl file is processed.
+final value of the variable to the .adp template when the
+.tcl file is processed.
-The call ad_return_template tells the template system
-what .adp template page to fetch to display the
+The call ad_return_template tells the template system
+what .adp 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 .tcl file
-that just ran, but with an .adp extension.
+will look for a file by the same name as the .tcl file
+that just ran, but with an .adp extension.
-Next we write the corresponding .adp page. This page
+Next we write the corresponding .adp page. This page
outputs HTML for the form, and also contains placeholders whose values
-are substituted in from the properties set up by the .tcl
-file. Create a file called note-add.adp in your editor,
+are substituted in from the properties set up by the .tcl
+file. Create a file called note-add.adp in your editor,
and insert this text:
-<master src="master"> -<property name="title">@page_title@</property> -<property name="context_bar">@context_bar@</property> +<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=""> +<input type="text" name="title" value=""> </p> <p>Body: -<input type="text" name="title" value=""> +<input type="text" name="title" value=""> </p> <p> <center> -<input type=submit value="@submit_label@"> +<input type=submit value="@submit_label@"> </center> </p> </form>
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 "@"
+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 master.adp file, which looks like
+for us - create the master.adp file, which looks like
this:
@@ -144,29 +145,29 @@ <%= [eval ad_context_bar $context_bar] %> <hr> <slave> -<br clear="all"> +<br clear="all"> <%= [ad_footer] %>
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 <property> tags in the slave page.
+up in the <property> tags in the slave page.
After putting all these files into
-ROOT/packages/notes/www, you should be able to go to
-/notes/ URL for your server and see the input form.
-
+ROOT/packages/notes/www, you should be able to go to +/notes/ URL for your server and see the input form. +
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, the
-logic part of the page is just a .tcl that sets up
+logic part of the page is just a .tcl that sets up
data sources that are used by the display part of the page. The
-display part of the page is an .adp file with some
+display part of the page is an .adp 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.
-