Index: openacs-4/packages/acs-templating/www/doc/design.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/design.adp,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-templating/www/doc/design.adp 27 Oct 2014 16:40:13 -0000 1.2
+++ openacs-4/packages/acs-templating/www/doc/design.adp 7 Aug 2017 23:48:02 -0000 1.3
@@ -1,73 +1,77 @@
- 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
+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.The Template System -- Design Document
-by Christian Brechbühler Templating System :
+
+by Christian Brechbühler Templating System
+ :
Design
-I. Essentials
+
I. Essentials
+
www
exists only for
documentation.ad_proc
from acs-kernel
,
this package uses proc
.ad_template_sample_users
that some of the
demonstrations use.II. Introduction
+
+II. Introduction
+
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.action=
target
+of a form. They typically call ad_returnredirect
after
+completing their job.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
+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 + +
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.
+.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 +133,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:
tcl
extensions.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.
.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
+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
+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 @@ -202,47 +226,60 @@ (6) template::adp_prepare - -#5 template::code::tcl::/web/service/www/page +#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
-uplevel
ing.
To improve performance, adp pages are compiled into a tcl proc,
+uplevel
ing.
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 +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 +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, +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
+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 +288,19 @@ ; 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>
,
+
+
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.
<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 |