www exists only for
documentation.ad_template_sample_users that some of the
demonstrations use.The overall goal of the templating system is to provide the @@ -88,7 +91,9 @@ master template.
Karl Goldstein designed the templating system. First it was + +
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
@@ -104,11 +109,14 @@
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 +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.
+.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
@@ -124,9 +132,11 @@
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 +now.
+Other attributes are affected as follows. In parentheses the estimated priorities are listed, not the degree to which -the attributes are being achieved:
Details are in the developer +
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:
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.
Currently ad_page_contract does not allow
+specifying the latter two.
<include> and
-<master> tags. In these cases, Tcl and/or ADP
+requested with the <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 +
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.
++what's up and down (as in upvar), the stack grows down. +
Level Procedure Arguments @@ -204,45 +226,58 @@ - #5 template::code::tcl::/web/service/www/page Levels #1 to #3 exposed here are request processor internals. In +
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
+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,
+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, +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 +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, +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
+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]
@@ -251,13 +286,18 @@
; anything other than "never" or "always" means normal operation
RefreshCache=as necessary
-Passing datasources by reference is new. The acs-templating + +
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>,
+latter is phased out.
We intend to add a <which>,
<switch>, or <case> tag, to
complement sequential nested
-<if>/<else> constructs.
<if>/<else> constructs.
+| Document Revision # | Action Taken, Notes | When? | By Whom? |
|---|---|---|---|
| 0.2 | Adapted to acs-templating as distributed with ACS/Tcl 4.01 | 22 Nov 2000 | Christian Brechbühler |