At the time when we came to realize how serious the quoting +
At the time when we came to realize how serious the quoting deficiencies of ACS 4.0 were, we were about two weeks away from the release of a project for the German Bank. There was simply no time to hunt all the places where a variable needs to be quoted and -implement one of the above quoting tricks.
While examining the ADPs, we noticed that most substituted -variable fall into one of three categories:
While examining the ADPs, we noticed that most substituted +variable fall into one of three categories:
+ +Those that need to be quoted -- names and descriptions of -objects, and in general stuff that ultimately comes from the -user.
Those for which it doesn't make a difference whether they are -quoted or not -- e.g. all the database IDs.
Those that must not be quoted -- e.g. exported form vars stored -to a variable.
Finally we also remembered the fact that almost none of the +objects, and in general stuff that ultimately comes from the user.
Those for which it doesn't make a difference whether they are +quoted or not -- e.g. all the database IDs.
Those that must not be quoted -- e.g. exported form vars stored +to a variable.
Finally we also remembered the fact that almost none of the variables are quoted in the current source base.
Our reasoning went further: if it is a fact that most variables +
Our reasoning went further: if it is a fact that most variables are not quoted, and if the majority of variables either require quoting or are not harmed by it, then we are in a much better position if we make the templating system quote all variables by default! That way @@ -158,7 +169,9 @@ need to be marked as noquote to function correctly. But even those should not be a problem, because HTML code that ends up quoted in the page is immediately visible, and all you need to do to fix it -is add the marker.
We decided to test whether the idea will work by attempting to +is add the marker.
+ +We decided to test whether the idea will work by attempting to convert our system to work that way. I spent several minutes making the change to the templating system. Then we went through all the ADPs and replaced the instances of \@foo\@ where foo contained HTML Index: openacs-4/packages/acs-templating/www/doc/demo/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/demo/index.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-templating/www/doc/demo/index.adp 27 Oct 2014 16:40:19 -0000 1.2 +++ openacs-4/packages/acs-templating/www/doc/demo/index.adp 23 Jun 2015 10:52:55 -0000 1.3 @@ -78,7 +78,7 @@
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.
To speed development and ensure consistency of design, template +dictionary that lists all available variables.
+ + +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 @@ -28,15 +31,21 @@ 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.
Template authors need a simple mechanism for declaring +liking.
(graphic)
+See include.
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 @@ -52,6 +61,10 @@ a table.
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.
Variables are used in templates as placeholders for dynamic -data.
Simple variables are referenced by surrounding the variable name -with "commercial at" (\@) signs:
-<!-- simple variables --> + ++ +Summary
+Variables are used in templates as placeholders for dynamic data.
+ +Usage
+Simple variables are referenced by surrounding the variable name +with "commercial at" (\@) signs:
+<!-- simple variables --> <b><i>\@first_name\@ \@last_name\@</b></i> -When processing this template, the server will look for +
When processing this template, the server will look for variables named first_name and last_name and -substitute their values in the output:
-<b><i>Fred Finkel</b></i> -
The columns of a row variable are referenced by separating the -data source name and column with a period:
-<!-- onerow or multirow data sources --> +substitute their values in the output: +<b><i>Fred Finkel</b></i> ++ +The columns of a row variable are referenced by separating the +data source name and column with a period:
+<!-- onerow or multirow data sources --> <b><i>\@user.first_name\@ \@user.last_name\@</b></i> -Note(s)
An attempt to reference a variable that does not exist will -cause an error message to appear in the browser.
The variables between at-signs are per-default quoted and internationalized. +While quoting is necessary to protect against e.g. cross side scripting by escaping +less and greater signs, ampersands and quotes, internationalization substitutes +message keys in texts.
+When either quoting or substitutions are not desired, one can specify modifiers in +the variable specifications, as shown in the following examples:
+
| Quoting and internationalization: | <b>\@foo\@</b> |
| Quoting and no internationalization: | <b>\@foo;noi18n\@</b> |
| No quoting and internationalization: | <b>\@foo;noquote\@</b> |
| No quoting and no internationalization: | <b>\@foo;literal\@</b> |
An attempt to reference a variable that does not exist will +cause an error message to appear in the browser.