Index: openacs-4/packages/acs-templating/www/doc/requirements.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/requirements.adp,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-templating/www/doc/requirements.adp 27 Oct 2014 16:40:14 -0000 1.2
+++ openacs-4/packages/acs-templating/www/doc/requirements.adp 7 Aug 2017 23:48:02 -0000 1.3
@@ -1,19 +1,27 @@
- The template system is designed to be used by two classes of
+
+
+ The template system is designed to be used by two classes of
users: programmers and designers. In bulding a web site,
programmers are generally responsible for defining and implementing
-the application logic of the site, while designers are more
-responsible for the presentation. Generally speaking, the
-application logic generates data for the presentation to display to
-the user. The template system must provide mechanisms that supports
-both of these tasks and allows the designer and programmer to work
-seperately, but for their work to be combined at runtime into
-something that the user sees as a single page. Thus, pages are naturally split into two parts. The logic
-part executes application logic and generates data, and the
-presentation part that specifies the layout of the page and
-so on. What is needed is:ACS Templating Requirements
-by Karl Goldstein,
+
+by Karl Goldstein
+,
Christian
-Brechbühler, Peter
-Su, and Yonatan FeldmanI. Introduction
+Brechbühler
+, Peter
+Su
+, and Yonatan Feldman
+
+I. Introduction
+
The following is a requirements document for the ACS Templating
-System version 0.5. It has also been called Karl's Templates, the
-Dynamic Publishing System (DPS), and Stencil. The official package
-name for the system is now acs-templating
.
-II. Vision Statement
+System version 0.5. It has also been called Karl's Templates,
+the Dynamic Publishing System (DPS), and Stencil. The official
+package name for the system is now
+acs-templating
+.
+II. Vision Statement
+
On websites of sufficient size, a consistent look and feel (the UI,
or user interface) for users is important, while for site
publishers and administrators, de-coupling the UI from programming
@@ -26,8 +34,10 @@
on a script or program that generates the dynamic content that
fills the blanks in the template. In addition, the templating
system provides a way to use a single layout specification for the
-majority - if not all - of a website's pages, so the overall layout
-of a site can be more easily administered. III. System Overview
+majority - if not all - of a website's pages, so the overall
+layout of a site can be more easily administered.
+III. System Overview
+
The templating system provides:
IV. Use-cases and User-scenarios
IV. Use-cases and User-scenarios
+
+the application logic of the site, while designers are
+more responsible for the presentation. Generally speaking,
+the application logic generates data for the presentation to
+display to the user. The template system must provide mechanisms
+that supports both of these tasks and allows the designer and
+programmer to work separately, but for their work to be combined at
+runtime into something that the user sees as a single page.
Thus, pages are naturally split into two parts. The logic +part executes application logic and generates data, and the +presentation part that specifies the layout of the page +and so on.
+What is needed is:
+Jane Programmer writes a page contract and a draft template, + +
Jane Programmer writes a page contract and a draft template, that uses the promised page properties. Joe Designer takes that template and makes it look nice, using his design skills and HTML literacy. Meanwhile Jane Programmer writes code to generate the page properties, typically by querying the database. When both are done, the page is ready for Jim User, who requests it using his web -browser.
+browser.
+Alternate scenario: Judy Designer is familiar with the template system. She starts directly from a defined page contract, -so Jane Programmer doesn't need to write the draft template.
Programmers and designers should only have to learn a single system that serves as a UI substrate for all the functionally @@ -83,46 +107,48 @@ should look or function.
10.0.5Publishers should be able to change the default presentation of any module using a single methodology with minimal exposure to code.
-10.5 Programmer's APIIt must be easy to use/integrate the templating system with any +10.5 Programmer's API
It must be easy to use/integrate the templating system with any application. This implies a stable, simple, and comprehensive API for programmers to use when writing or converting modules.
Programmers must be able to publish a page's data sources, so -that a graphic designer knows what data sources are available.
10.5.2 Page Contract ImplementationProgrammers must be able to generate and populate the page +Publishing
Programmers must be able to publish a page's data sources, +so that a graphic designer knows what data sources are +available.
10.5.2 Page Contract ImplementationProgrammers must be able to generate and populate the page properties they promise. This includes page properties of types: onevalue, onerow, multirow, onelist, and multilist.
-It must be simple for graphic designers to create and maintain +10.10 Graphic Designer's API
It must be simple for graphic designers to create and maintain templates that include dynamic data, and other templates. This requires a stable, simple, and comprehensive API for graphic designers to use when creating the layout pages for a site.
Much like the "mail merge" feature of a word processor, template -authors must use special tags to position each piece of dynamic -data within the layout. Each template is associated with a data -dictionary that lists all available variables.
10.10.2 Use of ComponentsTo speed development and ensure consistency of design, template -authors are encouraged to assemble pages from distinct component -templates that may be recycled in different contexts. One -typical practice is to build a "master" template for an entire -section of a site, with a common header, footer and sidebar layout. -For each page request, the "content" template is incorporated -dynamically into a specified area of the master template, usually a -table cell.
Another common practice is to build small reusable templates +Substitution
Much like the "mail merge" feature of a word +processor, template authors must use special tags to position each +piece of dynamic data within the layout. Each template is +associated with a data dictionary that lists all available +variables.
10.10.2 Use of ComponentsTo speed development and ensure consistency of design, template +authors are encouraged to assemble pages from distinct +component templates that may be recycled in different +contexts. One typical practice is to build a "master" +template for an entire section of a site, with a common header, +footer and sidebar layout. For each page request, the +"content" template is incorporated dynamically into a +specified area of the master template, usually a table cell.
Another common practice is to build small reusable templates that may be included in other templates as logical components. This -may be useful for common "widgets" such as search boxes or lists of -related links, as well as for building configurable portal pages -where users may assemble different types of content to their -liking.
10.10.3 Inter-Template CommunicationTemplate authors need a simple mechanism for declaring +may be useful for common "widgets" such as search boxes +or lists of related links, as well as for building configurable +portal pages where users may assemble different types of content to +their liking.
10.10.3 Inter-Template CommunicationTemplate authors need a simple mechanism for declaring properties within templates. The most common use of such properties is for configuring elements of an enclosing master template, such as the title, navigation links, and whether to include a search box.
10.10.4 Conditional InsertionDesigners often need to tailor the layout depending on the specific data being presented. For example, when presenting a list of library books that a user has checked out, the designer might want to highlight the overdue ones in red. For this, designers must -have the ability to write simple program logic (Note: We run the -risk of inventing our own language here, we must be -careful).
+have the ability to write simple program logic (Note: We run +the risk of inventing our own language here, we must be +careful).Dynamic pages often present lists of values or records, each of which typically represents the results of a database query. @@ -172,7 +198,10 @@ template specifications and work on templates remotely without needing shell access to the server.
The Templating System must be releasable as part of the ACS and as a separate product. When distributed as part of the ACS all @@ -185,7 +214,9 @@ page load speed by more than 10% versus a Tcl page with inline HTML.
Document Revision # | Action Taken, Notes | When? | By Whom? |
---|---|---|---|
0.3 | Edited, reviewed, pending freeze | 8/28/2000 | Kai Wu |