Programmer / Developer Guide

Templating System : Developer Guide

Mini How To

Start a Tcl page as usual with ad_page_contract . Be sure to pass a -properties block; this signals the use of templating. The Tcl page should fill the data sources you promised in the contract, and not write to the connection. At the end of your Tcl page, call ad_return_template . The template system will look for an adp page with the filename stub you indicate (defaulting to the same stub as the Tcl page), process that, and deliver it to the client. The adp page can use the datasources defined in the Tcl page.

Guide

1. User Guide
   • Overview
   • Establishing data sources
     • Implementing data sources
     • Documenting data sources
   • Creating templates
     • Writing dynamic templates
     • Building reusable layout components
     • Using master templates
     • Composite pages
     • Presenting data in multiple styles and formats
     • Mixing Tcl and HTML
   • Managing forms
     • Creating and populating forms
     • Customizing form templates
     • Validating and processing form submissions
     • Integrating forms into a wizard
     • Implementing a search-and-select form
     • Implementing custom widgets
     • Implementing custom data types
   • Handling errors
     • See the "contract", "error", and "state" demos.
2. Object and API Reference
   • Database Query
   • Mutirow Data Source
   • Request
   • Form
   • Form Element
   • Form Widgets
3. Template Markup Tag Reference
4. Appendices
   • Appendix A: Sample templates
   • Appendix B: Parsing templates in memory

API

After the script for a page is executed, acs-templating processes the template, interpolating any data sources and executing the special tags. The resulting HTML page is written to the connection (i.e., returned to the user).

ad_return_template

Normally, does nothing at all. With the -string option you get the resulting HTML page returned as a string.

The optional template argument is a path to a page (tcl/adp file pair). Note that you don't supply the ".tcl" or ".adp" extension. It is resolved by help of template::util::url_to_file (with the current file stub as reference path) and passed to template::set_file, to change the name of the page being served currently. If it starts with a "/", it is taken to be a path relative to the server root; otherwise it is a filename relative to the directory of the Tcl script.

ad_page_contract

Normally, complaints about incorrect parameters are written directly to the connection, and the script is aborted. With the option -return_errors you can name a variable into which to put any error messages as a list, and ad_page_contract will return in any case. You can then present the errors to the user in a templated page, consistent with the look and feel of the rest of your service. If there's no complaint, ad_page_contract won't touch the variable; typically it will stay undefined.

---

Christian Brechbühler

Last modified: $‌Id: developer-guide.html,v 1.5.2.1 2023/06/06 09:30:30 gustafn Exp $