<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
  <head>
    <title>Template System Guide</title>
    <link href="api/stylesheet.css" rel="stylesheet">
  </head>

  <body>
    <h2>Programmer / Developer Guide</h2>
    
    <a href="">Templating System</a> : Developer Guide
    <hr>

    <h3>Mini How To</h3>

    Start a Tcl page as usual with <code>ad_page_contract</code>.  Be
    sure to pass a <code>-properties</code> 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 <code>ad_return_template</code>.  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.
    
    <h3>Guide</h3>
    <ol>
      <li>User Guide</li>
    <ul>
      <li><a href="guide/index.html">Overview</a>
      <li>Establishing data sources
	<ul>
	  <li><a href="guide/data.html">Implementing data sources</a>
	  <li><a href="guide/document.html">Documenting data sources</a>
	</ul>
      <li>Creating templates
        <ul>
          <li><a href="guide/templates.html">Writing dynamic templates</a>
          <li><a href="guide/components.html">Building reusable layout
                                              components</a>
          <li><a href="guide/master.html">Using master templates</a>
	  <li><a href="guide/composite.html">Composite pages</a></li>
          <li><a href="guide/skins.html">Presenting data in multiple 
                                         styles and formats</a>
          <li><a href="guide/tcl.html">Mixing Tcl and HTML</a>
        </ul>
      <li>Managing forms
        <ul>
          <li><a href="guide/forms.html">Creating and populating forms</a>
          <li><a href="guide/form-templates.html">Customizing form 
                                                  templates</a>
          <li><a href="guide/form-process.html">Validating and processing 
                                                form submissions</a>
          <li><a href="guide/wizards.html">Integrating forms 
                                                into a wizard</a>
          <li><a href="guide/search.html">Implementing a search-and-select
                                          form</a>
          <li><a href="guide/form-widgets.html">Implementing custom 
                                               widgets</a>
          <li><a href="guide/form-datatypes.html">Implementing custom 
                                               data types</a>
        </ul>
      </li>
      <li>Handling errors
	<ul>
	  <li>
	    See the "contract", "error", and "state" <a href="demo/">demos</a>.
	  </li>
	</ul>
      </li>
    </ul>
    <li>Object and API Reference
      <ul>
        <li><a href="api/database.html">Database Query</a>
        <li><a href="api/multirow.html">Mutirow Data Source</a>
        <li><a href="api/request.html">Request</a>
        <li><a href="api/form.html">Form</a>
        <li><a href="api/element.html">Form Element</a>
        <li><a href="widgets">Form Widgets</a>
      </ul>
    <li><a href="tagref">Template Markup Tag Reference</a>
    <li>Appendices
      <ul>
      <li><a href="demo/">Appendix A: 
         Sample templates</a>
      <li><a href="appendices/memory.html">Appendix B: 
         Parsing templates in memory</a>
      </ul>
  </ol>

    <h3>API</h3>

    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).

    <h5><code><a href="/api-doc/proc-view?proc=ad%5freturn%5ftemplate">ad_return_template</a></code></h5>
    
    Normally, does nothing at all.  With the
    <code>-string</code> option you get the resulting HTML page
    returned as a string.

    <p>
      The optional <code>template</code> 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
      <code>template::util::url_to_file</code> (with the current file
      stub as reference path) and passed to
      <code>template::set_file</code>, 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.
    </p>

    <h5><code><a href="/api-doc/proc-view?proc=ad_page_contract">ad_page_contract</a></code></h5>
    
    Normally, complaints about incorrect parameters are written
    directly to the connection, and the script is aborted.  With the
    option <code>-return_errors</code> you can name a variable into
    which to put any error messages as a list, and
    <code>ad_page_contract</code> 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, <code>ad_page_contract</code> won't touch
    the variable; typically it will stay undefined.

    <hr>
    <address>
      <a href="mailto:christian@arsdigita.com">Christian Brechb&uuml;hler</a>
    </address>
<!-- Created: Mon Aug 14 11:53:07 EDT 2000 -->
Last modified:
    $Id: developer-guide.html,v 1.7 2024/09/11 06:15:48 gustafn Exp $
  </body>
</html>