This document provides a brief introduction to the design of the templating system and the process of building dynamic pages with -the templating system.
This separation is achieved through utilization of the +
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 @@ -33,51 +37,64 @@ 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 +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 +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 +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.
The first step in building a dynamic page is to decide, at least +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.
+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 +
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 +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.
Once the publishing team has described the data to present on a +present on each page as part of the site specification.
+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 +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 @@ -89,17 +106,23 @@ 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.
The developer should include comments in the Tcl code +template with the extension .adp.
+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.
The final step is to write a +code and accessed by the designer or publisher for reference.
+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 +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 +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.
