www exists only for
	    documentation. 
ad_proc from acs-kernel, this
	    package uses proc.
      ad_template_sample_users that some of the
	      demonstrations use.
The overall goal of the templating system is to provide the publishing team with a set of tools for simplifying the development and maintenance of the user interface. In particular:
A common solution. Programmers and designers should only have to learn a single system that serves as a UI substrate for all the functionally specific modules used on a site. The system should not make any assumptions about how pages should look or function. Designers should be able to change the default presentation of any module using a single metholodogy with minimal exposure to code.
Separation of code (Tcl, Java and SQL) and layout (HTML). Programmers should be able to specify the data sources and other properties of the template independently of the HTML template used to present the data. HTML authors should be to able to write templates that reference the data sources and properties without further intervention from the programmer to produce a finished page.
Separation of page components. There should be provisions so that pages can be broken into discrete components to simplify maintenance of the HTML code and allow for reuse in different contexts. Examples of common page components include a navigation bar, a search box, or a section of a report or story. Another common example is a portal page that allows the user to choose from a palette of features to display.
Global control over presentation. There should be a way to define one or more standard master templates used by most pages on a site, so that changes to the overall look and feel of a site can be made in one place.
Dynamic selection of presentation style. Given that the same data may be presented in many different ways, there should be a general mechanism for selecting a specific presentation (including file format, layout, character set and language) for each page request, depending on characteristics such as user preference, location, browser type and/or device.
Usability. Programmers should be able to develop template specifications using their standard tools for writing and maintaining code on the server. HTML authors should be able to access information about template specifications and work on templates remotely without needing shell access to the server.
What this package is not intended to allow users to accomplish.
action=
	    target of a form.  They typically call
	    ad_returnredirect after completing their job.
	  User interface. Any application that delivers visible pages to a user. Any page that returns content (HTML or other) in response to an HTTP[S] request.
How the package meets its requirements.
ad_page_contract (from the acs
	    kernel) should be used to specify what makes the dynamic
	    part of the page.  There's also an API for creating forms
	    and for creating and manipulating multirow data sources.
	  <master> tag specifies a master
	    template.  Its src attribute defaults to the
	    site-wide master template.
	
      Karl Goldstein designed the templating system.  First it was
      called "Karl's Templates" or "The New Templating System" to
      distinguish it from the obsolescent templates or "Styles" by
      Philip Greenspun.  An extended and improved version was named
      "Dynamic Publishing System".  It wasn't part of the ACS yet, but 
      client projects like iluvCAMP used it successfully.  Newcomers
      were consistently puzzled by the .data files, which
      specified the datasources in an apparently unfamiliar XML
      syntax.  (The .form files specified elements in an
      HTML form similarly.)  To mitigate this initial shock, Karl
      redesigned templates to let the programmer specify datasources
      and forms in a .tcl script.  The system is present
      as packages templates and form-manager 
      in ACS 3.4.
      Both these packages are now merged and appear as
      acs-templating starting in ACS 4.0.  The
      architecture of the package was changed several times to meet
      the emerging coding/style constraints of ACS 4.0.
    
As indicated above, the primary attribute that the page tries to achieve is the separation of code and layout. The primary sacrifice is simplicity; in the typical case there will be two files (a .adp templage and a .tcl script) instead of a single .tcl page.
Management of data sources.
      Through the various past versions of the package, it evolved
      that data sources should be set as Tcl variables and arrays.
      Earlier they were kept as lists of ns_sets, which was
      significantly less efficient.  The datasources are not being
      copied around; they reside in a specific stack frame.  Using
      the uplevel Tcl command, we make sure that the data
      file (tcl part of a page) executes in the same stack frame as
      the compiled template (the adp part), so the latter can make use of the
      data sources prepared by the former.
              Thus, we decided for
      performance, simplicity, and ease of
	use at the cost of using the (standard Tcl) commands
      upvar and uplevel, which is
      considered confusing and error-prone by
      reviewers (of 4.0).  The use of these constructs has been
      reduced in 4.01, and the code is clearer now.
    
