Index: openacs-4/packages/acs-templating/www/doc/designer-guide.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/designer-guide.adp,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-templating/www/doc/designer-guide.adp 27 Oct 2014 16:40:13 -0000 1.2
+++ openacs-4/packages/acs-templating/www/doc/designer-guide.adp 25 Aug 2015 18:02:09 -0000 1.2.2.1
@@ -2,67 +2,96 @@
Templates are the primary means for separating the work of
+ Templates are the primary means for separating the work of
developers and designers. A template is written by a designer and
consists largely of static HTML (or other markup). The template
author uses a small set of special markup tags to reference dynamic
data prepared by the developer.The tags allow authors to accomplish
-four basic tasks that are not possible with standard HTML:Designer Guide
Templating System : Designer Guide
-Overview
Designer Guide
+Templating System
+ : Designer Guide
+Overview
+
+four basic tasks that are not possible with standard HTML:
A reasonably skilled template author should be able to implement + +
A reasonably skilled template author should be able to implement a template without any assistance from the developer, other than -assuring that the proper dynamic data is accessible.
This section introduces the basic concepts underlying the use of -template tags in ACS 4.0.
Much like the mail merge feature of a word processor, template +assuring that the proper dynamic data is accessible.
+This section introduces the basic concepts underlying the use of +template tags in ACS 4.0.
+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 data sources.
To speed development and ensure consistency of design, template +dictionary that lists all available data sources.
+ +To 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.
(graphic)
Another common practice is to build small reusable templates +cell.
+(graphic)
+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.
(graphic)
See include and +liking.
+(graphic)
+See include and master. See also Building reusable layout components and -Using master templates.
Template authors need a simple mechanism for declaring +Using master templates.
+Template authors need a simple mechanism for declaring properties within the 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. The data dictionary specifies available -properties as well as the set of valid values when appropriate.
(graphic)
See property.
Designers often need to tailor the layout depending on the +properties as well as the set of valid values when appropriate.
+(graphic)
+See property.
+Designers 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.
See if..else.
Dynamic pages often present lists of values or records, each of +want to highlight the overdue ones in red.
+See if..else.
+Dynamic pages often present lists of values or records, each of which typically represents the results of a database query. Template authors must have a way to iterate over each value or record in such a list and format it appropriately. In the simplest scenario, the exact HTML is repeated with each iteration. However, template authors often need to vary the design depending on the -context. For example:
First and last items may be formatted differently from items in between.
Special breaks may be required when a particular value changes. For example, a query may return the name and office of all employees in a company, and the designer may wish to insert a subheading for each office.
Colors or patterns may alternate between items. For example, the designer may want to have alternate between white and gray bands in a table.
To accomodate these type of scenarios, the template parser sets +
To accomodate these type of scenarios, the template parser sets some additional variables that the designer can reference to vary -the layout from item to item.
Template tags are processed by the server each time a page is
requested. The end result of this processing is a standard HTML
page that is delivered to the user. Users do not see template tags
@@ -87,7 +116,9 @@
Specifically, if you must use the <% %>
tag, do
not call ns_puts
, because it will not work the same
way as in AOLserver's ADP pages.