Overview

Templating System : Developer Guide : User Guide

This document provides a brief introduction to the design of the templating system and the process of building dynamic pages with the templating system.

Introduction

The templating system solves a clear business need: providing a system for efficient collaboration between designers and developers on building a web site. Writing a dynamic web page requires writing application logic that retrieves data from a database and HTML markup that presents this data in a readable form for the user. In practice on production sites, this requires collaboration between designers sensitive to issues of usability and the user experience and developers who are sensitive to programming and performance requirements. Without a templating system, a single script containing the application logic and presentation markup is often authored by both a designer and a developer simultaneously. This is inefficient, error-prone, and difficult to maintain, as multiple people with different purposes in mind must change the same file. To solve this problem, the ACS Templating System, separates the responsibilities of writing the page into separate application logic and presentation layers.

How the Templating System Works

This separation is achieved through utilization of the Model-View-Controller (MVC) pattern. The MVC pattern is a classic design pattern that identifies clear roles for components in GUI application with persistent data originally developed for SmallTalk-80 by Steve Burbeck. The model represents the object, its data, and methods for updating the data. The view provides a user a UI to see and manipulate the data in the model. The controller provides the system necessary to connect the model and the view to the user's requests. This diagram summarizes how the process flow of the templating system using the MVC framework. The filename dynamic-page is simply an example.

The model in the templating system is the representation in the database of the ACS Objects and their associated PL/SQL package methods. The view is the ADP template that formats the datasources retrieved through the controller into a presentation for a user. The controller is the combination of the Request Processor and the application logic pages implemented as .tcl scripts that prepare data sources for the templating system.

This framework permits a clear separation between the logic that retrieves data from the database and the markup that prepares the data for display. The designer can focus on presentation and usability issues and need only write HTML markup. The developer can focus on the programming necessary to retrieve the data for the designer and does not need to write HTML markup. These tasks are separated into separate files so that the two tasks do not interfere with each other.

The design of the templating system makes it easier to include reusable presentation components as included templates and master templates, as explained in "Composite Page". Moreover, the ACS Core pages are templated which enables users of the ACS who want to customize their look and feel to update a site-wide master or the individual templates without touching the application logic. If a bug is fixed in the application logic, the application logic script can be replaced without affecting the template.

The rest of this document explains the steps necessary to write a templated page.

Choose the data you wish to present

The first step in building a dynamic page is to decide, at least to a first approximation, on the data you wish to present to the user. For example, a site that allows users to manage their car maintenance records might want to present the following data on the user's home page:

Note that our definition of data encompasses everything that is unique to a particular user's experience. It does not include text or other layout features that will appear the same for all users.

Each of the items in the above list constitutes a data source which the system merges with a template to produce the finished page. The publisher typically describes the data to present on each page as part of the site specification.

Implement the Data Sources

Once the publishing team has described the data to present on a page, the developer writes a Tcl script to implement the data sources. The Tcl script should be located under the page root at the URL of the finished page. For example, a dynamic page that will be located at http://yoursite.com/cars.acs requires a Tcl script located on the server at /web/yoursite/www/cars.tcl (or wherever your pages happen to be located).

In addition to setting data sources, the Tcl script may perform any other required tasks, such as checking permissions, performing database transactions or sending email. It may also redirect to another URL if necessary. The Tcl script may optionally use logic to change which page is being delivered, specified by ad_return_template <filename>. If no filename is supplied, ad_return_template does nothing. If the page as defined after the last call to ad_return_template differs from what it was at the beginning of the page, its datasource preparation script is run in the same scope, in fact accumulating datasources. By default the templating system looks for a file with the same name as the Tcl script, but for the template with the extension .adp.

Document the Data Sources

The developer should include comments in the Tcl code documenting each data source. A templating system specifies recognizes special documentation directives that allow the comments to be extracted from the code and accessed by the designer or publisher for reference.

Write the Template

The final step is to write a template specifying the layout of the page. Template files must have the adp extension. By default the system looks for the template at the same location as the associated Tcl script, such as /web/yoursite/www/cars.adp.

The layout is mostly HTML, with a small number of additional custom tags to control the presentation of dynamic data on the page. In most cases, the initial draft of the template will be written by the developer in the course of testing the Tcl script. The designer may then enhance the layout as required.

docs@openacs.org