Other attributes are affected as follows. In parentheses the estimated priorities are listed, not the degree to which the attributes are being achieved:
sourced and parsed
	on every request.
      ad_page_contract for the specification of the
	expected parameters (called query) and the datasources it will
	supply (called properties).  The templating system is
	registered with the request processor as the handler for both
	adp and tcl extensions.
      Details are in the developer guide. Here we give an overview, and then the more obscure aspects of the current implementation.
The most important abstraction is the data source, of which there are several kinds:
      Currently ad_page_contract does not allow
      specifying the latter two.
    
.adp or .tcl file.  As both invoke
        the same handler, it doesn't matter that adp take precendence.
      .tcl file is present,
	its ad_page_contract in the
        -properties block indicates a set of data
	sources that will be made available to the template.
      template::set_file directly or through
        the wrapper ad_return_template.
      <include> and 
      <master> tags.  In these cases,
    Tcl and/or ADP parsing happens recursively.
    Below is a diagram of the typical call stack when processing a page without dependent pages. To conform to the Tcl notion of what's up and down (as in upvar), the stack grows down.
Level Procedure Arguments #1 rp_handler #2 rp_serve_abstract_file /web/service/www/page #3 rp_serve_concrete_file /web/service/www/page.adp #4 adp_parse_ad_conn_file #5 template::adp_parse /web/service/www/page {} (6) template::adp_prepare #5 template::code::tcl::/web/service/www/page 
      Levels #1 to #3 exposed here are request processor internals.
      In the case shown, datasources reside in level #5.  Due to the
      uplevel command, the frame of the sixth procedure
      is not accessible in the call stack at this moment, and the
      seventh runs in
      stack frame #5.  If the <include> or
      <master> tags are used,
      adp_parse will be invoked recursively.  Datasources
      always reside in the stack frame of an instance of
      adp_parse.
    
      To keep track of data sources of several page components, the
      templating system maintains a stack of their stack levels in the 
      variable template::parse_level.  In our case, it
      just contains 5.  But if this page included another page or
      designated is as its master,
      the level of the next adp_parse would be pushed to
      the list, and popped when that proc returned.  This next level
      will appear as #6, due to the repeated upleveling.
    
To improve performance, adp pages are compiled into a tcl proc, and thus cached for future use. Tcl pages are also cached in a proc; this saves the trouble of reading and parsing the file the next time. The template system remembers the modification times of the adp and tcl sources, and re-processes any requested file if the cached version is no longer current. Consequently, this cacheing is transparent in normal use.
To emphasize that "normal" use essentially always applies, here's a scenario for abnormal use: Save version n of a file at 11:36:05.1; request a page that uses it at 11:36:05.3; modify and save version n+1 of the file at 11:36:05.9. If you work that fast (!), the new version will have the same modification time -- kept with 1 second resolution in Unix --, and will not be refreshed.
      For timing measurements and performance tuning, you can set the
      parameter RefreshCache in section
      template to never or
      always.  The former suppresses checking mtime and
      may improve performance on a production server, where the
      content pages don't change.  The latter is only inteded for testing.
    
This packages doesn't need a data model.
      It comes with its own database interfaces, one for using ns_ora,
      the Oracle driver from ArsDigita, and one for ns_db, the builtin
      database interface of the AOL server.  If you are programming
      under the ACS, you should use neither of these, but rather the
      db_* interface, in particular db_multirow.
    
This packages doesn't have a user interface. It is the substrate of all user interfaces, be it user or admin pages.
      [ns/server/yourservername/acs/template]
      ; the site-wide Master template
      DefaultMaster=/www/default-master
      ; anything other than "never" or "always" means normal operation
      RefreshCache=as necessary
    
    
      Passing datasources by reference is new.  The acs-templating
      syntax &formal="actual" is different from the
      independent ATS, which used formal="@actual.*@".
      The latter is phased out.
    
      We intend to add a <which>,
      <switch>, or  <case> tag,
      to complement sequential nested
      <if>/<else> constructs.
    
| Document Revision # | Action Taken, Notes | When? | By Whom? | 
|---|---|---|---|
| 0.1 | Brought into the form suggested by Finkler, McLoghlin and Wu | 18 Jul 2000 | Christian Brechbühler | 
| 0.2 | Adapted to acs-templating as distributed with ACS/Tcl 4.01 | 22 Nov 2000 | Christian Brechbühler |