Index: openacs-4/packages/acs-service-contract/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/www/doc/index.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-service-contract/www/doc/index.adp 17 Sep 2014 19:06:32 -0000 1.1.2.1 @@ -0,0 +1,70 @@ + +{/doc/acs-service-contract {Service Contracts}} {ACS Service Contract Documentation} +ACS Service Contract Documentation + + + +

ACS Service Contract Documentation

Why

To facilitate greater code reuse, application integration, and +package extensibility within the OpenACS.

To do this acs-service-contract defines an api for the creation +of interfaces and discovery of interface implementations.

Background

Most component systems are based on the use of interfaces. +Interfaces allow components to create contracts which define their +functional level of reuse and customization. It also provides the +infrastructure for runtime discovery of which implemented +interfaces are available.

The ACS4 is based on a thin object system, that is primarily +relational but the acs_objects system allows a veneer of object +orientedness by providing globally unique object ids, object +metadata, and bundling of data and methods as an object. While this +permits a level of reuse on an object or package basis, it requires +hardcoding the unit of reuse.

ACS Service contract allows these objects and packages to also +define and register their implementation of interfaces, so the +level of reuse is defined at the contract level.

In addition ACS Service contract provides mean to dispatch +method calls on an interface implementation. The dispatch means is +only available through tcl.

Interface Discovery is available programmatically as well as via +documentation through ad_proc.

The Service Contract interface specification was inspired by +WDSL, the interface specfication for web services.

Hitchiker's Guide to Service Contract Definitions

Usage

Design the Contract

First Off design the interface for your contract, keeping in +mind that all implementations need to implement it and that +extension of the contract after deployment is often not practical. +In other words take the time to do a little future proofing and +thinking about possible uses that you weren't planning on.

Defining Operations

Next define the logical operations that will make up your +contract

Register the Contract

with acs contracts.

Implement the Contract

FAQ

Why Does an implementation reference an interface?

This might seem a little strange since a binding is the official +reference between an implementation and an interface. However it is +quite possible that an implementation for interface might exist +prior to the interface being defined, ie the interface defining +package is not installed. By retaining this information the +interface defining package can be installed and the implementations +already installed on the system can be bound to it.

Api Reference

[for oracle please syntax replace __ with .]

Creating Message Types

Creating Interfaces

creates a new contract to serve as a logical container for +operations. contract_desc is a text description of the +contract.

creates a new operation as part of a contract.

Creating Implementations

Discovery

Dispatching

Examples

Included in the service contract package are examples for oracle +and postgresql of a trivial contract.

Also the search contract functions as a non-trivial core +contract used by openacs4.

Further Reading

Abstract Factory Pattern - GOF

Component Systems - Clemens Syzperski

WSDL Spec

Credits

Most content was provided by Neophytos Demetriou. Most of the +errors were provided by Kapil Thangavelu.

+ Index: openacs-4/packages/acs-service-contract/www/doc/notes.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/www/doc/notes.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-service-contract/www/doc/notes.adp 17 Sep 2014 19:06:32 -0000 1.1.2.1 @@ -0,0 +1,24 @@ + +{/doc/acs-service-contract {Service Contracts}} {} + + + + +ACS Service Contract Overview by Neophytos Demetriou +(k2pts@yahoo.com) and Kapil Thangavelu (k_vertigo@yahoo.com) Goals +- To increase inter-application code reuse by designating +interfaces for interaction. - To increase flexibility by allowing +developers to reimplement an interface for their needs. - To +provide the framework for constructing web services by housing the +metadata needed to construct wsdl. - To be low impediment to +developers to create interfaces for their packages. - To reduce +fixed dependencies in packages. Definitions Interface - An abstract +set of operations supported by one or more endpoints. Operation - +An abstract description of an action supported by the service. +Binding - A concrete implementation for a particular interface. +Function - The implementation of an operation. Actors Registrar - +An entity that defines the specification of a contract and +registers it with the repository. Provider - Provides an +implementation of the contract. Dependant - Something that uses a +contract. + Index: openacs-4/packages/acs-subsite/www/doc/group-admin-pages-acceptance-test.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/group-admin-pages-acceptance-test.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-subsite/www/doc/group-admin-pages-acceptance-test.adp 17 Sep 2014 19:06:31 -0000 1.1.2.1 @@ -0,0 +1,205 @@ + +{/doc/acs-subsite {Subsite}} {Group Admin Pages - Acceptance test} +Group Admin Pages - Acceptance test + + + +

Group Admin Pages - Acceptance +test

+ACS subsite docs : Group Admin Pages - +Acceptance test

DEVELOPER DEFINED GROUP TYPES TEST

The first thing we have to test is developer defined group +types working in conjunction with the user defined ones.

Create the following object type in SQL*Plus.

begin
+ acs_object_type.create_type (
+   supertype => 'group',
+   object_type => 'developer_defined_test_type',
+   pretty_name => 'Developer defined test type',
+   pretty_plural => 'Developer defined test types',
+   table_name => 'developer_defined_test_types',
+   id_column => 'test_group_id',
+   package_name => 'developer_defined_test_type',
+   name_method => 'acs_group.name'
+ );
+end;
+/
+show errors;   
+
+
+create table developer_defined_test_types (
+       test_group_id   integer primary key references groups(group_id)
+);
+
+
+create or replace package developer_defined_test_type
+as
+
+  function new (
+         TEST_GROUP_ID   IN DEVELOPER_DEFINED_TEST_TYPES.TEST_GROUP_ID%TYPE DEFAULT NULL,
+         GROUP_NAME      IN GROUPS.GROUP_NAME%TYPE,
+         OBJECT_TYPE     IN ACS_OBJECTS.OBJECT_TYPE%TYPE DEFAULT 'developer_defined_test_type'
+  ) return DEVELOPER_DEFINED_TEST_TYPES.TEST_GROUP_ID%TYPE;
+
+  procedure delete (
+    TEST_GROUP_ID      in DEVELOPER_DEFINED_TEST_TYPES.TEST_GROUP_ID%TYPE
+  );
+
+end developer_defined_test_type;
+/
+show errors
+
+create or replace package body developer_defined_test_type
+as
+
+  function new (
+         TEST_GROUP_ID   IN DEVELOPER_DEFINED_TEST_TYPES.TEST_GROUP_ID%TYPE DEFAULT NULL,
+         GROUP_NAME      IN GROUPS.GROUP_NAME%TYPE,
+         OBJECT_TYPE     IN ACS_OBJECTS.OBJECT_TYPE%TYPE DEFAULT 'developer_defined_test_type'
+  ) return DEVELOPER_DEFINED_TEST_TYPES.TEST_GROUP_ID%TYPE
+  is
+    v_TEST_GROUP_ID DEVELOPER_DEFINED_TEST_TYPES.TEST_GROUP_ID%TYPE;
+  begin
+
+    v_TEST_GROUP_ID := acs_group.new (
+                     group_id         => new.TEST_GROUP_ID,
+                     GROUP_NAME       => new.GROUP_NAME,
+                     OBJECT_TYPE      => new.OBJECT_TYPE
+                   );
+
+    insert into DEVELOPER_DEFINED_TEST_TYPES
+    (TEST_GROUP_ID)
+    values
+    (v_TEST_GROUP_ID);
+
+    return v_TEST_GROUP_ID;
+
+  end new;
+
+  procedure delete (
+    TEST_GROUP_ID      in DEVELOPER_DEFINED_TEST_TYPES.TEST_GROUP_ID%TYPE
+  )
+  is
+  begin
+
+    acs_group.del( developer_defined_test_type.delete.TEST_GROUP_ID );
+
+  end delete;
+
+end developer_defined_test_type;
+/
+show errors
+
+
    +
  1. Go to /admin/group-types and select "Developer defined +test types"
  2. Add a permissible rel type of Membership +Relation
  3. Add a group named "Test group"
    4. +

GROUP TYPE PAGES BASIC FUNCTIONALITY

(Start at /admin)
    +
  1. Click on group types
  2. Click on Groups
  3. Click on "Group name" under "Attributes of this type of +group"
  4. Ensure that you see the properties of the attribute and +that you are offered no administrative links
  5. Make sure you cannot add attributes or do anything under +administration
  6. Make sure you see Composition and Membership Relation as +the default relationship types
  7. Add a new group called "Foobar" - Make sure Foobar +appears after adding the group
  8. Click on Foobar
  9. Click on nuke this group then click no. Ensure group is +not deleted
  10. Click on nuke this group then click yes. Group should no +longer show up
  11. Recreate the group Foobar
  12. Click on foobar, then change the name to +"ArsDigita"
  13. Change ArsDigita's join policy to closed
    14. +

DYNAMICALLY EXTENDING GROUPS

(Start at /admin/group-types/)
    +
  1. Click on "Define a new group type" and create a new group +type called "Project" with type "project". Ensure that all the +fields you see are required (try submitting without entering in +anything).
  2. Define another group type, child of group, named +"Test"
  3. Define another group type, 'subproject', child of +project. Ensure that the index page correctly displays the +hierarchy.
  4. Define a new group type with group type = group. See +error message saying type already exists.
  5. Go back to the index page +(/admin/group-types).
  6. +Click on the Test group type. Make sure that:
      +
    • there are no groups
    • Group name attribute is inherited from groups
    • you have a link to add an attribute
    • you see Composition and Membership Relation as the +default relationship types
    • You have a link to change the default join +policy
    • You have a link to delete the group type
      • +
    +
  7. Click on "Add a permissible relationship type." Ensure +that you are not given a select bar but are offered a link to +"create a new relationship type"
  8. Create a group of type test.
  9. Delete the test group type (first verify that the cancel +button works)
  10. Go to the "project" group type
  11. Add a required attribute called "Project type" of +datatype enumeration. Values are "Client" "Toolkit"
  12. Add an optional attribute "Monthly fee" of type integer +and default of "10000"
  13. Add a third attribute called test.
  14. Make sure you can see all the attributes. Delete the test +attribute
  15. +Go to "/admin/object-types/one?object_type=project" and +ensure that start_date and monthly fees are listed as attributes. +Also make sure:
      +
    • test attribute is not visible
    • monthly_fee has a default specified (NULL) in the pl/sql +parameter list
    • start_date has no default specified
      • +
    +
  16. Go to "/admin/object-types/one?object_type=subproject" +and ensure the new attributes of project are in the pl/sql +package
  17. Now go back to the group type admin page for the +"Projects" group type. Remove the composition relation. Make sure +you get a link back to add a relationship type. Add back the +composition relation.
  18. Add a group of type project named +GuideStar.org
    19. +

RELATIONSHIP TYPE PAGES BASIC FUNCTIONALITY

    +
  1. Create a new relationship type, Employment relation, that +is a subtype of Membership relation, between group and person. +Group has role of employer, person role of employee.
  2. Select the employment relation and add an attribute age +(integer, not required)
  3. Delete the employment relationship type.
  4. Re-add the employment relationship type (we're testing to +make sure the age attribute is correctly removed and flushed from +the cache)
  5. Click on membership relation, then click on create +subtype
  6. Click on membership relation -> Create subtype type: +project_lead_relation name: Project Lead between projects (the +composite) and persons (the project leader new role)
  7. Create a new, dummy rel type, subtype of Project Lead +Relation. Make sure the only things in object type one are project +and subproject
  8. Select the dummy relationship type and then delete +it.
  9. Select the Employment relation and add a required +attribute "salary" (type integer)
    10. +

SEGMENTS, CONSTRAINTS AND RELATIONS

    +
  1. Go back to the admin page (/admin)
  2. Click on the Groups -> GuideStar.org. Add ArsDigita as +a component
  3. Remove the composition rel type from this +group
  4. Readd the composition rel type. Make sure arsdigita +doesn't show up
  5. remove the composition rel type
  6. Add a permissible rel type: +project_lead_relation
  7. Click yes to create a rel segment named "GuideStar +Project Leads"
  8. Go back to /admin/groups
  9. Click on "relationship to site"
  10. Remove yourself from the group.
  11. Add yourself again as a member (using the membership +relation). You will have to select an existing party from the +system.
  12. Make sure you see the segment "Main Site Members" for +parties with a membership relation to the main site.
  13. Go to the ArsDigita group.
  14. Add guidestar.org as a component
  15. Remove the membership relation type from this +group
  16. Add the employment relation type
  17. Create a segment named "ArsDigita employees"
  18. Add a constraint named "ArsDigita employees must be Main +Site Members" for employees and the segment "Main Site +Members"
  19. Go back to the guidestar.org group
  20. Add yourself as a project lead.
  21. Click on the project lead segment "GuideStar Project +Leads"
  22. Click delete this segment. Say no.
  23. Click delete this segment. Say Yes.
  24. Recreate the "GuideStar Project Leads" +segment
  25. Add a constraint named "Project leads must be employees" +that says all "project leaders must be employees of +ArsDigita"
  26. Make sure you see yourself as a violation. Remove the +violating relation and finish adding the constraint
  27. Try to add a project leader to guidestar. You should see +that there "There is no other Person that can be added as Project +Leader to GuideStar.Org"
  28. Add yourself as an arsdigita employee
  29. Make yourself the project lead on +guidestar.org
  30. Go back to /admin/groups and select "relationship typ +site." Remove your membership relation. You should get prompted to +remove relation to arsdigita, then to guidestar. Remove all of +these relations.
  31. Make yourself a project lead of guidestar +again.
    32. +

Testing with more Users

Now we're going to test that the user interface remains +consistent if there are a few more users.
    +
  1. Go to /acs-admin/users and add 4 users
  2. Go to /admin/groups and click on "relationship to site." +You should see all of the people you just entered listed as members +of the subsite.
  3. Try to remove your Membership relation. You should see +only one constraint violation.
  4. Remove one of the other people from the registered users +group. You should be allowed to do it immediately.
  5. Add back the person you removed.
  6. Remove yourself from the registered users group. Make +yourself a project lead on guidestar again.
  7. Make another user a project lead on +guidestar.
    8. +

CLEANING UP

    +
  1. Go to /admin/group-types
  2. Select the project group type
  3. Delete this group type. Should get prompted to delete sub +projects group type.
  4. Delete the sub projects group type.
  5. Should get prompt to delete the project lead rel +type
  6. Delete the project lead rel type. Continue until you +delete the project group type.
  7. Delete the ArsDigita group.
  8. Go to /admin/rel-types/
  9. Click on "View all roles"
  10. Click on "Project Leader" - delete this role
  11. Click on "Employer" then on Employment +Relation
  12. Delete the employment relation type.
  13. Delete the employee, employer, and project_leader +roles
  14. Delete any groups you created for the developer defined +type
  15. +Drop the developer defined type (in SQL*Plus):
    exec acs_object_type.drop_type('developer_defined_test_type'); 
+drop table developer_defined_test_types;
+drop package developer_defined_test_type;
+
    +
    16. +
Michael +Bryzek
+
$Id: group-admin-pages-acceptance-test.html,v 1.3 +2003/09/30 12:10:03 mohanp Exp $ + + Index: openacs-4/packages/acs-subsite/www/doc/group-admin-pages-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/group-admin-pages-design.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-subsite/www/doc/group-admin-pages-design.adp 17 Sep 2014 19:06:31 -0000 1.1.2.1 @@ -0,0 +1,139 @@ + +{/doc/acs-subsite {Subsite}} {Group Admin Pages - Design} +Group Admin Pages - Design + + + +

Group Admin Pages - Design

ACS subsite docs : Group Admin Pages - Design +

I. Essentials

II. Introduction

+The group administration packages provides a "control panel" to +allow the administrator of a subsite to control the groups in use +on that subsite. Administrators manage the types of groups in use +on a subsite. For each of these group types, the administrator can +create new groups, specify applicable relationship types, create +relations between these groups, and modify attributes of the types +and groups. +

III. Historical Considerations

+Versions 4.0.x of the ACS lacked a useful group administration +package for subsites. For example: +
    +
  • Groups were given no context
  • Groups could not be deleted
  • Group types could not be created
  • Relationships were limited to membership and composition, not +including subtypes of these two.
    • +
+This package addresses most of the short-coming of the previous +subsites group administration package making group administration +subsite aware and better integrated with the ACS Object Model. +

IV. Design Tradeoffs

+Whenever possible, the design of this package tries to minimize +disturbance to the core ACS 4.0 data model. Instead, we focus on +adding a more powerful user interface and PL/SQL API to the +existing group admin pages while extending the data model only when +necessary. +

V. API

Permissible relationship types

+We defined the following two tables to store the relationship type +used to store the permissible relationship types for group types +and individual groups. Whenever a group is created using the +acs_group.new function, the relationship types for the +new group are automatically copied from those allowed for its group +type. +
+create table group_type_rels (
+       group_rel_type_id      integer constraint gtr_group_rel_type_id_pk primary key,
+       rel_type               not null 
+                              constraint gtr_rel_type_fk
+                              references acs_rel_types (rel_type)
+                              on delete cascade,
+       group_type             not null 
+                              constraint gtr_group_type_fk
+                              references acs_object_types (object_type)
+                              on delete cascade,
+       constraint gtr_group_rel_types_un unique (group_type, rel_type)
+);
+
+
+create table group_rels (
+       group_rel_id           integer constraint group_rels_group_rel_id_pk primary key,
+       rel_type               not null 
+                              constraint group_rels_rel_type_fk
+                              references acs_rel_types (rel_type)
+                              on delete cascade,
+       group_id               not null 
+                              constraint group_rels_group_id_fk
+                              references groups (group_id)
+                              on delete cascade,
+       constraint group_rels_group_rel_type_un unique (group_id, rel_type)
+);
+
+

Dynamic subtypes of object types

+To allow administrators to create dynamic object types (e.g. +subtypes of the object types group, +membership_rel, and composition_rel), we +provide a Tcl library of procedure that generate PL/SQL packages. +For each dynamically created object type, we: +
    +
  • We create the ACS object type
  • We create a table to store the attributes for the new type
  • We create a PL/SQL package with a new function and delete +procedure
    • +
+Whenever an attribute is added or deleted, a type added or removed, +we regenerate some of the PL/SQL packages, based on the type +hierarchy affected by the change. +

Attributes themselves are stored using +type-specific storage. For each new attribute, we +create a column in the table dynamically created for the new object +type.

To support the clean separation between programmer defined +PL/SQL packages and automatically generated packages, we add the +dynamic_p column to the acs_object_types +table.

+acs_object_types.dynamic_p       char(1) default 'f' 
+                                 constraint acs_obj_types_dynamic_p_ck
+                                 check (dynamic_p in ('t', 'f'))
+

Note that the dynamic_p is still experimental +and may be removed in a future version of ACS

VII. Data Model Discussion

+... +

VIII. User Interface

+The user interface comprises entirely of administrative pages +located in the /admin/ directory of the subsite +package. +

IX. Configuration/Parameters

+The revised group administration pages require no new package +parameters. +

X. Future Improvements/Areas of Likely Change

+There are many areas for improvement to the user interface, +including tighter integration with the relational segments and +constraints packages. One major improvement would allow individual +subsites to define their own group types and relationship types, +separate from any other subsite. However, since ACS object types +are not themselves objects, it is difficult to properly scope +object types. +

We also may add a few additional package parameters +including:

    +
  • "Create Group Types" (Boolean). Determines whether new group +types can be created dynamically.
  • "Create Relationship Types" (Boolean). Determines whether new +relationship types can be created dynamically.
    • +

XI. Authors

+This document is primarily the result of discussions between Oumi +Mehrotra and Michael Bryzek. Bryan Quinn and Rafi Schloming +provided key insights early in the development process. +

XII. Revision History

+ + + + + + + +
Document Revision #Action Taken, NotesWhen?By Whom?
0.1Creation11/30/2000Michael Bryzek
1.0Major Revision1/11/2001Michael Bryzek
Michael +Bryzek

group-admin-pages-design.html,v 1.1.4.1 2001/01/12 +22:43:33 mbryzek Exp + Index: openacs-4/packages/acs-subsite/www/doc/group-admin-pages-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/group-admin-pages-requirements.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-subsite/www/doc/group-admin-pages-requirements.adp 17 Sep 2014 19:06:31 -0000 1.1.2.1 @@ -0,0 +1,135 @@ + +{/doc/acs-subsite {Subsite}} {Group Admin Pages - Requirements} +Group Admin Pages - Requirements + + + +

Group Admin Pages - Requirements

+ACS subsite docs : Group Admin Pages - +Requirements

I. Introduction

The subsites package offers a powerful way to create discrete +collections of subcommunities on top of a single ACS installation. +The package must be permissions-aware for all groups, relational +segments and constraints, and relations.

The subsites package must also allow administrators to +dynamically extend existing group and relationship types and to +define attributes for new types.

II. Vision Statement

From /doc/subsites-requirements.html:
The other piece of the subsite system is a +subsite package that provides subsite admins a "control panel" for +administering their subsite. This is the same package used to +provide all the community core functionality available at the +"main" site which is in fact simply another +subsite.
This control panel needs to treat individual groups as +belonging to a single instance of a subsite. However, groups +themselves are not enough. We must allow a subsite to specify its +own types of groups, instances of those types (or of a type from a +parent subsite), and types of relationships between those +groups.

III. Historical Motivations

In the ACS 3.x architecture, many modules, e.g. portals, +intranet, and bboard, created their own group types to manage +different aspects of the module. While it is true that the ACS +Permissioning package will replace the need for group types used +exclusively for controlling permissions, some modules require the +logical grouping of other parties. For these modules, we must +restrict administrative control of their groups to administrators +of the subsite. Without this ability, a user with administrative +privilege of one subsite can administer all other groups in the +system.

IV. Use case and User Scenarios

The Intranet Application

The Intranet application may model employees in many ways. +Without loss of generality, we assume each employee is a "person" +with an "employment relation" to a company. Figure 1 shows an +outline of what the ACS Site Map may look like with several +companies. Note that each company represents one instance of the +intranet application.

+
Figure 1: Structure of Multiple Intranets +
The employment relation is a subtype of the ACS Membership +Relation with additional attributes specific to employees (e.g. +salary, start date, etc.). Administrators of each instance of the +intranet application must be able to create the subtype and to +specify the attributes of the subtype dynamically. For example, the +ArsDigita administrator may track salary, biography, and education +while IBM administrators may choose to track salary and family +member information.
Note: The current version of ACS, +4.0.1, does not treat object types as objects. This is a problem +for subsites wishing to support dynamic sub-typing as name +collisions are common because object types do not have context. The +ability to create unique types of relationships for a given +instance of the intranet application requires the object type to be +unique to the instance. In other words, the context of the object +type is set to the subsite. We use the context here so that we can +automatically maintain permissions from subsite to object +type.

VI.A Requirements: Data Model

+
10.10 Default relationship types for group +types

Each group type should specify a set of permissible +relationship types to use for groups of that type.


10.20 Default relationship types for +groups

The administrator must be able to specify the permissible +relationship types to use for each group. The defaults are +inherited from the list of permissible relationship types for the +group's type.

+

VI.B Requirements: API

+
20.10 Define a new group type

Users should be able to create a new type of +group.

30.10 Specify attributes

Users should be able to dynamically add attributes to +group types. These attributes should be stored +efficiently.

35.10 Remove attributes

Users should be able to dynamically remove attributes from +a group type. Removing the attribute removes all values specified +for that attribute.

40.10 Relationship Constraints

The API must support the following types of constraints on +relationships:

40.10.10 Permissible relationships

Each group type should maintain a list of all relationship +types that can be used to add elements to groups of this group +type.

40.10.20 Constraints on relationships

Relationships listed as allowable for a given group type +should link to more information about the relationship type, +including any constraints that must be satisfied before relations +of the specified type are created.

40.10.30 Constrain membership to a given +group

The system provides a well-defined API call that adds a +given relationship type to the list of allowable relationship types +to apply to a given group or group type. Any subtype of an +allowable relationship type will also be allowed.

+

VI.C Requirements: User Interface

+
+100.10 Create a group type with +attributes

When creating a new group type, the UI should support ACS +datatypes with appropriate UI.

+130.10 Group type summary page
+
+130.10.10 Display allowable relationship +types

The group type summary page should display all the +relationship types used to add relations to groups of this type and +allow the user to add permissible relationship types or to remove +existing ones.

+130.10.20 Display groups

Display all groups of this type, based on permissions. UI +should scale well with a large number of groups.

+110.10 Create an instance of a particular group +type

When creating a new group of the specified type, the UI +must request values for each of the attributes of that type, +including attributes of all supertypes (up the type tree until the +object of type 'group').

+130.10.20 Display type attributes

Display all attributes for this group type, including +supertypes.

+130.10.20 Delete group type

Allow administrators to delete the group type. This action +removes all groups of this type.

+
+
+150.10 Group instance summary page
+
+150.10.10 Display relations

Each group should display all the parties related to it +and through what relationship type. Offer links to remove each +relation or to add a new relation of a given type. The UI for +relations should scale well.

+150.10.20 Display attributes

Display all attributes of the group with links to edit +each.

+150.10.20 Delete group

Allow administrators to delete the group including all +relations to the group.

+150.20 Integration with relational Segments and +Constraints

The group summary page should offer links to define +relational segments for the group, based on a particular +relationship type. The UI must also integrate with the relational +constraints data model to support defining constraints on +intra-party relations.

+

Revision History

+ + + + + + + + + +
Document Revision #Action Taken, NotesWhen?By Whom?
0.1Creation11/16/2000Michael Bryzek
0.2Major Revisions11/24/2000Michael Bryzek
1.0Final Revisions1/11/2001Michael Bryzek
Michael +Bryzek

$Id: group-admin-pages-requirements.html,v 1.2 +2001/08/11 21:31:03 ben Exp $ + Index: openacs-4/packages/acs-subsite/www/doc/images.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/images.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-subsite/www/doc/images.adp 17 Sep 2014 19:06:31 -0000 1.1.2.1 @@ -0,0 +1,137 @@ + +{/doc/acs-subsite {Subsite}} {ACS Subsite Documentation} +ACS Subsite Documentation + + + +

Images available from the acs-subsite package

+Image can be included with a link of the form <img +src="/resources/acs-subsite/FILENAME\" /> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
action-link-marker.png
add.gif
Add16.gif
Add24.gif
arrow-down.gif
arrow-up.gif
attach.png
bold-button.gif
checkbox.gif
checkboxchecked.gif
Copy16.gif
Copy24.gif
Delete16.gif
Delete24.gif
diamond.gif
down.gif
Edit16.gif
Edit24.gif
email.gif
email_add.gif
email_delete.gif
email_open.gif
feed.gif
go.gif
http.png
info.gif
italic-button.gif
left.gif
new.gif
New16.gif
New24.gif
Open16.gif
Open24.gif
Preferences16.gif
Preferences24.gif
profile-16.png
Properties16.gif
Properties24.gif
radio.gif
radiochecked.gif
right.gif
spacer.gif
stock_copy-16.png
stock_copy.png
stock_first-16.png
stock_first.png
stock_last-16.png
stock_last.png
stock_left-16.png
stock_left.png
stock_right-16.png
stock_right.png
underline-button.gif
up.gif
url-button.gif
xml.gif
Zoom16.gif
Zoom24.gif
ZoomIn16.gif
ZoomIn24.gif
ZoomOut16.gif
ZoomOut24.gif
+ Index: openacs-4/packages/acs-subsite/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/www/doc/index.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-subsite/www/doc/index.adp 17 Sep 2014 19:06:31 -0000 1.1.2.1 @@ -0,0 +1,32 @@ + +{/doc/acs-subsite {Subsite}} {ACS Subsite Documentation} +ACS Subsite Documentation + + + +

ACS Subsite Documentation

+ACS subsite docs +

Document overview

+ + + + + + + + + + + +
Overall +requirementsOverview of the requirements that motivated the design of +subsites.
DesignOverview of the API provided by ACS subsites including the +package manger, site nodes, and request processor hooks.
Group +admin pages requirementsOverview of the requirements for web-based group administration +tools
Group admin +pages designOverview of the API and design of the web-based group +administration
Subsite imagesShows all (hopefully) images available from the subsite +package
Michael +Bryzek

$Id: index.html,v 1.2 2005/01/13 13:55:49 jeffd Exp +$ + 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 -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/design.adp 17 Sep 2014 19:06:32 -0000 1.1.2.1 @@ -0,0 +1,284 @@ + +{/doc/acs-templating {Templating}} {Template System} +Template System + + + +

The Template System -- Design Document

+by Christian Brechbühler Templating System : +Design +

I. Essentials

    +
  • User directory -- none; www exists only for +documentation.
  • ACS administrator directory -- none.
  • Subsite administrator directory -- none.
  • +Tcl script directory. Almost no +procedures show up here. To minimize dependencies across packages, +in particular on ad_proc from acs-kernel, +this package uses proc.
  • PL/SQL API -- none.
  • Data model -- none. Templating does not depend on a database +system at all. There's the one table +ad_template_sample_users that some of the +demonstrations use.
  • Requirements document
  • ER diagram -- none.
  • Transaction flow diagram -- none.
    • +

II. Introduction

    +
  • +What this package is intended to allow the user to +accomplish.

    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 +(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.

      • +
    +
  • +

    What this package is not intended to allow users to +accomplish.

      +
    • Tcl "pages" that do not return anything visible to the user. +Such pages may be, e.g., the action= target of a form. +They typically call ad_returnredirect after completing +their job.
    • Tcl scripts that are scheduled to run in the server without a +connection to a user.
      • +
    +
  • +The application domains where this package is most likely +to be of use.

    User interface. Any application that delivers visible pages to a +user. Any page that returns content (HTML or other) in response to +an HTTP[S] request.

    +
  • +

    How the package meets its requirements.

      +
    • It supplies a set of custom markup +tags.
    • The proc 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 +manipulating multirow data sources.
    • The mechanism for dynamically generating pages combines data +and layout. It also allows coposition of modular pages from +reusable widges and skins. It is not limited to HTML.
    • The <master> tag specifies a master +template. Its src attribute defaults to the site-wide +master template.
      • +
    +
    • +

III. Historical Considerations

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.

V. Design Tradeoffs

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.

+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 +of ns_sets, which was significantly less efficient. The datasources +are not being copied around; they reside in a specific stack frame. +Using the uplevel Tcl command, we make sure that the +data file (tcl part of a page) executes in the same stack frame as +the compiled template (the adp part), so the latter can make use of +the data sources prepared by the former.
+        Thus, we decided for +performance, simplicity, and ease of use +at the cost of using the (standard Tcl) commands upvar +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 +estimated priorities are listed, not the degree to which +the attributes are being achieved:

    +
  • Performance (high): Early versions of the templating system +were a compuational burden. This has been fixed. Thanks to +compilation of .adp pages and caching of both .adp and .tcl parts +as procs, templated pages are much faster now; the caching can in +fact make a templated page faster than an old-style .tcl page, +which is sourced and parsed on every request.
  • Flexibility (high): the recursive composition of pages allows +for a big deal of flexibility.
  • Interoperability (low): The templating system must tie in with +the request processor for delivery of pages and with +ad_page_contract for the specification of the expected +parameters (called query) and the datasources it will supply +(called properties). The templating system is registered with the +request processor as the handler for both adp and +tcl extensions.
  • Reliability and robustness (medium): Considering how many parts +have to play together, one might not predict a very reliable +system. In practice, the package works reliably. It is robust to +user errors in the sense that it won't error out if a file is +missing or such; rather it quietly proceeds. Error reporting to the +user is not very sophisticated.
  • Usability (high): Emphasis has been put on the easy use of the +system. In particular, a graphics designer should only have to +learn a small number of special markup tags.
  • Maintainability (medium): The code is well structured in +reasonably sized procedures, and well commented.
  • Portability (high): Unlike most other parts of the ACS, the +templating system can work standalone. It doesn't need the database +nor the acs-kernel or any other part of the ACS. All you need is +AOLserver with the fancy ADP parser.
  • Reusability (low): Many parts of the templating system are +actually generally reusable, and probably should be extracted into +a common set of utility procs used by this package and the ACS; +this would reduce code duplication. The API lets programmers call +into the system at different level. The templating system will +probably mostly deliver HTML pages, but it has also been used to +format mass mailings (spam), and any other formal (e.g., XML) could +be used.
  • Testability(low): A demonstration sample page exercises most +mechanisms of the templating system.
    • +

VI. API

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:

    +
  • onevalue (string)
  • onerow
  • multirow
  • onelist
  • multilist
    • +

Currently ad_page_contract does not allow +specifying the latter two.

Process Flow

+In a simple case, the following is the sequence of steps that +serving a templated page involves. +
    +
  1. The request processor gets a url and maps it to a +.adp or .tcl file. As both invoke the +same handler, it doesn't matter that adp take precendence.
  2. If a .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.
  3. The rest of the tcl script executes, defining these data +sources. It may change the name of the page being served by calling +template::set_file directly or through the wrapper +ad_return_template.
  4. The corresponding template (file stub.adp) is +interpreted and the data sources from the .tcl script are +interpolated into the template.
  5. The HTML is streamed to the client by the handler.
    6. +
+Less simple cases involve dependent templated pages. They are +requested with the <include> and +<master> tags. In these cases, Tcl and/or ADP +parsing happens recursively. +

Tcl Call Stack

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.

+ + + + + + + + + + + + + + + + + +
LevelProcedureArguments
#1rp_handler
#2rp_serve_abstract_file/web/service/www/page
#3rp_serve_concrete_file/web/service/www/page.adp
#4adp_parse_ad_conn_file
#5template::adp_parse/web/service/www/page {}
(6)template::adp_prepare
#5template::code::tcl::/web/service/www/page

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 +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.

Caching and Template Compilation

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, +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.

VII. Data Model Discussion

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.

VIII. User Interface

This packages doesn't have a user interface. It is the +substrate of all user interfaces, be it user or admin +pages.

IX. Configuration/Parameters

+There are two parameters. +
+      [ns/server/yourservername/acs/template]
+      ; the site-wide Master template
+      DefaultMaster=/www/default-master
+      ; anything other than "never" or "always" means normal operation
+      RefreshCache=as necessary
+    
+

X. Future Improvements/Areas of Likely Change

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.

Authors

XII. Revision History

+ + + + + + + +
Document Revision #Action Taken, NotesWhen?By Whom?
0.1Brought into the form suggested by Finkler, +McLoghlin and Wu +18 Jul 2000Christian Brechbühler
0.2Adapted to acs-templating as distributed with ACS/Tcl 4.0122 Nov 2000Christian Brechbühler
Christian +Brechbuehler
+Last modified: $Id: design.html,v 1.2.26.1 2014/09/09 08:32:01 +gustafn Exp $ + 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 -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/designer-guide.adp 17 Sep 2014 19:06:32 -0000 1.1.2.1 @@ -0,0 +1,93 @@ + +{/doc/acs-templating {Templating}} {Template Designer Guide} +Template Designer Guide + + + +

Designer Guide

Templating System : Designer Guide +

Overview

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:

    +
  • Embed a dynamic variable in a template (var).
  • Repeat a template section for each object in a dynamic list of +objects (multiple, +grid).
  • Output different template sections depending on the value of +one or more dynamic variables (if).
  • Provide a mechanism for building complete pages from multiple +component templates (include).
    • +

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.

Concepts

This section introduces the basic concepts underlying the use of +template tags in ACS 4.0.

Variable 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 data sources.

See Variable +Substitution.

Use of Components

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 +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 +master. See also Building reusable layout components and +Using master templates.

Property Declarations

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.

Conditional Insertion

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.

Iteration

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:

    +

  1. First and last items may be formatted differently from items in +between.

  2. 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.

  3. Colors or patterns may alternate between items. For example, the +designer may want to have alternate between white and gray bands in +a table.

    4. +

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.

See multiple, +group, grid.

Notes

    +

  • 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 +in the HTML source code of the delivered page.

  • +

    With normal usage, the use of dynamic tags tends to increase the +amount of whitespace in the final HTML as compared to the template. +This usually does not affect how browsers display the page. +However, if a page layout depends on the presence or absence of +whitespace between HTML tags for proper display, then special care +must be taken with dynamic tags to avoid adding whitespace.

    When placed on a line by themselves, tags that are containers +for template sections (grid, if, and +multiple) will cause newlines to be added to the page at +the beginning and end of the section. This can be avoided by +crowding the start and end tags like so:

    +<td><if %x% eq 5><img src="five.gif"></if>
+<else><img src="notfive.gif"></else></td>
+

    Note that this should not be done unless necessary, since it +reduces the legibility of the template to others who need to edit +the template later.

    +

  • +Caution:   Do not write to the connection. +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.

    • +
Christian +Brechbuehler
+Last modified: Mon Oct 2 14:12:08 EDT 2000 + Index: openacs-4/packages/acs-templating/www/doc/developer-guide.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/developer-guide.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/developer-guide.adp 17 Sep 2014 19:06:32 -0000 1.1.2.1 @@ -0,0 +1,85 @@ + +{/doc/acs-templating {Templating}} {Template System Guide} +Template System Guide + + + +

Programmer / Developer Guide

Templating System : Developer Guide +

Mini How To

+Start a Tcl page as usual with ad_page_contract. Be +sure to pass a -properties block; this signals the use +of templating. The tcl page should fill the data sources you +promised in the contract, and not write to the connection. At the +end of your tcl page, call ad_return_template. The +template system will look for an adp page with the file name stub +you indicate (defaulting to the same stub as the tcl page), process +that, and deliver it to the client. The adp page can use the +datasources defined in the tcl page. +

Guide

    +
  1. User Guide
  3. Object and API Reference + +
  4. Template Markup Tag Reference
  5. Appendices + +
    6. +

API

+After the script for a page is executed, acs-templating processes +the template, interpolating any data sources and executing the +special tags. The resulting HTML page is written to the connection +(i.e., returned to the user). +
ad_return_template
+Normally, does nothing at all. With the -string option +you get the resulting HTML page returned as a string. +

The optional template argument is a path to a page +(tcl/adp file pair). Note that you don't supply the ".tcl" or +".adp" extension. It is resolved by help of +template::util::url_to_file (with the current file +stub as reference path) and passed to +template::set_file, to change the name of the page +being served currently. If it starts with a "/", it is taken to be +a path relative to the server root; otherwise it is a filename +relative to the directory of the tcl script.

ad_page_contract
+Normally, complaints about incorrect parameters are written +directly to the connection, and the script is aborted. With the +option -return_errors you can name a variable into +which to put any error messages as a list, and +ad_page_contract will return in any case. You can then +present the errors to the user in a templated page, consistent with +the look and feel of the rest of your service. If there's no +complaint, ad_page_contract won't touch the variable; +typically it will stay undefined. +
Christian +Brechbühler
+Last modified: $Id: developer-guide.html,v 1.3 2004/02/10 12:16:40 +joela Exp $ + Index: openacs-4/packages/acs-templating/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/index.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/index.adp 17 Sep 2014 19:06:33 -0000 1.1.2.1 @@ -0,0 +1,44 @@ + +{/doc/acs-templating {Templating}} {Templates} +Templates + + + +

Templating System

+Templating System +

Document overview

+ + + + + + + + + + + + + + + + + + + + + +
RequirementsWhat the template system should do for you.
NoquoteA revision in 5.0 that escapes all html codes by default.
DesignGets more specific and discusses the way the templating system +integrates with ACS. Gory details.
Designer +GuideWriting a Template, the ADP part of a page
+        + TagsTemplate markup tag reference
Using NoquoteUpgrading and writing new pages with noquote.
+Developer Guide + API for programming the Tcl part of a page
+API, TclDoc API Viewer +   Object and API Reference
MigrationBringing legacy tcl pages to use the template system.
DemonstrationSamples of the various mechanisms, with both Tcl and ADP +parts.
Christian +Brechbühler
+Last modified: $Id: index.html,v 1.4.20.1 2014/09/09 08:32:02 +gustafn Exp $ + Index: openacs-4/packages/acs-templating/www/doc/install.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/install.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/install.adp 17 Sep 2014 19:06:33 -0000 1.1.2.1 @@ -0,0 +1,89 @@ + +{/doc/acs-templating {Templating}} {Templating System: Installation} +Templating System: Installation + + + +

Installation

The templating system may be used alone or in conjunction with +version 4.0 or greater of the ArsDigita Community System (ACS). The +following instructions apply to a standalone installation only.

Requirements

The templating system requires version 3.1 or greater of +AOLserver for Unix or Windows. Until version 3.1 is officially +released, you must use the ArsDigita distribution of +AOLserver 3.0, which includes some required patches to the ADP +parser. These patches have been integrated into AOLserver 3.1.

To use the database interface for merging dynamic data with your +templates, you will also need to have installed any +AOLserver-compatible RDBMS.

Obtaining the distribution

To install the templating system, download and unpack the tar +file under your page root:

+$ wget http://bob.sf.arsdigita.com:8089/ats/ats.tar.gz
+$ cd /web/myserver/www
+$ gunzip -c ats.tar.gz | tar xvf -
+

The distribution consists of four subdirectories:

    +
  1. +demo: A set of sample templates and supporting +files.
  2. +doc: Documentation and tutorials.
  3. +tcl: The Tcl module.
  4. +resources: Sitewide style templates for forms +and error messages and associated assets.
    5. +

You can also untar (or check out) the distribution somewhere +else and symlink it under your page root. (If you do not wish to +install the distribution under your page root, see the +configuration options below).

Installing the Tcl module

The templating system code is a Tcl-only module for AOLserver. +For AOLserver to load the module source code, you must move, copy +or symlink the tcl directory in the templating system +distribution to the private Tcl library of your AOLserver +installation (as indicated by the Library parameter in the +ns/server/myserver/tcl section of the AOLserver +configuration file):

+$ cd /web/myserver/tcl
+$ ln -s <path_to_distribution>/ats/tcl/ ats
+

Configuring AOLserver

The last step is to modify your AOLserver configuration file. +You will need to register the templating system as a Tcl-only +module:

+[ns/server/myserver/modules]
+nssock=nssock.so
+nslog=nslog.so
+ats=Tcl
+

or if you are using the new configuration file format:

+ns_section "ns/server/${server}/modules"
+ns_param   nssock          nssock.so
+ns_param   nslog           nslog.so
+ns_param   ats          Tcl
+

Note that you should replace ats with whatever you +named the directory or symlink for the templating code within your +private Tcl library.

You will also need to ensure that the "fancy" ADP parser is the +default:

+[ns/server/yourserver/adp]
+Map=/*.adp
+DefaultParser=fancy
+
+[ns/server/yourserver/adp/parsers]
+fancy=.adp
+

Optional Configuration

The templating system recognizes two optional parameters in the +AOLserver configuration file in the +ns/server/yourserver/ats section:

+ + + + + + + + + +
DatabaseInterfaceSpecifies the set of procedures to use for accessing a +relational database from the templating system. Two interfaces are +supplied with the system: oracle (uses the ns_ora +API in conjunction with the AOLserver Oracle driver) and +generic (uses the ns_db API in conjunction with +any AOLserver RDBMS driver). The default is Oracle.
ShowCompiledTemplatesPEnables a filter on the cmp extension so that the +compiled Tcl code for any template may be viewed in a browser for +debugging purposes. The default is 0 (disabled).
ShowDataDictionariesPEnables a filter on the dat extension so that +documentation directives in Tcl scripts may be extracted and viewed +in a browser. The default is 1 (enabled).
ResourcePathSpecifies the absolute path to the system templates +directory, containing sitewide styles for forms, system messages, +etc. Defaults to $::acs::pageroot/ats/resources.

Testing the System

To test the system, run the script demo/demo.sql to +create and populate a simple table in your database.

Save the configuration file and restart the server. Use the +samples included in the distribution to test whether the system is +working properly.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/introduction.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/introduction.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/introduction.adp 17 Sep 2014 19:06:33 -0000 1.1.2.1 @@ -0,0 +1,47 @@ + +{/doc/acs-templating {Templating}} {Templating System: Goals} +Templating System: Goals + + + +

Goals

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 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.

    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/migration.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/migration.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/migration.adp 17 Sep 2014 19:06:33 -0000 1.1.2.1 @@ -0,0 +1,550 @@ + +{/doc/acs-templating {Templating}} {Templating an Existing Tcl Page} +Templating an Existing Tcl Page + + + +

Templating an Existing Tcl Page

Templating System : Migration +

In a Nutshell

+When templatizing a legacy tcl page, your task is to +separate code and graphical presentation. The latter goes +into an ADP file; it contains essentially HTML, augmented by a few +special tags and the \@variable\@ construct. The +code goes into a Tcl script. In other words, a templated page +consists of two files, a Tcl part that puts its results in data +sources, and an ADP page (the template), into which these data +sources will be interpolated to yield a complete HTML page. +

General

As usual, the Tcl page should start with a call to +ad_page_contract. In its -properties +block you promise the data sources that your script will provide; +they were earlier called page properties, hence the name +of the option. Then your script performs all the computations and +queries needed to define these data sources. There are special +mechanisms for handling multirow data sources; see below.

At the end of the Tcl script, you should call +ad_return_template. The template runs after the tcl +script, and can use these data sources.

Make sure that the fancy adp parser is enabled in your AOL ini +file.

+      [ns/server/myserver/adp]
+      DefaultParser=fancy
+

A few more hints

    +
  • Do not write to the connection directly. Avoid +ns_puts, ns_write etc., which don't wait +till the headers are written or the page is completed; they may act +differently than you expect.
  • If you can, put code in the tcl file, not between <% +%> in the adp page.
  • Put HTML in the adp page, not int the tcl program. Put reusable +HTML fragments in a separate adp file (think of it as a widget) +that will be <include>d from several pages. +Prefer this to writing a tcl proc that returns HTML.
  • Remember to remove backslashes where you had to escape special +characters, as in +
    +Nuts  \$2.70 \[<a href=\"shoppe\">buy</a>\]
+          
+
    +
    • +

Forms

+There is nothing special about building forms; just use the +<form> tag as always. All HTML tags can be used +in the ADP file (template). +

A simple page

First I take a page from the news package as an example. For +simplicity, I pick item-view, which does not use a +<form>. I reformatted it a bit to make three +panes fit next to each other and to line up corresponding code.

+ + + + + + + +
old tcl codenew
packages/news/www/item-view.tclpackages/news/www/item-view.adp
+# /packages/news/admin/index.tcl
+ad_page_contract {
+
+    View a news item.
+
+    \@author Jon Salz (jsalz\@arsdigita.com)
+    \@creation-date 11 Aug 2000
+    \@cvs-id $Id: migration.adp,v 1.1.2.1 2014/09/17 19:06:33 gustafn Exp $
+
+} {
+    news_item_id:integer,notnull
+}
+
+
+
+
+
+
+
+
+db_1row news_item_select {
+    select *
+    from news_items
+    where news_item_id = :news_item_id
+}
+
+set body "
+[ad_header $title]
+<h2>$title</h2>
+[ad_context_bar [list "" "News"] $title]
+
+<hr>
+
+<p>Released $release_date:
+
+<blockquote>
+$body
+</blockquote>
+
+[ad_footer]
+"
+
+doc_return 200 text/html $body
+return
+
+
+ad_page_contract {
+
+    View a news item.
+
+    \@author Jon Salz (jsalz\@arsdigita.com)
+    \@creation-date 11 Aug 2000
+    \@cvs-id $Id: migration.adp,v 1.1.2.1 2014/09/17 19:06:33 gustafn Exp $
+
+} {
+    news_item_id:integer,notnull
+} -properties {
+  body:onevalue
+  release_date:onevalue
+  title:onevalue
+  header:onevalue
+  context_bar:onevalue
+  footer:onevalue
+}
+
+db_1row news_item_select {
+    select *
+    from news_items
+    where news_item_id = :news_item_id
+}
+
+
+
+
+set context_bar [ad_context_bar \
+    [list "" "News"] $title]
+
+
+
+
+
+
+
+
+
+
+
+ad_return_template
+          
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<master>
+<property name="doc(title)">\@title\@</property>
+<property name="context">\@context;noquote\@</property>
+
+<hr>
+
+<p>Released \@release_date\@:
+
+<blockquote>
+\@body\@
+</blockquote>
+
+          
+

Multi-Row Data Sources

+Technically, the result of a query that may return multiple rows is +stored in several arrays. This datasource is filled by a call to +db_multirow, and the repeating part of the HTML output +is produced by the <multiple> tag. The following +example shows the part of the index page of the News +module that uses the mechanism, not a whole page. + + + + + + + + + + + + +
old tcl codenew
packages/news/www/index.tclpackages/news/www/index.adp
ad_page_contract {
+
+    Displays a list of 
+    available news items.
+
+    \@param archive_p show archived
+                      news items?
+    \@author Jon Salz (jsalz\@mit.edu)
+    \@creation-date 11 Aug 2000
+    \@cvs-id $Id: migration.adp,v 1.1.2.1 2014/09/17 19:06:33 gustafn Exp $
+} {
+}
+ad_page_contract {
+
+    Displays a list of available
+    news items.
+
+    \@param archive_p show archived
+                      news items?
+    \@author Jon Salz (jsalz\@mit.edu)
+    \@creation-date 11 Aug 2000
+    \@cvs-id $Id: migration.adp,v 1.1.2.1 2014/09/17 19:06:33 gustafn Exp $
+} {
+} -properties {
+  header:onevalue
+  context_bar:onevalue
+  subsite_id:onevalue
+  subsite:multirow
+item:multirow
+  footer:onevalue
+}
+
 
.........
+append body "
+<ul>
+"
+
+db_foreach news_items_select {
+    select news_item_id, title
+    from news_items_obj
+    where context_id = :subsite_id
+    and sysdate >= release_date
+    and (   expiration_date is null
+         or expiration_date > sysdate)
+} {
+    append body "<li><a href=
+        \"item-view?news_item_id="\
+        "$news_item_id\"
+        >$title</a>\n"
+
+
+} if_no_rows {
+    append body "<li>There are 
+        currently no news items
+        available.\n"
+}
+
+append body "
+<p><li>You can use the <a href=
+    \"admin/\">administration
+    interface</a> to post a new
+    item (there's currently no
+    security in place).
+
+</ul>
+"
+
+db_multirow item
+ news_items_select {
+    select news_item_id, title
+    from news_items_obj
+    where context_id = :subsite_id
+    and sysdate >= release_date
+    and (   expiration_date is null
+         or expiration_date > sysdate)
+}
+          
+
+
+<ul>
+
+
+<multiple name=item>
+
+
+
+
+
+
+
+  <li><a href=
+      "item-view?news_item_id=<%
+      %>\@item.news_item_id\@"
+      >\@item.title\@</a>
+</multiple>
+
+<if \@item:rowcount\@ eq 0>
+  <li>There are
+  currently no news items
+  available.
+</if>
+
+
+<p><li>You can use the <a href=
+  "admin/">administration
+  interface</a> to post a new
+  item (there's currently no
+  security in place).
+
+</ul>
+          
+
+Notes: +
    +
  • I use the general <if> construct to handle +the case when no lines are returned. (The +<multiple> loop just executes zero times.)
  • For a list of the available tags, refer to the templating +documentation.
  • Blue color marks additional syntax necessary to wrap lines +short.
  • The proc db_multirow does have a code block and an +optional if_no_rows block, just like +db_foreach. They aren't used in the example, +though.
    • +

If you have a more complicated db_foreach, where logic is +performed inside the body, then it might be helpful to build your +own multirow variable. In the excert below, taken from +/pvt/alerts.tcl and /pvt/alerts.adp, the foreach logic made it hard +to use the db_multirow because it needed a combination of the +output from sql and also the output of tcl procedures using that +value.

+ + + + + + + + + + + +
old tcl codenew
packages/acs-core-ui/www/pvt/alerts.tclpackages/acs-core-ui/www/pvt/alerts.adp
ad_page_contract {
+    \@cvs-id $Id: migration.adp,v 1.1.2.1 2014/09/17 19:06:33 gustafn Exp $
+} {
+}
+ad_page_contract {
+    \@cvs-id $Id: migration.adp,v 1.1.2.1 2014/09/17 19:06:33 gustafn Exp $
+} {
+} -properties {
+    header:onevalue
+    decorate_top:onevalue
+    ad_footer:onevalue
+    discussion_forum_alert_p:onevalue
+    bboard_keyword_p:onevalue
+    bboard_rows:multirow
+    classified_email_alert_p:onevalue
+    classified_rows:multirow
+    gc_system_name:onevalue
+}
+
 
.........
+
+
+if { [db_table_exists "bboard_email_alerts"] } {
+ 
+ set counter 0
+
+
+
+
+
+
+
+
+ db_foreach alerts_list "
+ select bea.valid_p, bea.frequency,
+        bea.keywords, bt.topic, bea.rowid
+ from bboard_email_alerts bea, bboard_topics bt
+ where bea.user_id = :user_id
+ and bea.topic_id = bt.topic_id
+ order by bea.frequency" {
+   incr counter
+
+   if { $valid_p == "f" } {
+     # alert has been disabled 
+     set status "Disabled"
+     set action "
+     <a href=\"/bboard/alert-reenable\">
+     Re-enable</a>"
+   } else {
+     # alert is enabled
+     set status "
+     <font color=red>Enabled</font>"
+     set action "
+     <a href=\"/bboard/alert-disable\">
+     Disable</a>"
+   }
+
+   append existing_alert_rows "<tr>
+   <td>$status</td>
+   <td>$action</td>
+   <td>$topic</td>
+   <td>$frequency</td>"
+
+   if { [bboard_pls_blade_installed_p] == 1 } {
+     append existing_alert_rows "
+     <td>\"$keywords\"</td>"
+   }
+   append existing_alert_rows "</tr>\n"
+
+ }
+
+ if  { $counter > 0 } {
+   set wrote_something_p 1
+   set keyword_header ""
+   if { [bboard_pls_blade_installed_p] == 1 } {
+     set keyword_header "<th>Keywords</th>"
+   }
+   append page_content "
+   <h3>Your discussion forum alerts</h3>
+
+   <blockquote>
+   <table>
+   <tr>
+   <th>Status</th>
+   <th>Action</th>
+   <th>Topic</th>
+   <th>Frequency</th>
+   $keyword_header
+   </tr>
+
+   $existing_alert_rows
+   </table>
+   </blockquote>
+   "
+ }
+}
+          
+
+set discussion_forum_alert_p 0
+
+if { [db_table_exists "bboard_email_alerts"] } {
+  set discussion_forum_alert_p 1
+
+  set rownum 0
+
+  if { [bboard_pls_blade_installed_p] == 1 } {
+    set bboard_keyword_p 1
+  } else {
+    set bboard_keyword_p 0
+  }
+        
+  db_foreach alerts_list "
+  select bea.valid_p, bea.frequency,
+         bea.keywords, bt.topic, bea.rowid
+  from bboard_email_alerts bea, bboard_topics bt
+  where bea.user_id = :user_id
+  and bea.topic_id = bt.topic_id
+  order by bea.frequency" {
+  incr rownum
+
+  if { $valid_p == "f" } {
+    # alert has been disabled for some reasonset bboard_rows:[set rownum](status) "disable"
+    set bboard_rows:[set rownum](action_url) "
+    /bboard/alert-reenable"
+  } else {
+    # alert is enabledset bboard_rows:[set rownum](status) "enable"
+    set bboard_rows:[set rownum](action_url) "
+    /bboard/alert-disable"
+  }
+
+  set bboard_rows:[set rownum](topic) $topic
+  set bboard_rows:[set rownum](frequency) $frequency
+  set bboard_rows:[set rownum](keywords) $keywords
+        
+  } if_no_rows {
+    set discussion_forum_alert_p 0
+  }
+  set bboard_rows:rowcount $rownum
+  
+}
+
+          
+          
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<if \@discussion_forum_alert_p\@ eq 1>
+
+<h3>Your discussion forum alerts</h3>
+
+<blockquote>
+   <table>
+   <tr><th>Status</th>
+       <th>Action</th>
+       <th>Topic</th>
+       <th>Frequency</th>
+     <if \@bboard_keyword_p\@ eq 1>
+       <th>Keyword</th>
+     </if>
+   </tr>
+ <multiple name=bboard_rows>
+
+   <tr>
+      <if \@bboard_rows.status\@ eq "enabled">
+       <td><font color=red>Enabled</font></td>
+       <td><a href="\@bboard_rows.action_url\@">
+       Disable</a></td>
+      </if>
+      <else>
+       <td>Disabled</td>
+       <td><a href="\@bboard_rows.action_url\@">
+       Re-enable</a></td>
+      </else>
+       <td>\@bboard_rows.topic\@</td>
+       <td>\@bboard_rows.frequency\@</td>
+     <if \@bboard_rows.bboard_keyword_p\@ eq 1>
+       <td>\@keyword</td>
+     </if>
+   </tr>
+ 
+ </multiple>
+   </table>
+</blockquote> 
+
+</if>
+          
+
+Christian +Brechbühler, Hiro +Iwashima +
+Last modified: $Id: migration.html,v 1.2.22.2 2014/09/09 08:32:02 +gustafn Exp $ + Index: openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/no-quote-upgrade.adp 17 Sep 2014 19:06:33 -0000 1.1.2.1 @@ -0,0 +1,268 @@ + +{/doc/acs-templating {Templating}} {Upgrading existing ADPs to noquote templating} +Upgrading existing ADPs to noquote templating + + + +

Upgrading existing ADPs to noquote templating

Introduction.

+The variable substitution in the templating has been changed to +become more friendly towards quoting. The rationale for the change +and the definition of terms like quoting are present in +the quoting article. As it discusses +these concepts in some depths, we see no reason to repeat them +here. Instead, we will assume that you have read the previous +article and focus on the topic of this one: the changes you need to +apply to make your module conformant to the new quoting rules. +

This text is written as a result of our efforts to make the ACS +installation for the German Bank project work, therefore it is +based on field experience rather than academic discussion. We hope +you will find it useful.

Recap of the Theory.

+The change to the templating system can be expressed in one +sentence: +
All variables are now quoted by default, except those +explicitly protected by ;noquote.
+This means that the only way your code can fail is if the new code +quotes a variable which is not meant to be quoted. Which is where +;noquote needs to be added. That's all porting effort that +is required. +

This is not hard because most variables will not be affected by +this change. Most variables either need to be quoted (those +containing textual data that comes from the database or from the +user) or are unaffected by quoting (numerical database IDs, etc.) +The variables where this behavior is undesired are those that +contain HTML which is expected to be included as part of the +page, and those that are already quoted by Tcl code. Such +variables should be protected from quoting by the ;noquote +modifier.

The Most Common Cases.

+The most common cases where you need to add ;noquote to +the variable name are easy to recognize and identify. +

+Hidden form variables.
+Also known as "hidden input fields", hidden form variables are form +fields with pre-defined values which are not shown to the user. +These days they are used for transferring internal state across +several form pages. In HTML, hidden form variables look like +this:

+<form>
+  <input name=var1 value="value1">
+  <input name=var2 value="value2">
+  ... real form stuff ...
+</form>
+      
+
+ACS has a convenience function for creating hidden form variables, +export_form_vars. It accepts a list of variables and +returns the HTML code containing the hidden input tags that map +variable names to variable values, as found in the Tcl environment. +In that case, the Tcl code would set the HTML code to a variable: +
+set form_vars [export_vars -form {var1 var2}]
+      
+
+The ADP will simply refer to the form_vars variable: +
+<form>
+  \@form_vars\@              <!-- WRONG!  Needs noquote -->
+  ... real form stuff ...
+</form>
+      
+
+This will no longer work as intended because form_vars +will be, like any other variable, quoted, and the user will end up +seeing raw HTML text of the hidden variables. Even worse, the +browser will not be aware of these form fields, and the page will +not work. After protecting the variable with ;noquote, +everything works as expected: +
+<form>
+  \@form_vars;noquote\@
+  ... real form stuff ...
+</form>
+      
+

+Snippets of HTML produced by Tcl code, aka +widgets +.
+Normally we try to fit all HTML code into the ADP template and have +the Tcl code handle the "logic" of the program. And yet, sometimes +pieces of relatively convoluted HTML need to be included in many +templates. In such cases, it makes sense to generate the +widget programmatically and include it into the template as +a variable. A typical widget is a date entry widget which provides +the user the input and selection boxes for year, month, and day, +all of which default to the current date.

Another example of widgets is the context bar often found +on top of ACS pgages.

Obviously, all widgets should be treated as HTML and therefore +adorned with the ;noquote qualifier. This also assumes +that the routines that build the widget are correctly +written and that they will quote the components used to +build the widget.

+Pieces of text that are already quoted.
+This quoting is usually part of a more general preparation for HTML +rendering of the text. For instance, a bboard posting can be either +HTML or text. If it is HTML, we transmit it as is; if not, we +perform quoting, word-wrapping, etc. In both cases it is obvious +that quoting performed by the templating system would be redundant, +so we must be careful to add ;noquote to the ADP.

The property and include Gotchas.

+Transfer of parameters between included ADPs often requires manual +addition of ;noquote. Let's review why. +

The property tag is used to pass a piece of information +to the master template. This is used by the ADP whose writer +consciously chose to let the master template handle a variable +given by the Tcl code. Typically page titles, headings, and context +bars are handled this way. For example:

+master:
+<head>
+  <title>\@title\@</title>
+</head>
+<body bgcolor="#ffffff">
+  <h1>\@heading\@</h1>
+  <slave>
+</body>
+      
+
slave:
+<master>
+<property name="title">\@title\@</property>
+<property name="heading">\@title\@</property>
+...
+      
+
+
+The obvious intention of the master is to allow its slave templates +to provide a "title" and a "heading" of the page in a standardized +fashion. The obvious intention of our slave template is to allow +its corresponding Tcl code to set a single variable, +title, which will be used for both title and heading. +What's wrong with this code? +

The problem is that title gets quoted twice, once by +the slave template, and once by the master template. This is the +result of how the templating system works: every +occurrence of \@variable\@ is converted to +[ad_quotehtml $variable], even when it is +used only to set a property and you would expect the quoting to be +suppressed.

Implementation note: Ideally, the +templating system should avoid this pitfall by quoting the variable +(or not) only once, at the point where the value is passed from the +Tcl code to the templating system. However, no such point in time +exists because what in fact happens is that the template gets +compiled into code that simply takes what it needs from the +environment and then does the quoting. Properties are passed +to the master so that all the property variables are shoved into an +environment; by the time the master template is executed, all +information on which variable came from where and whether it might +have already been quoted is lost.

This occurrence is often referred to as over-quoting. +Over-quoting is sometimes hard to detect because things seem to +work fine in most cases. To notice the problem in the example above +(and in any other over-quoting example), the title needs to contain +one of the characters <, > or +&. If it does, they will appear quoted to the user +instead of appearing as-is.

Over-quoting is resolved by adding ;noquote to one of +the variables. We strongly recommend that you add ;noquote +inside the property tag rather than in the master. The +reason is that, first, it makes sense to do so because conceptually +the master is the one that "shows" the variable, so it makes sense +that it gets to quote it. Secondly, a property tag is +supposed to merely transfer a piece of text to the master; +it is much cleaner and more maintainable if this transfer is +defined to be non-lossy. This becomes important in practice when +there is a hierarchy of master templates -- e.g. one for +the package and one for the whole site.

To reiterate, a bug-free version of the slave template looks +like this:

+slave sans over-quoting:
+<master>
+<property name="title">\@title;noquote\@</property>
+<property name="heading">\@title;noquote\@</property>
+...
+      
+
+

The exact same problems when the include statement +passes some text. Here is an example:

+Including template:
+<include src="user-kick-form" id=\@kicked_id\@ reason=\@default_reason\@>
+      
+
Included template:
+<form action="do-kick" method=POST>
+  Kick user \@name\@.<br>
+  Reason: <textarea name=reason>\@reason\@</textarea><br>
+  <input type=submit value="Kick">
+</form>
+      
+
+
+Here an include statement is used to include an HTML form widget +parts of which are defined with Tcl variables $id and +$default_reason whose values presumably come from the +database. +

What happens is that reason that prefills the +textarea is over-quoted. The reasons are the same as in +the last example: it gets quoted once by the includer, and the +second time by the included page. The fix is also similar: when you +transfer non-constant text to an included page, make sure to add +;noquote.

+Including template, sans over-quoting:
+<include src="user-kick-form" id=\@kicked_id\@ reason=\@default_reason;noquote\@>
+      
+
+

Upgrade Overview.

+Upgrading a module to handle the new quoting rules consists of +applying the process mentioned above to every ADP in the module. +Using the knowledge gained above, we can specify exactly what needs +to be done for each template. The items are sorted approximately by +frequency of occurrence of the problem. +
    +
  1. Audit the template for variables that export form variables and +add ;noquote to them.
  2. More generally, audit the template for variables that are known +to contain HTML, e.g. those that contain widgets or HTML content +provided by the user. Add ;noquote to them.
  3. Add ;noquote to variables used inside the +property tag.
  4. Add ;noquote to textual variables whose values are +attributes to the include tag.
  5. Audit the template for occurrences of +<%= [ad_quotehtml \@variable\@] => +and replace them with \@variable\@.
  6. Audit the Tcl code for occurrences of ad_quotehtml. If +it is used to build an HTML component, leave it, but take note of +the variable the result gets saved to. Otherwise, remove the +quoting.
  7. Add ;noquote to the "HTML component" variables noted +in the previous step.
    8. +
+After that, test that the template behaves as it should, and you're +done. +

Testing.

+Fortunately, most of the problems with automatic quoting are very +easy to diagnose. The most important point for testing is that it +covers as many cases as possible: ideally testing should cover all +the branches in all the templates. But regardless of the quality of +your coverage, it is important to know how to conduct proper +testing for the quoting changes. Here are the cases you need to +watch out for. +
    +
  • +HTML junk appearing in the page.
    +Literal HTML visible to the user typically comes from an +"export_form_vars" or a widget variable that lacks +;noquote. To fix the problem, simply add ;noquote +to the variable.
  • +Over-quoting and under-quoting.
    +To detect quoting defects, you need to assume an active role in +naming your objects. The best way to do it is to create objects +(bboard forums, messages, news items, etc.) with names that contain +the representation of an entity, e.g. "&copy;". This +looks like the copyright SGML entity, and intentionally so. The +testing consists of checking that the browser prints exactly what +you typed in as the name. Thus if your forum/message/etc. is listed +as "&copy;", everything is OK. If it is listed as +"&amp;copy;", it means that the string was quoted +twice, i.e. over-quoted. Finally, if the entity is interpreted +(shown as ©), it means that the string lacks quoting, i.e. it +is under-quoted. +

    To get rid of over-quoting, make sure that the variables don't +get quoted in transport, such as in the property +tag or as an attribute of the include tag. Also, make sure +that your Tcl code is not quoting the variable name.

    To get rid of under-quoting, make sure that your variable gets +quoted exactly once. This can be achieved either by removing a +(presumably overzealous) ;noquote or by quoting the string +from Tcl. The latter is necessary when building HTML components, +such as a context bar, from strings that come from the database or +from the user.

    +
    • +
Hrvoje +Niksic
+Last modified: Mon Oct 7 12:27:47 CEST 2002 + Index: openacs-4/packages/acs-templating/www/doc/noquote.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/noquote.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/noquote.adp 17 Sep 2014 19:06:33 -0000 1.1.2.1 @@ -0,0 +1,195 @@ + +{/doc/acs-templating {Templating}} {HTMLQuoting as Part of the Templating System - +Requirements} +HTMLQuoting as Part of the Templating System - +Requirements + + + +
+ +
+
+

+HTMLQuoting as +Part of the Templating System - Requirements

+
+

+The Templating System.

Templating systems, as deployed by most web software, serve to +distinguish the programming logic of the system from the +presentation that is output to the user.

Before introduction of a templating systems to ACS, pages were +built by outputting HTML text directly from Tcl code. Therefore it +was hard for a designer or a later reviewer to change the +appearance of the page. "Change the color of the table? How do I do +that when I cannot even find the body tag?" At this point some +suggest to embed Tcl code in the document rather than the other way +around, like PHP does. But it doesn't solve the problem, because +the code is still tightly coupled with the markup, requiring +programmer-level understanding for every change. The only workable +solution is to try to uncouple the presentation from the design as +much as possible.

ACS 4.0 addressed the problem by introducing a custom-written +templating system loosely based on the already-present capabilities +of the AolServer, the ADP pages. Unlike the ADP system, which +allowed the coder to register his own tags to encapsulate +often-used functionality, the new templating system came with a +pre-programmed set of tags that performed the basic transformations +needed to process the page, and some additional value.

Comparing ACS templating to other templating systems, it is my +impression that the former was designed to be useful in real life +rather than minimalistic -- which is only makes sense given the +tight deadlines most ArsDigita projects have to face. Besides the +if tag, multiple tag and \@variable\@ variable substitution, which +are sufficient to implement any template-based page, it also +includes features like including one template in another, +customizing site- or module-wide look using the master templates, +directly importing query results to the template, facilities for +building grid-tables, and more. This utilitarian approach to +templating urges us to consider the quoting issues as integral part +of the system.

+
+

+Quoting.

In the context of HTML, we define quoting as transforming text +in such a way that the HTML-rendered version of the transformed +text is identical to the original text. Thus one way to quote the +text "<i>" is to transform it to "&lt;i&gt;". When a +browser renders the transformed text, entities &lt; and +&gt; are converted back to < and >, which makes the +rendered version of the transformation equal to the original.

The easiest way to guarantee correct transformation in all cases +is to "escape" ("quote") all the characters that HTML considers +special. In the minimalistic case, it is enough to transform &, +<, and > into their quoted equivalents, &amp;, &lt;, +and &gt; respectively. For additional usefulness in quoted +fields, it's a good idea to also quote double and single quotes +into &quot; and &#39; respectively.

All of this assumes that the text to be quoted is not meant to +be rendered as HTML in the first place. So if your text contains +"<i>word</i>", and you expect the word to show up in +italic, you should not quote that entire string. However, if word +in fact comes from the database and you don't want it to, for +instance, close the <i> behind your back, you should quote +it, and then enclose it between <i> and </i>.

The ACS has a procedure that performs HTML quoting, +ad_quotehtml. It accepts the string that needs to be quoted, and +returns the quoted string. In ACS 3.x, properly written code was +expected to call ad_quotehtml every time it published a string to a +web page. For example:

+doc_body_append "<ul>\n" set db [ns_db gethandle] set selection
+[ns_db select $db {SELECT name FROM bboard_forums}] while {[ns_db
+getrow $db $selection]} { set_variables_after_query doc_body_append
+"<li>Forum: <tt>[ad_quotehtml $name]</tt>\n" }
+doc_body_append "</ul>\n"
+

Obviously, this was very error-prone, and more often than not, +the programmers would forget to quote the variables that come from +the database or from the user. This would "usually" work, but in +some cases it would lead to broken pages and even pose a security +problem. For instance, one could imagine a mathematicians' forum +being named "0 < 1", or an HTML designers' forum being named +"The Woes of <h1>".

In some cases the published variable must not be quoted. +Examples for that are the bboard postings that are posted in HTML, +or variables containing the result of export_form_vars. All in all, +the decision about when to quote had to be made by the programmer +on a case-by-case basis, and many programmers simply enjoyed the +issue because the resulting code happened to work in 95% of the +cases.

Then came ACS 4. One hoped that ACS 4, with its advanced +templating system, would provide an easy and obvious solution for +the (lack of) quoting problem. It turned out that this did not +happen, partly because no easy solution exists, and partly because +the issue was ignored or postponed.

Let's review the ACS 3.x code from above. The most important +change is that it comes in two parts: the presentation template, +and the programming logic code. The template will look like +this:

+<ul> <multiple name=forums> <li>Forum:
+  <tt>\@forums.name\@</tt> </multiple> </ul>
+

Once you understand the (simple) workings of the multiple tag, +this version strikes you as much more readable than the old one. +But we're not done yet: we need to write the Tcl code that grabs +forum names from the database. The db_multirow proc is designed +exactly for this; it retrieves rows from the database and assigns +variables from each row to template variables in each pass of a +multiple of our choice.

+db_multirow forums get_forum_names { SELECT name FROM forums }
+

At this point the careful reader will wonder at which point the +forum name gets quoted, and if so, how does the templating system +know whether the forum name needs to be quoted or not? The answer +is amazingly blunt: no quoting happens anywhere in the process. If +a forum name contains HTML special characters, you have a +problem.

There are two remedies for this situation, and neither is +particularly appealing. One can rewrite the nice db_multirow with a +db_foreach loop, manually create a multirow, and feed it the quoted +data in the loop. That is ugly and error-prone because it is more +typing and it requires you to explicitly name the variables you +wish to export at several points. It is exactly the kind of ugly +code that db_multirow was designed to avoid.

The alternative approach means less typing, but it's even uglier +in its own subtle way. The trick is to remember that our templating +still supports all the ADP features, including embedding Tcl code +in the template. Thus instead of referring to the multirow variable +with the \@forums.name\@ variable substitutions, we use +<%= [ad_quotehtml \@forums.name\@] %>. This +works correctly, but obviously breaks the abstraction barrier +between ADP and Tcl syntaxes. The practical result of breaking the +abstraction is that every occurrence of Tcl code in an ADP template +will have to be painstakingly reviewed and converted once ADPs +start being invoked by Java code rather than Tcl.

At this point, most programmers simply give up and don't quote their variables at all . +Quoting is handled only in the areas where it is really crucial and +where not handling it would quote immediate and visible breakage, +such as in the case of displaying the bodies of bboard articles. +This is not exaggeration; it has been proven by auditing the ACS +4.0, both manually and through grepping for ad_quotehtml. +Strangely, this otherwise sad fact allows us to deploy a very +radical but much more robust solution to the problem.

+
+

+Quote Always, Except +When Told Not to.

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:

    +

  1. Those that need to be quoted -- names and descriptions of +objects, and in general stuff that ultimately comes from the +user.

  2. Those for which it doesn't make a difference whether they are +quoted or not -- e.g. all the database IDs.

  3. Those that must not be quoted -- e.g. exported form vars stored +to a variable.

  4. Finally we also remembered the fact that almost none of the +variables are quoted in the current source base.

    5. +

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 +the variables from the first and the second category will be +handled correctly, and the variables from the third category will +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 +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 +code with \@foo;noquote\@.

The change took two people less than one day for the system that +consisted of core ACS 4.0.1, and modules bboard, news, chat, and +bookmarks. (We were also doing other things, so it's hard to +measure correctly.) During two of the following days, we would find +a broken page from time to time, typically by spotting the +obviously visible HTML markup. Such a page would get fixed it in a +matter of seconds by appending ;noquote to the name of the +offending variable.

We launched successfully within schedule.

+
+

+Porting the quoting +changes to the ACS.

After some discussion, it was decided that these changes will be +included into the next ACS release. Since the change is +incompatible, it will be announced to module owners and the general +public. Explanation on how to port your existing modules and the +"gotchas" that one can expect follows in a separate +document .

The discussion about speed, i.e. benchmarking results before and +after the change, is also +available .

Hrvoje Niksic

+
+
+
+ + + + + +
docs\@openacs.org
+
View +comments on this page at openacs.org
+ 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 -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/requirements.adp 17 Sep 2014 19:06:34 -0000 1.1.2.1 @@ -0,0 +1,201 @@ + +{/doc/acs-templating {Templating}} {ACS Templating Requirements} +ACS Templating Requirements + + + +

ACS Templating Requirements

+by Karl Goldstein, +Christian +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

+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 +allows for easier maintenance and more efficient workflow. Thus the +ACS 4 Templating system provides mechanisms that allow programmers +and graphic designers to work independently of each other. +Templates specify the layout of the page separately from the +dynamic content of the page. Graphic designers work primarily on +the layout, that is the template, while programmers work primarily +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

+The templating system provides: +
    +
  • A set of custom markup tags (using ADP, AOLserver Dynamic +Pages) that are used to specify page layout, and to declare where +dynamically generated content belongs in the layout.
  • An API for specifying the content part of the page. This API is +used by programmers to specify the script that generates the +content in a page.
  • A mechanism for combining the data (from a data source) with +the layout (from a layout template) into a single dynamically +generated HTML page.
  • A mechanism for specifying a single master template to be used +for multiple pages.
    • +

IV. Use-cases and User-scenarios

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:

    +
  1. A notation and API for the programmer specify the application +logic and to generate the data to be displayed. In ACS, we call the +data that we wish to display a data source or page +property. Application logic is driven by the inputs the page +gathers from the user request (e.g. the HTTP request), and the +computation that the page must perform on this input. This +computation will generally create and populate the data sources and +page properties. Data sources tend to be connected to database +queries, while page properties can be defined by any arbitrary +computation.
  2. A notation and API for the designer to specify how the data +sources and page properties will be presented to the user. This +notation will generally take the form of some kind extended +HTML.
  3. A mechanism for communicating the data sources and page +properties from the logic part of the page
    4. +

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.

+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.

V. Related Links

  • Design document

VI.A Functional Requirements

    +
  • +10.0 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 in the toolkit.

    +10.0.1

    The system should not make any assumptions about how pages +should look or function.

    10.0.5

    Publishers should be able to change the default presentation of +any module using a single methodology with minimal exposure to +code.

    +
    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.

    +10.5.1 Page Properties +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 Implementation

    Programmers must be able to generate and populate the page +properties they promise. This includes page properties of types: +onevalue, onerow, multirow, onelist, and multilist.

    +
    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.

      +
    • +10.10.1 Variable +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 Components

      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.

      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 Communication

      Template 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 Insertion

      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. 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).

      +
    • +10.10.5 Iteration

      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.

      +
      • +
    +
  • +20.0 Separation of Code and +Layout

    Programmers should be able to specify the page properties +independently of the markup used to present the data in the +template. Markup authors should be to able to write templates that +reference the page properties without further intervention from the +programmer to produce a finished page.

    +20.5 Programmer - Graphic +Designer Communication

    A graphic designer must be able to look at the documentation for +a page in a documentation browser and find out what properties a +page publishes and what types they are. This documentation should +be available through the standard ACS documentation facilities.

    +
    +
  • +30.0 Separation of Page +Components

    There should be provisions so that pages can be broken into +discrete components to simplify maintenance of the markup 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.

    +
  • +40.0 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.

    +
  • +50.0 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.

    +
  • +60.0 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.

    +
    • +

VI.B Non-functional Requirements

    +
  • +100.0 Distribution

    The Templating System must be releasable as part of the ACS and +as a separate product. When distributed as part of the ACS all +documentation, examples, and source code must follow ACS standards. +This includes but is not limited to: using the db_api, +using ad_page_contract appropriately.

    +
  • +110.0 Performance

    The Templating System must not cause any performance problems to +a site. It must be fast and efficient, and it must not slow down +page load speed by more than 10% versus a Tcl page with inline +HTML.

    +
    • +

VII. Revision History

+ + + + + + + + + +
Document Revision #Action Taken, NotesWhen?By Whom?
0.1Creation8/23/2000Yonatan Feldman
0.2Merge with previous docs8/25/2000Christian BrechbÃ&frac14;hler
0.3Edited, reviewed, pending freeze8/28/2000Kai Wu
yon\@arsdigita.com
+Last modified: $Id: requirements.html,v 1.1.1.1.28.1 2014/09/09 +08:32:02 gustafn Exp $ + Index: openacs-4/packages/acs-templating/www/doc/requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/requirements.html,v diff -u -N -r1.1.1.1.28.1 -r1.1.1.1.28.2 --- openacs-4/packages/acs-templating/www/doc/requirements.html 9 Sep 2014 08:32:02 -0000 1.1.1.1.28.1 +++ openacs-4/packages/acs-templating/www/doc/requirements.html 17 Sep 2014 19:06:34 -0000 1.1.1.1.28.2 @@ -15,15 +15,15 @@
- +

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

On websites of sufficient size, a consistent look and feel (the @@ -42,7 +42,7 @@ - of a website's pages, so the overall layout of a site can be more easily administered. - +

III. System Overview

The templating system provides: @@ -73,7 +73,7 @@ - +

IV. Use-cases and User-scenarios

@@ -148,12 +148,12 @@ - +

VI.A Functional Requirements

  • - + 10.0 A Common Solution

    Programmers and designers should only have to learn a single @@ -278,7 +278,7 @@

  • - + 20.0 Separation of Code and Layout

    Programmers should be able to specify the page properties @@ -303,7 +303,7 @@

  • - + 30.0 Separation of Page Components

    There should be provisions so that pages can be broken into @@ -315,7 +315,7 @@

  • - + 40.0 Global Control Over Presentation

    There should be a way to define one or more standard master @@ -325,7 +325,7 @@

  • - + 50.0 Dynamic Selection of Presentation Style

    Given that the same data may be presented in many different ways, @@ -337,7 +337,7 @@

  • - + 60.0 Usability

    Programmers should be able to develop template specifications @@ -350,12 +350,12 @@

- +

VI.B Non-functional Requirements

  • - + 100.0 Distribution

    The Templating System must be releasable as part of the ACS and as @@ -369,7 +369,7 @@

  • - + 110.0 Performance

    The Templating System must not cause any performance problems to a Index: openacs-4/packages/acs-templating/www/doc/timing-1.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing-1.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/timing-1.adp 17 Sep 2014 19:06:34 -0000 1.1.2.1 @@ -0,0 +1,39 @@ + +{/doc/acs-templating {Templating}} {Template Timing Results} +Template Timing Results + + + +

    Results

    +The measurements were taken on dev0103-001 on 5 +October 2000, probably with acs-4-0-beta-R20001001. Here are the +graphs for the 14 stages, titled by the log message of their +beginning. +

    Invoking preauth filter rp_filter

    No difference; all take about 2.6 ms. The same is the case for +the few following stages: Short times and apparently independent of +the kind of page.

    Looking for node to match +/acs-templating/admin/test/chain-frac-0.

    Found /acs-templating/.

    Performing developer support logging

    Checking for changed libraries

    Handling authentication

    For some reason, this seems to take much longer on the Tcl-only +page. Maybe because it's the first in a triple of pages that +e-Tester requests? There may be a little longer time gap between +chain-frac-2 and the next request of chain-frac-0

    Handling authorization

    An unexplained but clear distinction here: 0 is faster than 2, +and 1 is slowest.

    Done invoking preauth filter rp_filter (returning +filter_ok)

    Invoking registered procedure rp_handler

    Searching for +/webroot/web/brech/acs/packages/acs-templating/www/admin/test/chain-frac-0.*

    Serving +/webroot/web/brech/acs/packages/acs-templating/www/admin/test/chain-frac-0.tcl +with rp_handle_tcl_request

    Here the actual work supposedly happens. The Tcl-only page is +clearly fastest. Always reparsing pages expectedly affects the +templated page, and -2, which compiles two ADP pages, is affected +more than -1. The benefit of -2, wrapping -1 in another include, +isn't apparent; on the contrary, -1 is in all cases a bit faster +than -2. The benefit of cacheing seems more than offset by the +extra complexity of nesting several templates.

    Invoking trace filter ad_issue_deferred_dml

    For some reason, the Tcl-only page takes significantly +longer.

    Done invoking trace filter ad_issue_deferred_dml (returning +filter_ok)

    Invoking trace filter ds_trace_filter

    That last phase is ended by Done invoking trace filter +ds_trace_filter (returning filter_ok) +

    Total time

    Overall, the templated pages are delivered faster. +Forcing the template system to always reread all files and to +recompile the ADP part slows them down, as expected, but overall +they are still faster than the Tcl-only page.

    Christian +Brechbuehler
    +Last modified: Tue Oct 17 20:04:29 EDT 2000 + Index: openacs-4/packages/acs-templating/www/doc/timing-2.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing-2.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/timing-2.adp 17 Sep 2014 19:06:34 -0000 1.1.2.1 @@ -0,0 +1,23 @@ + +{/doc/acs-templating {Templating}} {Template Timing Results} +Template Timing Results + + + +

    Results

    +The measurements were taken on reusia.boston on 13 +October 2000, with approximately acs-4-0-beta-2-R20001009. +

    Here are the graphs for the 15 stages, and the log message of +their beginning is written in the lower right of the graphs. In +comparison with the first measurement, +the steeper slopes indicate much less variation in the +measurements, which reflects the more reproducible conditions +(essentially no other activity) on reusia.boston in comparison with +dev0103-001.

    Individual Stages

    Total Time (Sum of all Stages)

    Overall, the templated pages are delivered markedly +slower, by about 65ms. Forcing the template system to always +reread all files and to recompile the ADP part slows them down, as +expected, but overall they are still faster than the Tcl-only +page.

    Christian +Brechbuehler
    +Last modified: Wed Oct 18 16:45:17 EDT 2000 + Index: openacs-4/packages/acs-templating/www/doc/timing-3.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing-3.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/timing-3.adp 17 Sep 2014 19:06:34 -0000 1.1.2.1 @@ -0,0 +1,25 @@ + +{/doc/acs-templating {Templating}} {Template Timing Results} +Template Timing Results + + + +

    Results

    The measurements were taken on reusia.boston on 17 +October 2000, with tarball acs-3-4-6-R20001008. Templating under +3.4 is quite different; instead of a .tcl script, datasources are +defined in a .data file that has a different XML syntax.

    We have graphs for 9 stages only. While Tcl pages generate four +more entries, these lack from templated pages, and hence I +suppressed them. The log message that marks the beginning of each +phase is written in the lower right of the graphs. Each curve curve +plots 288 page requests. As I didn't back port of the configurable +cache refreshing stragegy ('never' or 'always'), I show all graphs +in the 'normal' colors. The label is 'do', though.

    Individual Stages

    Total Time (Sum of all Stages)

    To show off the graphing method, compare the graph above with +the one below, which only uses the first 32 measurements. The +curves are less smooth, but the message is the same.

    In ACS 3.4.6, Tcl-only pages are sereved faster than in +4.0 beta-2. The templated pages are delivered much slower. +The first time the template system reads a templated page, it takes +about 3 seconds! The result is cached, mitigating the problem a +lot.

    Christian +Brechbuehler
    +Last modified: Tue Oct 17 20:26:14 EDT 2000 + Index: openacs-4/packages/acs-templating/www/doc/timing.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/timing.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/timing.adp 17 Sep 2014 19:06:34 -0000 1.1.2.1 @@ -0,0 +1,165 @@ + +{/doc/acs-templating {Templating}} {Timing a Templated Page} +Timing a Templated Page + + + +

    Timing a Templated Page

    +by Christian +Brechbühler

    I. Introduction

    +One of the requirements for the +template system asks for efficiency: +
    • +110.0 Performance

      The Templating System must not cause any performance problems to +a site. It must be fast and efficient, and it must not slow down +page load speed by more than 10% versus a Tcl page with inline +HTML.

      +
    +This page documents the attempt to verify this requirement. +

    II. Methods

    I wrote a sample page for this test. It expands four real +numbers into continued fractions. I created three versions:

      +
    • +chain-frac-0, +a Tcl page with inline HTML,
    • +chain-frac-1, +a templated page, i.e. a Tcl and an HTML file, and
    • +chain-frac-2, +an ADP page that simply <include>s +chain-frac-1.
      • +

    The reason for creating chain-frac-2.adp is that in +this way, the script chain-frac-1.tcl is handled +inside the templating system, and hence loaded once and cached. +There is hope that this might be faster.

    Normally, the templating system re-reads a file whenever the +version on disk is out of date. ADP pages are compiled to TCL, and +both ADP and Tcl pages are cached as Tcl procs. The parameter +RefreshCache in section template can be +set to always or never to affect the +cacheing strategy; the latter may be useful for a production site. +All timing is carried out for the three settings +always, normal, and never; +the associated variable is called check.

    I created a script in e-Tester that requests the three pages +from my development server on dev0103-001. One timing of requesting +a page isn't very expressive. A lot of factors affect the page load +time. To offset these and get better results, I repeatedly request +the pages. For the timing, I have e-Tester iterate this script 200 +times. To compesate for varying load on the machine, i ran the +iteration twice for each setting of RefreshCache at +different times of the day.

    The timing information is taken from the error log file entries +that the request processor produces with parameter +LogDebugP=1. For finer granularity I changed rp_debug +to divide the clock clicks (microsecond) difference by 1000.0 +instead of 1000. Delivering a page gives us 15 log file entries +with timestamps. I treat the first one (? ms) as 0. There must be +no other page requests from this AOLserver during the measurement. +I note the length of the error log before and after one run of the +script. Afterwards I cut out the error log sections indicated by +these positions into files never, normal, +and always.

    The following steps extract the relevant information and bring +it in a form suitable for gnuplot.

      +
    • +Extract time from log file sections. This is done in +tcsh. +
      +foreach i ( never normal always )
+  fgrep '] Notice: RP (' $i                        >  $i-0
+  echo                                             >  $i-1
+  foreach conn (`cut -d- -f2 always-0 | sort -u`)
+    echo "$i '$conn'"
+    fgrep "[-$conn-]" $i-0 | cut -d: -f5-          >> $i-1
+  end
+  cut -d" " -f3 $i-1| cut -c2-| tr \? 0            >  $i-2
+end
+        
+
      +The three resulting files, ending in -2, contain 18000 numbers, for +2 runs * 200 tries * 3 pages * 15 stages.
    • +Group and sort times. The time one stage of processing +takes is given by the difference of two time adjacent entries. This +defines stage00 to stage13; I keep the total time in stage14. This +is done by the Tcl script +dev0103-001:/home/brech/prog/tcl/timing.tcl, which +generates the directories stage00 to +stage14 and the ten files +{0,1,2}-{never,normal,always}, +and t_max in each of them. Each of the former files +contains the 2*200 samples, ordered for graphing. +

      III. Presentation

      Color Codes

      The different experiments are color coded as follows.

      + + + + + + + + + +
      nevernormalalways
      chain-frac-0   
      chain-frac-1   
      chain-frac-2   
      +(They lie in the isoluminant plane in the middle of the RGB color +space.) +

      Presenting Distributions

      A number of statistic measures can summarize an ensemble of +data, in our case, the 400 timings. The average is affected by +outliers; the median is much more robust. Maybe some dispersion +measure would be of interest, too. Some people plot histograms, but +that approach is frought with its own problems. I chose to use all +the data and plot estimated distribution functions. Our random +variable being time T, its distribution function is +defined as

      +FT +(t) = +P[T <= t]  + .
      +It is sometimes referred to as cumulative density function. Its +deriviative p(t) = +F'(t) is the distribution density of the +random variable T, which histograms approximate. +

      The curve always increases monotonically from 0 to 1. In case of +a normal distribution, you get the erf shape; for a uniform +distribution it is a ramp. This form of presentation throws away no +information, and it shows all about the distribution of a single +variable. I am pretty sure the times that different stages of one +request take are statistically dependent, but I don't consider that +for the time being. The median is the abscissa t at +which the ordinate F(t)=1/2.

      The curves for all nine experiments are drawn in the same graph +for comparison. Note that the abscissa is scaled very differently +for various stages.

      Steps

        +
      • I scp the stage?? directories to my linux box, where gnuplot is +installed. Another approach would be to install gnuplot on the +machine that runs the server, i.e., dev0103-001.
      • The csh script plot-all goes into each stage?? subdirectory and +runs the gnuplot script distrib.gplt: +
        +   #! /bin/csh
+   foreach i (stage[01][0-9])
+     (cd $i; gnuplot ../distrib.gplt > $i.gif)
+     echo $i done.
+   end
+        
+
        +
        • +

      IV. Results

        +
      • +graphs from dev0103-001, +approximately acs-4-0-beta-R20001001.
      • +graphs from reusia.boston, +approximately acs-4-0-beta-2-R20001009.
      • +graphs from reusia.boston, from ACS +3.4.6 tarball. This comparison is not completely fair.
        • +

      V. Conclusion

      Currently, the template system doesn't meet the performance +requirement.

      Earlier on dev0103-001, templated pages loaded fast enough. +Although the processing stage seems to a lot be more than 10% +slower, the overall performance is rather increased than slowed by +templating.

      On reusia.boston, we had a much better performance of the +request processor. The processing times of the pages proper (stage +10 before, 11 now) didn't change much; we just got clearer results. +The total processing time of Tcl-only pages is around 155ms, while +templated pages take around 220ms, that is 42% longer (or Tcl-only +pages take 30% less).

      Relative times depend on the other components of the pipeline. +The difference of 65ms is a large percentage of a total serving +time of 155ms; when other parts of the system (e.g., the request +processor) were slower, this wasn't that noticeable.

      For ACS 3.4, Tcl-only chain-frac-0 pages take 115ms, where the +templated versisons are much slower, 320ms for chain-frac-1 and 340 +for -2.

      VI. Further Work

      Tune templating in ACS 4.0.

      Christian +Brechbühler
      +Last modified: Tue Oct 17 20:11:49 EDT 2000 +
      • +
    + Index: openacs-4/packages/acs-templating/www/doc/todo.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/todo.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/todo.adp 17 Sep 2014 19:06:35 -0000 1.1.2.1 @@ -0,0 +1,12 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Data Source API

    We need to resolve how onerow and multirow data sources are +represented internally, and plug in the proper API. I originally +used ns_sets to represent rows in a data source (and continue to do +so for the time being). jsalz instead uses arrays and lists to +represent rows. Task: look at jsalz's data source code.

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/cm_widget.adp 17 Sep 2014 19:06:35 -0000 1.1.2.1 @@ -0,0 +1,29 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace cm_widget

    Procedures associated with custom metadata widgets for +basic CR content types

    Method Summary

    +Listing of public methods:
    The namespace cm_widget currently contains no public +methods.

    Method Detail

    +* indicates required

    +Private Methods:
    +

    + +
    +cm_widget::validate_description
      by Michael Pih +
    +
    Make sure that description <= 4000 +bytes
    +Parameters: + +
    +value* +The submitted value of the description form +element
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/cms_rel.adp 17 Sep 2014 19:06:35 -0000 1.1.2.1 @@ -0,0 +1,44 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace cms_rel

    Procedures for managing relation items and child +items

    Method Summary

    +Listing of public methods:
    +cms_rel::sort_child_item_order
    cms_rel::sort_related_item_order
    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    +cms_rel::sort_child_item_order
      by Michael Pih +
    +
    Resort the child items order for a given content item, +ensuring that order_n is unique for an item_id. Chooses new order +based on the old order_n and then rel_id (the order the item was +related)
    +Parameters: + +
    +item_id* +The item for which to resort child items
    +
    +
    + +
    +cms_rel::sort_related_item_order
      by Michael Pih +
    +
    Resort the related items order for a given content +item, ensuring that order_n is unique for an item_id. Chooses new +order based on the old order_n and then rel_id (the order the item +was related)
    +Parameters: + +
    +item_id* +The item for which to resort related items
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content.adp 17 Sep 2014 19:06:35 -0000 1.1.2.1 @@ -0,0 +1,649 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace content

    Procedures for generating and processing content +content creation and editing forms..

    Method Summary

    +Listing of public methods:
    +content::add_attribute_element
    content::add_attribute_elements
    content::add_basic_revision
    content::add_child_relation_element
    content::add_content
    content::add_content_element
    content::add_revision
    content::add_revision_form
    content::copy_content
    content::get_attribute_enum_values
    content::get_latest_revision
    content::get_object_id
    content::new_item
    content::new_item_form
    content::validate_name
    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    content::add_attribute_element
    +
    Add a form element (possibly a compound widget) to an +ATS form object. for entering or editing an attribute +value.
    +Parameters: + + + + + + + + + +
    +form_name* +The name of the ATS form object to which the +element should be added.
    +content_type* +The content type keyword to which this attribute +belongs.
    +attribute* +The name of the attribute, as represented in the +attribute_name column of the acs_attributes table.
    +attribute_data* +Optional nested list of parameter data for the the +attribute (generated by get_attribute_params).
    +
    +
    + +
    content::add_attribute_elements
    +
    Add form elements to an ATS form object for all +attributes of a content type.
    +
    +Parameters: + + + + + + + +
    +form_name* +The name of the ATS form object to which objects +should be added.
    +content_type* +The content type keyword for which attribute +widgets should be added.
    +revision_id* +The revision from which default values should be +queried
    +
    Returns:
    The list of attributes that were added.
    +
    +
    + +
    content::add_basic_revision
    +
    Create a basic new revision using the content_revision +PL/SQL API.
    +
    +Parameters: + + + + + + + +
    +item_id* +
    +revision_id* +
    +title* +
    +
    Options:
    + + + + + + + + + +
    description
    mime_type
    text
    tmpfile
    +
    +
    + +
    content::add_child_relation_element
    +
    Add a select box listing all valid child relation tags. +The form must contain a parent_id element and a content_type +element. If the elements do not exist, or if there are no valid +relation tags, this proc does nothing.
    +
    +Parameters: + +
    +form_name* +The name of the form
    +
    Options:
    + + + + + +
    section +none If present, creates a new form section +for the element.
    label{Child relation tag} The label for the +element
    +
    +
    + +
    content::add_content
    +
    Update the BLOB column of a revision with content +submitted in a form
    +Parameters: + +
    +revision_id* +The object ID of the revision to be updated.
    +
    +
    + +
    content::add_content_element
    +
    Adds a content input element to an ATS form +object.
    +Parameters: + + + + + +
    +form_name* +The name of the form to which the object should be +added.
    +content_method* +One of no_content, text_entry or file_upload
    +
    +
    + +
    content::add_revision
    +
    Create a new revision for an existing item based on a +valid form submission. Queries for attribute names and inserts a +row into the attribute input view for the appropriate content type. +Inserts the contents of a file into the content column of the +cr_revisions table for the revision as well.
    +Parameters: + + + + + +
    +form_name* +Name of the form from which to obtain attribute +values. The form should include an item_id and revision_id.
    +tmpfile* +Name of the temporary file containing the content +to upload.
    +
    +
    + +
    content::add_revision_form
    +
    Adds elements to an ATS form object for adding a +revision to an existing item. If the item already exists, element +values default a previous revision (the latest one by default). If +the form does not already exist, creates the form object and sets +its enctype to multipart/form-data to allow for text entries +greater than 4000 characters.
    +
    Options:
    + + + + + + + + + + + + + + + +
    form_nameThe name of the ATS form object. Defaults to { +new_item} .
    content_typeThe content_type of the item. Defaults to { +content_revision} .
    content_methodThe method to use for uploading the content body. +If the content type is text, defaults to text entry, otherwise +defaults to file upload.
    item_idThe item ID of the revision. Defaults to null +(item_id must be set by the calling code).
    revision_idThe revision ID from which to draw default values. +Defaults to the latest revision
    attributesA list of attribute names for which to create form +elements.
    actionThe URL to which the form should redirect +following a successful form submission.
    +
    +
    + +
    content::copy_content
    +
    Update the BLOB column of one revision with the content +of another revision
    +Parameters: + + + + + +
    +revision_id_src* +The object ID of the revision with the content to +be copied.
    +revision_id_dest* +The object ID of the revision to be updated. +copied.
    +
    +
    + +
    content::get_attribute_enum_values
    +
    Returns a list of { pretty_name enum_value } for an +attribute of datatype enumeration.
    +Parameters: + +
    +attribute_id* +The primary key of the attribute as in the +attribute_id column of the acs_attributes table.
    +
    +
    + +
    content::get_latest_revision
    +
    Get the ID of the latest revision for the specified +content item.
    +Parameters: + +
    +item_id* +The ID of the content item.
    +
    +
    + +
    content::get_object_id
    Grab an object ID for creating a new ACS +object.
    + +
    content::new_item
    +
    Create a new item, including the initial revision, +based on a valid form submission.
    +
    +Parameters: + + + + + +
    +form_name* +Name of the form from which to obtain item +attributes, as well as attributes of the initial revision. The form +should include an item_id, name and revision_id.
    +tmpfile* +Name of the temporary file containing the content +to upload for the initial revision.
    +
    See Also:
    add_revision -
    +
    +
    +
    + +
    content::new_item_form
    +
    Adds elements to an ATS form object for creating an +item and its initial revision. If the form does not already exist, +creates the form object and sets its enctype to multipart/form-data +to allow for text entries greater than 4000 +characters.
    +
    Options:
    + + + + + + + + + + + + + + + +
    form_nameThe name of the ATS form object. Defaults to { +new_item} .
    content_typeThe content_type of the item. Defaults to { +content_revision} .
    content_methodThe method to use for uploading the content body. +Valid values are { no_content} , { text_entry} , and { file_upload} +. If the content type allows text, defaults to text entry, +otherwise defaults to file upload.
    parent_idThe item ID of the parent. Defaults to null +(Parent is the root folder).
    nameThe default name of the item. Default is an empty +string (User must supply name).
    attributesA list of attribute names for which to create form +elements.
    actionThe URL to which the form should redirect +following a successful form submission.
    +
    +
    + +
    content::validate_name
    +
    Make sure that name is unique for the +folder
    +
    +Parameters: + +
    +form_name* +The name of the form (containing name and +parent_id)
    +
    Returns:
    0 if there are items with the same name, 1 otherwise
    +
    +

    +Private Methods:
    +

    + +
    content::add_revision_dml
    +
    Perform the DML to insert a revision into the +appropriate input view.
    +
    +Parameters: + + + + + + + + + +
    +statement* +The DML for the insert statement, specifying a +bind variable for each column value.
    +bind_vars* +An ns_set containing the values for all bind +variables.
    +tmpfile* +The server-side name of the file containing the +body of the revision to upload into the content BLOB column of +cr_revisions.
    +filename* +The client-side name of the file containing the +body of the revision to upload into the content BLOB column of +cr_revisions
    +
    See Also:
    add_revision -
    +
    +
    +
    + +
    content::attribute_insert_statement
    +
    Prepare the insert statement into the attribute input +view for a new revision (see the content repository documentation +for details about the view).
    +Parameters: + + + + + + + + + +
    +content_type* +The content type of the item for which a new +revision is being prepared.
    +table_name* +The storage table of the content type.
    +bind_vars* +The name of an ns_set in which to store the +attribute values for the revision. (Typically duplicates the +contents of {[ns_getform].}
    +form_name* +The name of the ATS form object used to process +the submission.
    +
    +
    + +
    content::get_attribute_params
    +
    Query for parameters associated with a particular +attribute
    +Parameters: + + + + + +
    +content_type* +The content type keyword to which this attribute +belongs.
    +attribute_name* +The name of the attribute, as represented in the +attribute_name column of the acs_attributes table.
    +
    +
    + +
    content::get_attributes
    +
    Returns columns from the acs_attributes table for all +attributes associated with a content type.
    +Parameters: + + + + + +
    +content_type* +The name of the content type (ACS Object Type) for +which to obtain the list of attributes.
    +args* +Names of columns to query. If no columns are +specified, returns a simple list of attribute names.
    +
    +
    + +
    content::get_default_content_method
    +
    Gets the content input method most appropriate for an +content type, based on the MIME types that are registered for that +content type.
    +Parameters: + +
    +content_type* +The content type for which an input method is +needed.
    +
    +
    + +
    content::get_sql_value
    +
    Return the sql statement for a column value in an +insert or update statement, using a bind variable for the actual +value and wrapping it in a conversion function where +appropriate.
    +Parameters: + + + + + +
    +name* +The name of the column and bind variable (they +should be the same).
    +datatype* +The datatype of the column.
    +
    +
    + +
    content::get_type_attribute_params
    +
    Query for attribute form metadata
    +
    +Parameters: + +
    +args* +Any number of object types
    +
    Returns:
    A list of attribute parameters nested by object_type, +attribute_name and the is_html flag. For attributes with no +parameters, there is a single entry with is_html as null.
    +
    +
    + +
    content::get_type_info
    +
    Return specified columns from the acs_object_types +table.
    +Parameters: + + + + + + + +
    +object_type* +Object type key for which info is required.
    +ref* +If no further arguments, name of the column value +to return. If further arguments are specified, name of the array in +which to store info in the calling
    +args* +Column names to query.
    +
    +
    + +
    content::get_widget_param_value
    +
    Utility procedure to return the value of a widget +parameter
    +Parameters: + + + + + +
    +array_ref* +The name of an array in the calling frame +containing parameter data selected from the form metadata.
    +content_type* +The current content {type;} defaults to +content_revision
    +
    +
    + +
    content::prepare_content_file
    +
    Looks for an element named { content} in a form and +prepares a temporarily file in UTF-8 for uploading to the content +repository. Checks for a query variable named { content.tmpfile} to +distinguish between file uploads and text entry. If the type of the +file is text, then ensures that is in UTF-8. Does nothing if the +uploaded file is in binary format.
    +
    +Parameters: + +
    +form_name* +The name of the form object in which content was +submitted.
    +
    Returns:
    The path of the temporary file containing the content, or an +empty string if the form does not include a content element or the +value of the element is null.
    +
    +
    + +
    content::set_attribute_values
    +
    Set the default values for attribute elements in ATS +form object based on a previous revision
    +Parameters: + + + + + + + + + +
    +form_name* +The name of the ATS form object containing the +attribute elements.
    +content_type* +The type of item being revised in the form.
    +revision_id* +The revision ID from where to get the default +values
    +attributes* +The list of attributes whose values should be +set.
    +
    +
    + +
    content::set_content_value
    +
    Set the default value for the content text area in an +ATS form object based on a previous revision
    +Parameters: + + + + + +
    +form_name* +The name of the ATS form object containing the +content element.
    +revision_id* +The revision ID of the content to revise
    +
    +
    + +
    content::string_to_file
    +
    Write a string in UTF-8 encoding to of temp file so it +can be uploaded into a BLOB (which is blind to character +encodings). Returns the name of the temp file.
    +Parameters: + +
    +s* +The string to write to the file.
    +
    +
    + +
    content::update_content_from_file
    +
    Update the BLOB column of a revision with the contents +of a file
    +Parameters: + + + + + +
    +revision_id* +The object ID of the revision to update.
    +tmpfile* +The name of a temporary file containing the +content. The file is deleted following the update.
    +
    +
    + +
    content::upload_content
    +
    Inserts content into the database from an uploaded +file. Does automatic mime_type updating Parses text/html content +and removes tags
    +Parameters: + + + + + + + + + +
    +db* +A db handle
    +revision_id* +The revision to which the content belongs
    +tmpfile* +The server-side name of the file containing the +body of the revision to upload into the content BLOB column of +cr_revisions.
    +filename* +The client-side name of the file containing the +body of the revision to upload into the content BLOB column of +cr_revisions
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content_add.adp 17 Sep 2014 19:06:35 -0000 1.1.2.1 @@ -0,0 +1,36 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace content_add

    Procedures regarding content methods

    Method Summary

    +Listing of public methods:
    +content_add::content_method_html
    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    +content_add::content_method_html
      by Michael Pih +
    +
    Generates HTML stub for revision content method choices +for a content item
    +Parameters: + + + + + + + +
    +db* +A database handle
    +content_type* +The content type of the item
    +item_id* +The item id
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/content_method.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/content_method.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/content_method.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,87 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace content_method

    Procedures regarding content methods

    Method Summary

    +Listing of public methods:
    +content_method::flush_content_methods_cache
    content_method::get_content_methods
    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    +content_method::flush_content_methods_cache
      by Michael Pih +
    +
    Flushes the cache for content_method_types for a given +content type. If no content type is specified, the entire +content_method_types cache is flushed
    +Parameters: + +
    +content_type* +The content type, default null
    +
    +
    + +
    +content_method::get_content_methods
      by Michael Pih +
    +
    Returns a list of content_methods that are associated +with a content type, first checking for a default method, then for +registered content methods, and then for all content +methods
    +
    +Parameters: + +
    +content_type* +The content type
    +
    Returns:
    A list of content methods or a list of label-value pairs of +content methods if the " -get_labels" option is specified
    Options:
    + +
    get_labelsInstead of a list of content methods, return a +list of label-value pairs of associated content methods.
    See Also:
    content_method::get_content_method_options, +content_method::text_entry_filter_sql -
    +
    +
    +

    +Private Methods:
    +

    + +
    +content_method::get_content_method_options
      by Michael Pih +
    +
    Returns a list of label, content_method pairs that are +associated with a content type, first checking for a default +method, then for registered content methods, and then for all +content methods
    +
    +Parameters: + +
    +content_type* +The content type
    +
    Returns:
    A list of label, value pairs of content methods
    See Also:
    content_method::get_content_methods, +content_method::text_entry_filter_sql -
    +
    +
    +
    + +
    +content_method::text_entry_filter_sql
      by Michael Pih +
    +
    Generate a SQL stub that filters out the text_entry +content method
    +
    +Parameters: + +
    +content_type* +
    +
    Returns:
    SQL stub that possibly filters out the text_entry content +method
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/doc.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/doc.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/doc.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,81 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace doc

    Method Summary

    +Listing of public methods:
    The namespace doc currently contains no public +methods.

    Method Detail

    +* indicates required

    +Private Methods:
    +

    + +
    +
      by simon +
    +
    called by parse_file, this procedure is given the body +of text between two namespace markers in a tcl library file and +parses out procedure source and comments
    +Parameters: + +
    +text_lines* +namespace text body
    +
    +
    + +
    Parse API documentation from a Tcl page API +documentation is parsed as follows: Document is scanned until a +\@namespace directive is encountered. The remainder of the file is +scanned for \@private or \@public directives. When one of these +directives is encountered, the file is scanned up to a proc +declaration and the text in between is parsed as documentation for +a single procedure. The text between the initial \@private or +\@public directive and the next directive is considered a general +comment on the procedure Valid directives in a procedure doc +include: - \@author - \@param (for hard parameters) - \@see (should +have the form namespace::procedure. A reference to an entire +namespace should be namespace::. By convention the API for each +namespace should be in a file of the same name, so that a link can +be generated automatically). - \@option (for switches such as -foo) +- \@return
    + +
    +
    called by parse_comment_text
    +Parameters: + +
    +comment_text* +this should include the source text
    +
    +
    + +
    +
    called by parse_namespace
    +Parameters: + + + + + +
    +comment_text* +body of comment text to be parsed through
    +source_text* +source text of the procedure
    +
    +
    + +
    +
    takes the absolute path of the tcl library directory +and parses through it
    +
    Returns:
    a long lists of lists of lists, each list element contains a +three-element list of the format { {info} {public procedures +listing } {private procedures listing} }
    See Also:
    namespace - util
    +
    proc - doc::parse_file
    template::util::comment_text_normalize
    +
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/doc__util.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/doc__util.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/doc__util.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,95 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace doc::util

    Method Summary

    +Listing of public methods:
    The namespace doc::util currently contains no public +methods.

    Method Detail

    +* indicates required

    +Private Methods:
    +

    + +
    set split_name +$see_name doc::util::text_divider split_name :: set name_length +[llength $split_name] set see_namespace [join [lrange $split_name 0 +[expr $name_length - 2]] \"\"] set url \"[doc::util::dbl_colon_fix +$see_namespace].html#[set see_name]\"
    procedure to deal with \@see comments
    + +
    +
    divides a string variable into a list of strings, all +but the first element beginning with the indicated text {marker;} +the first element of the created list contains all of the string +preceding the first occurrence of the text marker
    +
    +Parameters: + + + + + +
    +text* +name of string variable (not the string value +itself)
    +marker* +the string indicating text division
    +
    See Also:
    proc - doc::util::find_marker_indices
    +
    +
    +
    + +
    escapes out all square brackets
    + +
    +
    given a body of text and a text marker, returns a list +of position indices for each occurrence of the text +marker
    +
    +Parameters: + + + + + +
    +text* +body of text to be searched through
    +marker* +the text-divider mark
    +
    Returns:
    list of indices of the position immediately preceding each +occurrence of the text marker; if there are no occurrences of the +text marker, returns a zero-element list
    See Also:
    namespace - doc
    +
    proc - doc::parse_file
    doc::parse_namespace
    doc::util::text_divider
    +
    +
    +
    + +
    puts a space after all closing curly brackets, does not +add a space when brackets are already followed by a +space
    + +
    +
    used to sort the see list, which has structure {[name} +name type type url url \]
    +Parameters: + + + + + +
    +element1* +the first of the two list elements to be +compared
    +element2* +the second of the two elements to be compared
    +
    +
    + +
    + +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/form.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/form.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/form.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,282 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace form

    Commands for managing dynamic templated +forms.

    Method Summary

    +Listing of public methods:
    +










    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    +
    Convenience procedure to set individual values of a +form (useful for simple update forms). Typical usage is to query a +onerow data source from database and pass the resulting array +reference to set_values for setting default values in an update +form.
    +Parameters: + + + + + +
    +id* +The form identifier
    +array_ref* +The name of a local array variable whose keys +correspond to element identifiers in the form
    +
    +
    + +
    +
    Determine whether a form exists by checking for its +data structures.
    +
    +Parameters: + +
    +id* +The ID of an ATS form object.
    +
    Returns:
    1 if a form with the specified ID exists. 0 if it does +not.
    +
    +
    + +
    +
    Generates hidden input tags for all values in a form +submission. Typically used to create a confirmation page following +an initial submission.
    +
    Returns:
    A string containing hidden input tags for inclusion in a +form.
    +
    +
    + +
    +
    Initialize the data structures for a form.
    +
    +Parameters: + +
    +id* +A keyword identifier for the form, such as { +add_user} or { edit_item} . The ID must be unique in the context of +a single page.
    +
    Options:
    + + + + + + + +
    methodThe standard METHOD attribute to specify in the +HTML FORM tag at the beginning of the rendered form. Defaults to +POST.
    htmlA list of additional name-value attribute pairs to +include in the HTML FORM tag at the beginning of the rendered form. +Common attributes include JavaScript event handlers and multipart +form encoding. For example, { -html { enctype multipart/form-data +onSubmit validate() } }
    elementsA block of element specifications.
    +
    +
    + +
    +
    Return a list which represents the result of getting +combined values from multiple form elements
    +Parameters: + + + + + + + +
    +id* +The form identifier
    +args* +A list of element identifiers. Each identifier may +be a regexp. For example, form get_combined_values { foo.*} will +combine the values of all elements starting with { foo}
    +return* +The combined list of values
    +
    +
    + +
    +
    Return the number of elements in a form
    +Parameters: + +
    +id* +The form identifier
    +
    +
    + +
    +
    Return true if a submission in progress. The submission +may or may not be valid.
    +
    +Parameters: + +
    +id* +The form identifier
    +
    Returns:
    1 if true or 0 if false
    +
    +
    + +
    +
    Return true if preparing a form for an initial request +(as opposed to repreparing a form that is returned to the user due +to validation problems). This command is used to conditionally set +default values for form elements.
    +
    +Parameters: + +
    +id* +The form identifier
    +
    Returns:
    1 if true or 0 if false
    +
    +
    + +
    +
    Return true if submission in progress and submission +was valid. Typically used to conditionally execute DML and redirect +to the next page, as opposed to returning the form back to the user +to report validation errors.
    +
    +Parameters: + +
    +id* +The form identifier
    +
    Returns:
    1 if true or 0 if false
    +
    +
    + +
    +
    Set local variables for form variables (assume they are +all single values). Typically used when processing the form +submission to prepare for DML or other type of +transaction.
    +Parameters: + + + + + +
    +id* +The form identifier
    +args* +A list of element identifiers. If the list is +empty, retreive all form elements
    +
    +
    + +
    +
    Set the name of the current section of the form. A form +may be divided into any number of sections for layout purposes. +Elements are tagged with the current section name as they are added +to the form. A form style template may insert a divider in the form +whenever the section name changes.
    +Parameters: + + + + + +
    +id* +The form identifier.
    +section* +The name of the current section.
    +
    +

    +Private Methods:
    +

    + +
    +
    Auto-generate the template for a form
    +
    +Parameters: + + + + + +
    +id* +The form identifier
    +style* +The style template to use when generating the +form. Form style templates must be placed in the forms subdirectory +of the ATS resources directory.
    +
    Returns:
    A string containing a template for the body of the form.
    +
    +
    + +
    Helper procedure used to access the basic data +structures of a form object. Called by several of the form +commands.
    + +
    +
    Iterates over all declared elements, checking for +hidden widgets and rendering those that have not been rendered yet. +Called after rendering a custom form template as a debugging +aid.
    +Parameters: + +
    +id* +The form identifier
    +
    +
    + +
    +
    Render the HTML FORM tag along with a hidden element +that identifies the form object.
    +
    +Parameters: + + + + + +
    +id* +The form identifier
    +tag_attributes* +A name-value list of special attributes to add to +the FORM tag, such as JavaScript event handlers.
    +
    Returns:
    A string containing the rendered tags.
    +
    +
    + +
    +
    Render the finished HTML output for a dynamic +form.
    +
    +Parameters: + + + + + +
    +id* +The form identifier
    +style* +The style template to use when generating the +form. Form style templates must be placed in the forms subdirectory +of the ATS resources directory.
    +
    Returns:
    A string containing the HTML for the body of the form.
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,332 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace item

    The item commands allow easy access to properties of +the content_item object. In the future, a unified API for caching +item properties will be developed here.

    Also see:

    +
    namespace
    publish
    +

    Method Summary

    +Listing of public methods:
    +item::content_is_null
    item::content_methods_by_type
    item::get_best_revision
    item::get_content_type
    item::get_extended_url
    item::get_id
    item::get_item_from_revision
    item::get_live_revision
    item::get_mime_info
    item::get_publish_status
    item::get_revision_content
    item::get_template_id
    item::get_template_url
    item::get_title
    item::get_url
    item::is_publishable
    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    item::content_is_null
    +
    Determines if the content for the revision is null (not +mereley zero-length)
    +
    +Parameters: + +
    +revision_id* +The revision id
    +
    Returns:
    1 if the content is null, 0 otherwise
    +
    +
    + +
    item::content_methods_by_type
    +
    Determines all the valid content methods for +instantiating a content type. Possible choices are text_entry, +file_upload, no_content and xml_import. Currently, this proc merely +removes the text_entry method if the item does not have a text mime +type registered to it. In the future, a more sophisticated +mechanism will be implemented.
    +
    +Parameters: + +
    +content_type* +The content type
    +
    Returns:
    A Tcl list of all possible content methods
    Options:
    + +
    get_labelsReturn not just a list of types, but a list of +name-value pairs, as in the -options ATS switch for form +widgets
    +
    +
    + +
    item::get_best_revision
    +
    Attempts to retrieve the live revision for the item. If +no live revision exists, attempts to retrieve the latest revision. +If the item has no revisions, returns an empty string.
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    The best revision id for the item, or an empty string if no +revisions exist
    See Also:
    proc - item::get_item_from_revision
    item::get_live_revision
    +
    +
    +
    + +
    item::get_content_type
    +
    Retrieves the content type of tyhe item. If the item +does not exist, returns an empty string.
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    The content type of the item, or an empty string if no such +item exists
    +
    +
    + +
    item::get_extended_url
    +
    Retrieves the relative URL of the item with a file +extension based on the item's mime_type (Example: { +/foo/bar/baz.html} ).
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    The relative URL of the item with the appropriate file +extension or an empty string on failure
    Options:
    + + + + + +
    template_extensionSignifies that the file extension should be +retrieved using the mime_type of the template assigned to the item, +not from the item itself. The live revision of the template is +used. If there is no template which could be used to render the +item, or if the template has no live revision, the extension +defaults to { .html}
    revision_id +default the live revision; Specifies the +revision_id which will be used to retrieve the item's mime_type. +This option is ignored if the -template_extension option is +specified.
    See Also:
    proc - item::get_mime_info
    item::get_template_id
    item::get_url
    +
    +
    +
    + +
    item::get_id
    +
    Looks up the URL and gets the item id at that URL, if +any.
    +
    +Parameters: + + + + + +
    +url* +The URL
    root_folder +default The Sitemap; The ID of the root +folder to use for resolving the URL
    +
    Returns:
    The item ID of the item at that URL, or the empty string on +failure
    See Also:
    proc - item::get_url
    +
    +
    +
    + +
    item::get_item_from_revision
    +
    Gets the item_id of the item to which the revision +belongs.
    +
    +Parameters: + +
    +revision_id* +The revision id
    +
    Returns:
    The item_id of the item to which this revision belongs
    See Also:
    proc - item::get_best_revision
    item::get_live_revision
    +
    +
    +
    + +
    item::get_live_revision
    +
    Retrieves the live revision for the item. If the item +has no live revision, returns an empty string.
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    The live revision id for the item, or an empty string if no +live revision exists
    See Also:
    proc - item::get_best_revision
    item::get_item_from_revision
    +
    +
    +
    + +
    item::get_mime_info
    +
    Creates a onerow datasource in the calling frame which +holds the mime_type and file_extension of the specified revision. +If the revision does not exist, does not create the +datasource.
    +
    +Parameters: + + + + + +
    +revision_id* +The revision id
    datasource_ref +default mime_info; The name of the +datasource to be created. The datasource will have two columns, +mime_type and file_extension. return 1 (one) if the revision +exists, 0 (zero) otherwise.
    +
    See Also:
    proc - item::get_extended_url
    +
    +
    +
    + +
    item::get_publish_status
    +
    Get the publish status of the item. The publish status +will be one of the following: +
      +
    • +production - The item is still in production. The +workflow (if any) is not finished, and the item has no live +revision.
    • +ready - The item is ready for publishing
    • +live - The item has been published
    • +expired - The item has been published in the past, but +its publication has expired
      • +
    +
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    The publish status of the item, or the empty string on +failure
    See Also:
    proc - item::is_publishable
    +
    +
    +
    + +
    item::get_revision_content
    +
    Create a onerow datasource called content in the +calling frame which contains all attributes for the revision +(including inherited ones). +

    The datasource will contain a column called { text} , +representing the main content (blob) of the revision, but only if +the revision has a textual mime-type.

    +
    +
    +Parameters: + +
    +revision_id* +The revision whose attributes are to be +retrieved
    +
    Returns:
    1 on success (and create a content array in the calling frame), +0 on failure
    Options:
    + +
    item_id +defaultauto-generated; The item_id +of the corresponding item.
    See Also:
    proc - item::get_content_type
    item::get_mime_info
    +
    +
    +
    + +
    item::get_template_id
    +
    Retrieves the template which can be used to render the +item. If there is a template registered directly to the item, +returns the id of that template. Otherwise, returns the id of the +default template registered to the item's content_type. Returns an +empty string on failure.
    +
    +Parameters: + + + + + +
    +item_id* +The item id
    context +default 'public'; The context in which the +template will be used.
    +
    Returns:
    The template_id of the template which can be used to render the +item, or an empty string on failure
    See Also:
    proc - item::get_template_url
    +
    +
    +
    + +
    item::get_template_url
    +
    Retrieves the relative URL of the template which can be +used to render the item. The URL is relative to the TemplateRoot as +it is specified in the ini file.
    +
    +Parameters: + + + + + +
    +item_id* +The item id
    context +default 'public'; The context in which the +template will be used.
    +
    Returns:
    The template_id of the template which can be used to render the +item, or an empty string on failure
    See Also:
    proc - item::get_template_id
    +
    +
    +
    + +
    item::get_title
    +
    Get the title for the item. If a live revision for the +item exists, use the live revision. Otherwise, use the latest +revision.
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    The title of the item
    See Also:
    proc - item::get_best_revision
    +
    +
    +
    + +
    item::get_url
    +
    Retrieves the relative URL stub to th item. The URL is +relative to the page root, and has no extension (Example: { +/foo/bar/baz} ).
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    The relative URL to the item, or an empty string on +failure
    See Also:
    proc - item::get_extended_url
    +
    +
    +
    + +
    item::is_publishable
    +
    Determine if the item is publishable. The item is +publishable only if: +
      +
    • All child relations, as well as item relations, are satisfied +(according to min_n and max_n)
    • The workflow (if any) for the item is finished
      • +
    +
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    1 if the item is publishable, 0 otherwise
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/namespace-list.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/namespace-list.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/namespace-list.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,17 @@ + +{/doc/acs-templating {Templating}} {} + + + + +All Namespaces
      doc
    +  doc::util
    +  form
    +  request
    +  util
    +
    Regenerate +these pages. +

    If you have not regenerated these pages before, you may have to +reset permissions on all files to be written as well as your +/doc/acs-templating/TclDocs directory.

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/namespaces.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/namespaces.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/namespaces.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,24 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    ATS and CMS Tcl Procedure +Specifications

    + +
    Namespaces
    doc
    doc::util
    +form
    Commands for managing dynamic templated +forms.
    +
    +request
    The request commands provide a mechanism for managing +the query parameters to a page. The request is simply a special +instance of a form object, and is useful for the frequent cases +when data must be passed from page to page to determine display or +page flow, rather than perform a transaction based on user input +via a form. +

    See: form element +

    +
    +
    util
    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/pagination.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/pagination.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/pagination.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,80 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace pagination

    Procedures for paginating a datasource

    Method Summary

    +Listing of public methods:
    +pagination::get_total_pages
    pagination::page_number_links
    pagination::paginate_query
    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    +pagination::get_total_pages
      by Michael Pih +
    +
    Gets the number of pages returned by a query PRE: +requires {$sql}
    +Parameters: + +
    +db* +A database handle
    +
    +
    + +
    +pagination::page_number_links
      by Michael Pih +
    +
    Generate HTML for navigating pages of a +datasource
    +Parameters: + + + + + +
    +page* +The current page number
    +total_pages* +The total pages returned by the query
    +
    +
    + +
    +pagination::paginate_query
      by Michael Pih +
    +
    Paginates a query
    +Parameters: + + + + + +
    +sql* +The sql query to paginate
    +page* +The current page number
    +
    +

    +Private Methods:
    +

    + +
    pagination::get_rows_per_page
    Returns the number of rows per page
    + +
    +pagination::ns_set_to_url_vars
      by Michael Pih +
    +
    Converts an ns_set into a list of url +variables
    +Parameters: + +
    +set_id* +The set id
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/publish.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/publish.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/publish.adp 17 Sep 2014 19:06:36 -0000 1.1.2.1 @@ -0,0 +1,710 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace publish

    +  by Stanislav Freidin The procs in this namespace are +useful for publishing items, including items inside other items, +and writing items to the filesystem.

    Specifically, the content, child and +relation tags are defined here.

    Also see:

    +
    namespace
    item
    +

    Method Summary

    +Listing of public methods:
    +publish::get_html_body
    publish::get_mime_handler
    publish::get_page_root
    publish::get_publish_roots
    publish::get_template_root
    publish::handle_binary_file
    publish::item_include_tag
    publish::mkdirs
    publish::proc_exists
    publish::publish_revision
    publish::schedule_status_sweep
    publish::set_publish_status
    publish::unpublish_item
    publish::unschedule_status_sweep
    publish::write_content
    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    publish::get_html_body
    +
    Strip the {<body>} tags from the HTML, leaving +just the body itself. Useful for including templates in each +other.
    +
    +Parameters: + +
    +html* +The html to be processed
    +
    Returns:
    Everything between the <body> and the </body> tags +if they exist; the unchanged HTML if they do not
    +
    +
    + +
    publish::get_mime_handler
    +
    Return the name of a proc that should be used to render +items with the given mime-type. The mime type handlers should all +follow the naming convention +
    proc +publish::handle::mime_prefix::mime_suffix +
    +If the specific mime handler could not be found, +get_mime_handler looks for a generic procedure with the +name +
    proc +publish::handle::mime_prefix +
    +If the generic mime handler does not exist either, +get_mime_handler returns { }
    +
    +Parameters: + +
    +mime_type* +The full mime type, such as { text/html} or { +image/jpg}
    +
    Returns:
    The name of the proc which should be used to handle the +mime-type, or an empty string on failure.
    See Also:
    proc - publish::handle_item
    +
    +
    +
    + +
    publish::get_page_root
    +
    Get the page root. All items will be published to the +filesystem with their URLs relative to this root. The page root is +controlled by the PageRoot parameter in CMS. A relative path is +relative to {[ns_info} pageroot\] The default is {[ns_info} +pageroot\]
    +
    Returns:
    The page root
    See Also:
    proc - publish::get_publish_roots
    publish::get_template_root
    +
    +
    +
    + +
    publish::get_publish_roots
    +
    Get a list of all page roots to which files may be +published. The publish roots are controlled by the PublishRoots +parameter in CMS, which should be a space-separated list of all the +roots. Relative paths are relative to publish::get_page_root. The +default is {[list} {[publish::get_page_root]]}
    +
    Returns:
    A list of all the publish roots
    See Also:
    proc - publish::get_page_root
    publish::get_template_root
    +
    +
    +
    + +
    publish::get_template_root
    +
    Get the template root. All templates are assumed to +exist in the filesystem with their URLs relative to this root. The +page root is controlled by the TemplateRoot parameter in CMS. The +default is /web/yourserver/templates
    +
    Returns:
    The template root
    See Also:
    proc - content::get_template_root,
    +
    +
    +
    + +
    publish::handle_binary_file
    +
    Helper procedure for writing handlers for binary files. +It will write the blob of the item to the filesystem, but only if +-embed is specified. Then, it will attempt to merge the image with +its template.
    +This proc accepts exactly the same options a typical +handler.
    +
    +Parameters: + + + + + + + + + +
    +item_id* +The id of the item to handle
    +revision_id_ref* + +required The name of the variable in the +calling frame that will recieve the revision_id whose content blob +was written to the filesystem.
    +url_ref* +The name of the variable in the calling frame that +will recieve the relative URL of the file in the file system which +contains the content blob
    +error_ref* +The name of the variable in the calling frame that +will recieve an error message. If no error has ocurred, this +variable will be set to the empty string { }
    +
    Returns:
    The HTML resulting from merging the item with its template, or +" " if no template exists or the -no_merge flag was +specified
    Options:
    + + + + + + + +
    embedSignifies that the content should be embedded +directly in the parent item. -embed is required for +this proc, since it makes no sense to handle the binary file in any +other way.
    revision_id +default The live revision for the item; The +revision whose content is to be used
    no_mergeIf present, do NOT merge with the template, in +order to prevent infinite recursion in the {<content>} tag. +In this case, the proc will return the empty string { }
    See Also:
    proc - publish::handle::image
    +
    +
    +
    + +
    publish::item_include_tag
    +
    Create an include tag to include an item, in the form +
    include src=/foo/bar/baz item_id=item_id +param=value param=value ...
    +
    +
    +Parameters: + + + + + +
    +item_id* +The item id
    +extra_args* +{} A list of extra parameters to be passed to the +include tag, in form {name value name value ...}
    +
    Returns:
    The HTML for the include tag
    See Also:
    proc - item::item_url
    publish::html_args
    +
    +
    +
    + +
    publish::mkdirs
    +
    Create all the directories neccessary to save the +specified file
    +Parameters: + +
    +path* +The path to the file that is about to be +saved
    +
    +
    + +
    publish::proc_exists
    +
    Determine if a procedure exists in the given +namespace
    +
    +Parameters: + + + + + +
    +namespace_name* +The fully qualified namespace name, such as { +template::util}
    +proc_name* +The proc name, such as { is_nil}
    +
    Returns:
    1 if the proc exists in the given namespace, 0 otherwise
    +
    +
    + +
    publish::publish_revision
    +
    Render a revision for an item and write it to the +filesystem. The revision is always rendered with the +-embed option turned on.
    +
    +Parameters: + +
    +revision_id* +The revision id
    +
    Options:
    + +
    root_path +default All paths in the PublishPaths +parameter; Write the content to this path only.
    See Also:
    proc - item::get_extended_url
    publish::get_publish_paths
    publish::handle_item
    +
    +
    +
    + +
    publish::schedule_status_sweep
    +
    Schedule a proc to keep track of the publish status. +Resets the publish status to { expired} if the expiration date has +passed. Publishes the item and sets the publish status to { live} +if the current status is { ready} and the scheduled publication +time has passed.
    +
    +Parameters: + +
    interval +default 3600; The interval, in seconds, +between the sweeps of all items in the content repository. Lower +values increase the precision of the publishing/expiration dates +but decrease performance. If this parameter is not specified, the +value of the StatusSweepInterval parameter in the server's INI file +is used (if it exists).
    +
    See Also:
    proc - publish::set_publish_status
    publish::track_publish_status
    publish::unschedule_status_sweep
    +
    +
    +
    + +
    publish::set_publish_status
    +
    Set the publish status of the item. If the status is +live, publish the live revision of the item to the filesystem. +Otherwise, unpublish the item from the filesystem.
    +
    +Parameters: + + + + + + + + + +
    +db* +The database handle
    +item_id* +The item id
    +new_status* +The new publish status. Must be { production} , { +expired} , { ready} or { live}
    revision_id +default The live revision; The revision id +to be used when publishing the item to the filesystem.
    +
    See Also:
    proc - publish::publish_revision
    publish::unpublish_item
    +
    +
    +
    + +
    publish::unpublish_item
    +
    Delete files which were created by +publish_revision +
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Options:
    + + + + + +
    revision_id +default The live revision; The revision +which is to be used for determining the item filename
    root_path +default All paths in the PublishPaths +parameter; Write the content to this path only.
    See Also:
    proc - publish::publish_revision
    +
    +
    +
    + +
    publish::unschedule_status_sweep
    +
    Unschedule the proc which keeps track of the publish +status.
    +
    See Also:
    proc - publish::schedule_status_sweep
    +
    +
    +
    + +
    publish::write_content
    +
    Write the content (blob) of a revision into a binary +file in the filesystem. The file will be published at the relative +URL under each publish root listed under the PublishRoots parameter +in the server's INI file (the value returnded by +publish::get_page_root is used as the default). The file extension +will be based on the revision's mime-type.
    +For example, an revision whose mime-type is { image/jpeg} for an +item at { Sitemap/foo/bar} may be written as +/web/your_server_name/www/foo/bar.jpg
    +
    +Parameters: + +
    +revision_id* +The id of the revision to write
    +
    Returns:
    The relative URL of the file that was written, or an empty +string on failure
    Options:
    + + + + + + + +
    item_id +default The item_id of the revision; +Specifies the item to which this revision belongs (mereley for +optimization purposes)
    textIf specified, indicates that the content of the +revision is readable text (clob), not a binary file
    root_path +default All paths in the PublishPaths +parameter; Write the content to this path only.
    See Also:
    proc - content::get_content_value
    publish::get_publish_roots
    +
    +
    +

    +Private Methods:
    +

    + +
    publish::delete_multiple_files
    +
    Delete the specified URL from the filesystem, for all +revisions
    +
    +Parameters: + +
    +url* +Relative URL of the file to write
    +
    See Also:
    proc - publish::get_publish_roots
    publish::write_multiple_blobs
    publish::write_multiple_files
    +
    +
    +
    + +
    publish::foreach_publish_path
    +
    Execute some Tcl code for each root path in the +PublishRoots parameter
    +
    +Parameters: + + + + + + + +
    +url* +Relative URL to append to the roots
    +code* +Execute this code
    root_path +default The empty string; Use this root +path instead of the paths specified in the INI file
    +
    See Also:
    proc - publish::get_publish_roots
    +
    +
    +
    + +
    publish::get_main_item_id
    +
    Get the main item id from the top of the +stack
    +
    Returns:
    the main item id
    See Also:
    proc - publish::get_main_revision_id
    publish::pop_id
    publish::push_id
    +
    +
    +
    + +
    publish::get_main_revision_id
    +
    Get the main item revision from the top of the +stack
    +
    Returns:
    the main item id
    See Also:
    proc - publish::get_main_item_id
    publish::pop_id
    publish::push_id
    +
    +
    +
    + +
    publish::handle_item
    +
    Render an item either by looking it up in the the +temporary cache, or by using the appropriate mime handler. Once the +item is rendered, it is stored in the temporary cache under a key +which combines the item_id, any extra HTML parameters, and a flag +which specifies whether the item was merged with its template.
    +This proc takes the same arguments as the individual mime +handlers.
    +
    +Parameters: + + + + + +
    +item_id* +The id of the item to be rendered
    +context* +The context for the item (default public)
    +
    Returns:
    The rendered HTML for the item, or an empty string on +failure
    Options:
    + + + + + + + + + + + +
    revision_id +default The live revision; The revision +which is to be used when rendering the item
    no_mergeIndicates that the item should NOT be merged with +its template. This option is used to avoid infinite recursion.
    refreshRe-render the item even if it exists in the cache. +Use with caution - circular dependencies may cause infinite +recursion if this option is specified
    embedSignifies that the content should be statically +embedded directly in the HTML. If this option is not specified, the +item may be dynamically referenced, f.ex. using the +{<include>} tag
    htmlExtra HTML parameters to be passed to the item +handler, in format {name value name value ...}
    See Also:
    proc - publish::handle::image
    publish::handle::text
    publish::handle_binary_file
    +
    +
    +
    + +
    publish::html_args
    +
    Concatenate a list of name-value pairs as returned by +set_to_pairs into a list of { name=value} +pairs
    +
    +Parameters: + +
    +argv* +The list of name-value pairs
    +
    Returns:
    An HTML string in format " name=value name=value ..."
    See Also:
    proc - publish::set_to_pairs
    +
    +
    +
    + +
    publish::merge_with_template
    +
    Merge the item with its template and return the +resulting HTML. This proc is simlar to +content::init +
    +
    +Parameters: + +
    +item_id* +The item id
    +
    Returns:
    The rendered HTML, or the empty string on failure
    Options:
    + + + + + +
    revision_id +default The live revision; The revision +which is to be used when rendering the item
    htmlExtra HTML parameters to be passed to the ADP +parser, in format {name value name value ...}
    See Also:
    proc - publish::handle_item
    +
    +
    +
    + +
    publish::pop_id
    +
    Pop the item_id and the revision_id off the top of the +stack. Clear the temporary item cache if the stack becomes +empty.
    +
    Returns:
    The popped item id, or the empty string if the string is +already empty
    See Also:
    proc - publish::get_main_item_id
    publish::get_main_revision_id
    publish::push_id
    +
    +
    +
    + +
    publish::process_tag
    +
    Process a child or relation tag. This +is a helper proc for the tags, which acts as a wrapper for +render_subitem.
    +
    +Parameters: + + + + + +
    +relation_type* +Either child or relation +
    +params* +The ns_set id for extra HTML parameters
    +
    See Also:
    proc - publish::render_subitem
    +
    +
    +
    + +
    publish::push_id
    +
    Push an item id on top of stack. This proc is used to +store state between child, relation and +content tags.
    +
    +Parameters: + + + + + +
    +item_id* +The id to be put on stack
    revision_id +default { }; The id of the revision to use. +If missing, live revision will most likely be used
    +
    See Also:
    proc - publish::get_main_item_id
    publish::get_main_revision_id
    publish::pop_id
    +
    +
    +
    + +
    publish::render_subitem
    +
    Render a child/related item and return the resulting +HTML, stripping off the headers.
    +
    +Parameters: + + + + + + + + + + + + + + + + + +
    +main_item_id* +The id of the parent item
    +relation_type* +Either child or relation. +Determines which tables are searched for subitems.
    +relation_tag* +The relation tag to look for
    +index* +The relative index of the subitem. The subitem +with lowest order_n has index 1, the second lowest +order_n has index 2, and so on.
    +is_embed* +If { t} , the child item may be embedded directly +in the HTML. Otherwise, it may be dynamically included. The proc +does not process this parameter directly, but passes it to +handle_item +
    +extra_args* +Any additional HTML arguments to be used when +rendering the item, in form {name value name value ...}
    is_merge +default t; If { t} , +merge_with_template may be used to render the subitem. +Otherwise, merge_with_template should not be used, in +order to prevent infinite recursion.
    context +default public;
    +
    Returns:
    The rendered HTML for the child item
    See Also:
    proc - publish::handle_item
    publish::merge_with_template
    +
    +
    +
    + +
    publish::set_to_pairs
    +
    Convert an ns_set into a list of name-value pairs, in +form {name value name value ...}
    +
    +Parameters: + + + + + +
    +params* +The ns_set id
    +exclusion_list* +{} A list of keys to be ignored
    +
    Returns:
    A list of name-value pairs representing the data in the +ns_set
    +
    +
    + +
    publish::track_publish_status
    +
    Scheduled proc which keeps the publish status +updated
    +
    See Also:
    proc - publish::schedule_status_sweep
    +
    +
    +
    + +
    publish::write_multiple_blobs
    +
    Write the content of some revision to multiple +publishing roots.
    +
    +Parameters: + + + + + + + +
    +db* +A valid database handle
    +url* +Relative URL of the file to write
    +revision_id* +Write the blob for this revision
    +
    See Also:
    proc - publish::get_publish_roots
    publish::write_multiple_files
    +
    +
    +
    + +
    publish::write_multiple_files
    +
    Write a relative URL to the multiple publishing +roots.
    +
    +Parameters: + + + + + +
    +url* +Relative URL of the file to write
    +text* +A string of text to be written to the URL
    +
    See Also:
    proc - publish::get_publish_roots
    publish::write_multiple_blobs
    template::util::write_file
    +
    +
    +
    + +
    +
    Implements the child tag which renders a child +item. See the Developer Guide for more information.
    +The child tag format is +
    {<child} tag=tag index=n embed +{args>}
    +
    +Parameters: + +
    +params* +The ns_set id for extra HTML parameters
    +
    +
    + +
    +
    Implements the content tag which renders the +content of the current item. See the Developer Guide for more +information.
    +The content tag format is simply {<content>.} The +embed and no_merge parameters are implicit to the +tag.
    +Parameters: + +
    +params* +The ns_set id for extra HTML parameters
    +
    +
    + +
    +
    Implements the relation tag which renders a +related item. See the Developer Guide for more information.
    +The relation tag format is +
    {<relation} tag=tag index=n embed +{args>}
    +
    +Parameters: + +
    +params* +The ns_set id for extra HTML parameters
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/request.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/request.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/request.adp 17 Sep 2014 19:06:37 -0000 1.1.2.1 @@ -0,0 +1,122 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace request

    The request commands provide a mechanism for managing +the query parameters to a page. The request is simply a special +instance of a form object, and is useful for the frequent cases +when data must be passed from page to page to determine display or +page flow, rather than perform a transaction based on user input +via a form.

    Also see:

    +
    form
    element
    +

    Method Summary

    +Listing of public methods:
    +




    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    +
    Checks for any param errors. If errors are found, sets +the display template to the specified URL (a system-wide request +error page by default).
    +
    +Parameters: + +
    +url* +The URL of the template to use to display error +messages. The special value { self} may be used to indicate that +the template for the requested page itself will handle reporting +error conditions.
    +
    Returns:
    1 if no error conditions exist, 0 otherwise.
    +
    +
    + +
    +
    Create the request data structure. Typically called at +the beginning of the code for any page that accepts query +parameters.
    +
    Options:
    + +
    paramsA block of parameter declarations, separated by +newlines. Equivalent to calling set_param for each parameter, but +requiring slightly less typing.
    +
    +
    + +
    +
    Declares a query parameter as part of the page request. +Validates the values associated with the parameter, in the same +fashion as for form elements.
    +
    +Parameters: + +
    +name* +The name of the parameter to declare.
    +
    Options:
    + + + + + + + + + + + +
    nameThe name of parameter in the query (may be +different from the reference name).
    multipleA flag indicating that multiple values may be +specified for this parameter.
    datatypeThe name of a datatype for the element values. +Valid datatypes must have a validation procedure defined in the +template::data::validate namespace.
    optionalA flag indicating that no value is required for +this element. If a default value is specified, the default is used +instead.
    validateA list of custom validation blocks in the form { +name { expression } { message } \ name { expression } { message } +...} where name is a unique identifier for the validation step, +expression is a block to Tcl code that evaluates to 1 or 0, and +message is to be displayed to the user when the validation step +fails.
    See Also:
    element::create -
    +
    +
    +
    + +
    +
    Manually report request error(s) by setting error +messages and then calling is_valid to handle display. Useful for +conditions not tied to a single query parameter. The arguments to +the procedure may be any number of name-message +combinations.
    +Parameters: + + + + + +
    +name* +A unique identifier for the error condition, which +may be used for layout purposes.
    +msg* +The message text associated with the +condition.
    +
    +
    + +
    +
    Retrieves the value(s) of the specified +parameter.
    +
    +Parameters: + +
    +name* +The name of the parameter.
    +
    Returns:
    The value of the specified parameter.
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.adp 17 Sep 2014 19:06:37 -0000 1.1.2.1 @@ -0,0 +1,8 @@ + +{/doc/acs-templating {Templating}} {ArsDigita Templating System, Content Management Tcl +Procedure Specifications} +ArsDigita Templating System, Content Management Tcl +Procedure Specifications + + + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.html,v diff -u -N -r1.1.1.1 -r1.1.1.1.28.1 --- openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/tcl-procs.html 17 Sep 2014 19:06:37 -0000 1.1.1.1.28.1 @@ -2,10 +2,12 @@ ArsDigita Templating System, Content Management Tcl Procedure Specifications + + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/util.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/util.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/util.adp 17 Sep 2014 19:06:37 -0000 1.1.2.1 @@ -0,0 +1,100 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace util

    Method Summary

    +Listing of public methods:
    The namespace util currently contains no public +methods.

    Method Detail

    +* indicates required

    +Private Methods:
    +

    + +
    a proc used for debugging, just prints out a value to +the error log
    + +
    +
    capitalizes the first letter of a string
    +
    Returns:
    returns formatted string
    +
    +
    + +
    +
    escapes quotes and removes comment tags from a body of +commented text
    +
    +Parameters: + +
    +text* +
    +
    Returns:
    text
    +
    +
    + +
    +
    just takes a body of text and puts a space behind every +double {quote;} this is done so that the text body can be treated +as a list without causing problems resulting from list elements +being separated by characters other than a space
    +
    +Parameters: + +
    +text* +req/none the body of text to be worked on
    +
    Returns:
    same text but with a space behind each quote; double quotes +that are already trailed by a space are unaffected
    +
    +
    + +
    +
    takes a .adp template name and the name of the file to +be written and creates the {file;} also puts out a notice +before
    +Parameters: + + + + + +
    +template* +the name of the template to be used in making the +file
    +file_name* +the name of the file to be created
    +
    +
    + +
    +
    takes an alphabetized list and an entry
    +
    +Parameters: + + + + + +
    +list* +{let's see how this parses out} the alphabetized +list
    +entry* +req the value to be inserted
    +
    Returns:
    either the proper list index for an alphabetized insertion or +-1 if the entry is already in the list
    +
    +
    + +
    used to compare two different elements in a list of +parsed data for public or private procs
    + +
    uses ns_library to find the server root, may not always +be accurate because it essentially asks for the tcl library path +and strips off the last /tcl directory
    + +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/TclDocs/widget.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/widget.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/widget.adp 17 Sep 2014 19:06:37 -0000 1.1.2.1 @@ -0,0 +1,261 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

    Namespace widget

    Procedures for generating and processing metadata form +widgets, editing attribute widgets

    Method Summary

    +Listing of public methods:
    +widget::param_element_create
    +

    Method Detail

    +* indicates required

    Public Methods:
    + +
    widget::param_element_create
    +
    Dipatches subprocs to generate the form elements for +setting an attribute widget param
    +Parameters: + + + + + + + + + + + + + + + +
    +form* +Name of the form in which to generate the form +elements
    +param* +Name of the form widget param for which to +generate a form element
    +order* +The order that the param form widget will appear +in the form
    +param_id* +The ID of the form widget param
    +default* +The default value of the form widget param
    +is_required* +Flag indicating whether the form widget param is +optional or required
    +param_source* +The default source of the value of the form widget +param. One of literal, eval, query
    +
    +

    +Private Methods:
    +

    + +
    +widget::create_options_param
      by Michael Pih +
    +
    Create the options param form widget for adding/editing +metadata form widgets
    +Parameters: + + + + + + + + + + + +
    +form* +The name of the form
    +order* +The order of placement of the form widget within +the form
    +default* +The default value of the form widget param +value
    +is_required* +A flag indicating whether the form widget param +value is mandatory
    +param_source* +The default param source for the form widget param +value (literal, query, eval)
    +
    +
    + +
    +widget::create_param_source
      by Michael Pih +
    +
    Create default param_source form widget for +adding/editing metadata form widgets
    +Parameters: + + + + + + + +
    +form* +
    +order* +The order of placement of the form widget within +the form
    +param_source* +The default param source of the metadata widget +(literal, query, eval)
    +
    +
    + +
    +widget::create_param_type
      by Michael Pih +
    +
    Create default param_type form widget for +adding/editing metadata form widgets
    +Parameters: + + + + + +
    +form* +The name of the form
    +order* +The order of placement of the form widget within +the form
    +
    +
    + +
    +widget::create_param_value
      by Michael Pih +
    +
    Create default param_value form widget for +adding/editing metadata form widgets
    +Parameters: + + + + + + + +
    +form* +The name of the form
    +order* +The order of placement of the form widget within +the form
    +is_required* +A flag indicating whether the value of the form +widget param is mandatory
    +
    +
    + +
    +widget::create_text_param
      by Michael Pih +
    +
    Create default text param form widget for +adding/editing metadata form widgets
    +Parameters: + + + + + + + + + +
    +form* +The name of the form
    +default* +The default value for the form widget param +value
    +is_required* +A flag indicating whether the value of the form +widget param is mandatory
    +param_source* +The deafult param source for the form widget param +value (literal, query, eval)
    +
    +
    + +
    +widget::create_values_param
      by Michael Pih +
    +
    Create the values param form widget for adding/editing +metadata widgets
    +Parameters: + + + + + + + + + + + +
    +form* +The name of the form
    +order* +The order of placement of the form widget within +the metadata form
    +default* +The default value of the form widget param +value
    +is_required* +A flag indicating whether the form widget param +value is mandatory
    +param_source* +The default param_source for the form widget param +value (literal, query, eval)
    +
    +
    + +
    +widget::process_param
      by Michael Pih +
    +
    Edits a metadata form widget parameter from the +form
    +Parameters: + + + + + + + + + + + +
    +db* +A database handle
    +form* +The name of the form
    +order* +The order of placement of the param form widgets +within the form
    +content_type* +The content type to which the attribute +belongs
    +attribute_name* +The name of the attribute
    +
    +

    +* indicates required

    + Index: openacs-4/packages/acs-templating/www/doc/api/database.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/database.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/api/database.adp 17 Sep 2014 19:06:38 -0000 1.1.2.1 @@ -0,0 +1,56 @@ + +{/doc/acs-templating {Templating}} {Templating System API: Database Query} +Templating System API: Database Query + + + +

    Database Query

    Summary

    Utilize the results of a database query as a template data +source.

    Method

    +query name structure sql -db dbhandle 
+                             -startrow n 
+                             -maxrows n
+                             -bind (set|list)
+                             -eval { code }
+

    Perform a query and store the results in a local variable.

    Examples

    +set db [ns_db gethandle]
+
+# this will set a scalar named current_time
+template::query current_time onevalue "select sysdate from dual" -db $db
+
+# this will set a single array named user_info with a key for each column
+template::query user_info onerow "select * from users 
+                                  where user_id = 86" -db $db
+
+# this will set an array for each row returned by the query
+# the arrays will be named user_info:1, user_info:2, etc.
+# the variable user_info:rowcount will be set with the total number of rows.
+template::query user_info multirow "select * from users" -db $db
+
+# this will set a list named emails
+template::query emails onelist "select email from users" -db $db
+
+# this will set a list of lists named user_info
+template::query user_info multilist "select * from users" -db $db
+
+# this will create a nested list of lists in the form
+# { California { Berkeley { { Ralph Smith } { Doug Jones } } } \
+#   Minnestota { Minneapolis { { Ina Jaffe } { Silvia Pojoli } } } }
+template::query persons nestedlist "
+  select state, city, first_name, last_name from users" \
+  -db $db -groupby { state city }
+

    Note(s)

      +
    • Valid values for structure are onevalue, onerow, +multirow, onelist, nestedlist and multilist. +
    • +sql may be any valid SQL statement whose result set +has the appropriate dimensions for the desired +structure.
    • The db parameter is optional. If no parameter is +supplied, a handle will be requested to perform the query and then +released immediately.
    • The startrow and maxrows parameters are valid +only for multirow queries. They may be specified to limit the rows +from the query result that are included in the data source.
    • The eval parameter takes a block of Tcl code to +perform on each row of a multirow query as it is fetched from the +database. The code may refer to the row array to get and +set column values.
    • The bind option is valid only when using Oracle.
      • +
    templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/api/element.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/element.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/api/element.adp 17 Sep 2014 19:06:38 -0000 1.1.2.1 @@ -0,0 +1,45 @@ + +{/doc/acs-templating {Templating}} {Templating System API: Form Element} +Templating System API: Form Element + + + +

    Form Element

    Summary

    Methods

    +template::element create form_name element_name \
+                        -widget widget \
+                        -datatype datatype \
+                        -html { attribute value attribute value ... } \
+                        -validate { \
+                          name { expression } { message } \
+                          name { expression } { message } \
+                          ... } \
+                        -options { { label value } { label value } ... } \
+                        -maxlength maxlength \
+                        -value value \
+                        -values { value value ... }
+                        
+

    Append a new element to the specified form.

      +
    • The html switch may be used to include additional HTML +attributes in the input, select, or +textarea tag used to ultimately render the element.
    • The validate switch may be used to perform simple +custom validation of each element value. type is a keyword +for the type of validation being performed. This same keyword must +be referenced by the formerror tag to customize the +presentation and layout of the error message for this validation +step. expression must be a block of arbitrary Tcl code +that evaluates to 1 (valid) or 0 (not valid). The variable +$value may be used in the expression to reference the +element value. message is simply a string containing a +message to return to the user if validation fails. The variables +$value and $label may be used in the message to +reference the parameter value and label (or name if no label is +supplied).
      • +
    +template::element set_properties form_name element_name
+                                 
+
    +template::element get_value form_name element_name
+

    Example

    +template::element get_values form_name element_name
+

    Note(s)

    templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/api/form.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/form.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/api/form.adp 17 Sep 2014 19:06:38 -0000 1.1.2.1 @@ -0,0 +1,25 @@ + +{/doc/acs-templating {Templating}} {Templating System API: Form} +Templating System API: Form + + + +

    Form

    Summary

    Building dynamic forms with automated validation.

    Methods

    +template::form create name \
+                      -html { attribute value attribute value }
+

    Initialize data structures for a dynamic form. This procedure +must be called before adding elements to the form.

    • Additional attributes to include in the HTML form tag may be +specified with the html option.
    +template::form is_request name
+

    Boolean procedure for determining whether a submission is in +progress. If this procedure returns true, then an initial request +for the form is underway. The code for insert or add forms may thus +query for primary key value(s), and the code for update forms may +query for current data and set the value(s) of form elements +accordingly.

    +template::form is_valid name
+

    Boolean procedure that returns true if a submission is in +progress and the submission is valid. Database or any +other transactions based on the form submission should only take +place after this procedure has been checked.

    Example

    Note(s)

    templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/api/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/index.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/api/index.adp 17 Sep 2014 19:06:38 -0000 1.1.2.1 @@ -0,0 +1,20 @@ + +{/doc/acs-templating {Templating}} {Object and API Reference} +Object and API Reference + + + +

    Object and API Reference

    Templating System : Developer Guide : API + +Some of the API discussed here achieves functionality that the ACS +(ArsDigita Community System) provides, just in different ways. If +you have the ACS installed, you likely want to use that instead of +the query and request call presented +below. +
    Christian +Brechbühler
    +Last modified: $Id: index.html,v 1.1.1.1 2001/03/13 22:59:27 ben +Exp $ + Index: openacs-4/packages/acs-templating/www/doc/api/multirow.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/multirow.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/api/multirow.adp 17 Sep 2014 19:06:38 -0000 1.1.2.1 @@ -0,0 +1,47 @@ + +{/doc/acs-templating {Templating}} {Templating System API: Multirow} +Templating System API: Multirow + + + +

    Multirow

    Summary

    Access and modify rows and columns of a multirow data +source.

    Methods

    +multirow getname index column
+
    +

    Get a particular column value or a reference to an entire +row.

      +
    • Rows are indexed starting with 1.
    • If a column name is omitted, this procedure will set +name to be a reference to an array containing the values +for the row specified by index.
      • +
    +
    +multirow setname index column value
+

    Set the value of a column in a specified row.

    +multirow sizename
+

    Get the number of rows in the data source.

    +multirow createname column [column ...]
+

    Set up a new multirow data source. This is an alternative to +having db_multirow create the +data source.

    +multirow appendname value [value ...]
+

    Add a row at the end of the data source. Extra values are +dropped, missing values default to the empty string

    +multirow mapname body
+

    Evaluate body for each row of the data source, and +return a list with all results. Within the body, all columns of the +current row are accessible (and modifiable) as local variables. +(Not yet committed.)

    Examples

    +  template::query foo multirow "select first_name, last_name from users"
+
+  # get the first name of the first user
+  set first_name [multirow get foo 1 first_name]
+
+  # get a reference to the entire row
+  multirow get foo 1
+
+  # this will the full name of the first user
+  set full_name "$foo(first_name) $foo(last_name)"
+

    Note(s)

    • Use the eval option to template::query to modify +column values while building a data source from a multirow query +result.
    templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/api/request.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/api/request.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/api/request.adp 17 Sep 2014 19:06:38 -0000 1.1.2.1 @@ -0,0 +1,70 @@ + +{/doc/acs-templating {Templating}} {Templating System API: Page Request} +Templating System API: Page Request + + + +

    Page Request

    Summary

    Transform, validate and report errors in the query parameters +associated with a page request.

    This API is an alternative to ad_page_contract +which should usually be preferred if you have ACS installed.

    Methods

    +template::request create
+

    Initialize the data structure to store request parameters. +Should be called at the start of any page that takes request +parameters.

    +template::request set_param name 
+                            -datatype datatype
+                            -multiple
+                            -optional
+                            -validate { { expression } { message } }
+

    Validates request parameter values and then sets a local +variable. Values are transformed if a transformation procedure +exists for the specified datatype (i.e. the components of a +date are assembled into a single structure).

      +
    • Options for datatype are the same as for form +elements.
    • The multiple switch indicates that more than one value +may be submitted. The local variable set by the procedure will be a +list.
    • The optional switch indicates that the parameter value +may be empty or missing. A value is assumed to be required if this +switch is not specified.
    • The validate switch may be used to perform simple +custom validation of each parameter value. expression must +be a block of arbitrary Tcl code that evaluates to 1 (valid) or 0 +(not valid). The variable $value may be used in the +expression to reference the parameter value. message is +simply a string containing a message to return to the user if +validation fails. The variables $value and $label +may be used in the message to reference the parameter value and +label (or name if no label is supplied).
      • +
    +template::request get_param name
+

    Returns the value (or values if the multiple is used) +of the named parameter.

    +template::request is_valid error_url
+

    Boolean procedure for determining whether any validation errors +occurred while setting request parameters.

    • +error_url is the location of the template to use for +reporting request errors. The default is +/ats/templates/messages/request-error if no URL is +specified. To report request errors in the template of the page +itself, use self for the URL.

    Example

    +request create
+
+request set_param state_abbrev -datatype keyword -validate {
+  { regexp {CA|HI|NV} $value } 
+  { Invalid state abbreviation $value. }
+}
+
+request set_param start_date -datatype date
+request set_param user_id -datatype integer -multiple
+
+if { ! [request is_valid "/mytemplates/request-error"] } { return }
+
+...
+

    Note(s)

      +
    • Error reporting templates may reference the +requesterror array to access error messages for each +parameter.
    • The request API provides a simple mechanism for processing +request parameters. It is not intended as a replacement to +ad_page_contract for sites built on the ArsDigita +Community System.
      • +
    templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/appendices/memory.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/appendices/memory.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/appendices/memory.adp 17 Sep 2014 19:06:38 -0000 1.1.2.1 @@ -0,0 +1,88 @@ + +{/doc/acs-templating {Templating}} {Templating System Appendix D: Parsing templates in +memory} +Templating System Appendix D: Parsing templates in +memory + + + +

    Parsing Templates in Memory

    The templating system code is oriented towards parsing templates +stored in the file system, in conjunction with a Tcl script that is +also stored as a file. However, when the template is not actually +stored in the file system, you will need to parse it as a string in +memory. Two common situations in which this occurs are:

      +
    • Templates are stored in the database.
    • Templates are generated dynamically, possibly based in turn on +a "style" template. This is how ATS auto-generates forms.
      • +

    The Parsing Process

    Whether the template is ultimately stored in a file or not, the +templating system follows the same basic process during the parsing +process:

      +
    1. +Prepare data sources. Some Tcl code is evaluated to +prepare data sources (scalars, lists, multirow data structures) for +merging with the template. (For file-based templates the +interpreted code is cached in a procedure after the first +time).
    2. +Compile the template.. The template markup is compiled +into a chunk of Tcl code that builds the page into a single output +string. (For file-based templates the resulting code is cached in a +procedure after the first time).
    3. +Evaluate the compiled template. The template code is +evaluated in the same stack frame as the data source code, so that +all variables declared as data sources are directly available to +the template. The result of the evaluation step is a single string, +which normally is written to the connection.
      4. +

    How to Parse Templates in Memory

    The templating system provides a low-level API that allows you +to perform the three steps described above in the context of your +own code:

    +# set up any number of data sources:
+
+set first_name George
+
+query cars multirow "
+  select make, model from cars where first_name = :first_name"
+
+# get the template.  This may be a static string, be queried from the
+# database, generated dynamically, etc.
+
+set template "
+Hello \@first_name\@!
+
+<multiple name=cars>
+  \@cars.rownum\@. \@cars.make\@ \@cars.model\@<br>
+</multiple>
+"
+
+# compile the template.  The templating system takes the
+# result of this step and wraps it in a proc so that it is 
+# bytecode-cached in the interpreter.  You may wish to implement
+# some sort of simple caching here as well.
+
+set code [template::adp_compile -string $template]
+
+# evaluate the template code.  Note that you pass a reference
+# to the variable containing the code, not the value itself.  The code
+# is evaluated in the calling stack frame (by uplevel) so that
+# the above data sources are directly accessible.
+
+set output [template::adp_eval code]
+
+# now use the output however you wish
+
    +Also see the "string" demo. +

    Generating Templates from Other Templates

    In some cases, the template itself may be based on yet another +base template. For example, the templating system itself generates +form templates based on a generic "style" template. The generic +template primarily depends on a single data source, +elements, which references the element list for a +particular form object. A single multipleloop is used to +lay out the specific formwidget and formgroup +tags, along with labels and validation text, for the form. The +output of this first step is then rendered into HTML and returned +to the user.

    Note that the generic "style" template contains templating tags +(formwidget, formgroup, if etc.) that +must be "protected" during the first step. The templating system +provides the noparse +tag to do this.

    templating\@arsdigita.com
    +Last modified: $Id: memory.html,v 1.1.1.1 2001/03/13 22:59:27 ben +Exp $ + 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 -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/demo/index.adp 17 Sep 2014 19:06:39 -0000 1.1.2.1 @@ -0,0 +1,249 @@ + +{/doc/acs-templating {Templating}} {Templating System Samples} +Templating System Samples + + + +

    Samples

    Templating System : Demo + +As the links reveal, the "Data" files have the extension +.tcl and the "Template" files have .adp. +If you want to see a little behind the scenes, you can look at the +tcl code into which we compile the template. The last column will +deliver the resulting page to your browser. +

    Mechanisms underlaid in red are known to not work.

    General

    + + + + + + + + + + + + + +
    DescriptionDataTemplateCompiled
    +Template    		Output
    Simple variable substitutionViewViewViewView
    Using bind variables in your queryViewViewViewView
    A plain Tcl page that returns its own outputViewNoneNoneView
    Conditional ExpressionsViewViewViewView
    CommentsNoneViewViewView

    Combining templates

    + + + + + + + + + + + +
    DescriptionDataTemplateCompiled
    +Template    		Output
    Include a template within another templateView +include
    included +    		 +include
    included +    		View
    Wrap a page within a master templateNone +Slave
    Master +    		 +Slave
    Master +    		View
    Using the default masterNoneViewViewView
    Include with master and recursion.
    +Remember Fibonacci from pset 1, exercise 1?    		 +Start
    Included
    Master +    		 +Start
    Included
    Master +    		 +Start
    Included
    Master +    		View

    Embedded Tcl

    + + + + + + + + + + + +
    DescriptionDataTemplateCompiled
    +Template    		Output
    Tcl escape with implicit outputViewViewViewView
    Tcl escape with explicit outputNoneViewViewView
    Template chunks within escaped Tcl code blocksViewViewViewView
    Puts (if you absolutely must)ViewViewViewView

    Iteration

    +To see the following examples with different data, you can enter +additional users into the sample table with "a simple form" or +change them with "editing: several pages in one" in section +Using the Form Manager below. + + + + + + + + + + + + + + + +
    DescriptionDataTemplateCompiled
    +Template    		Output
    Repeating template chunks for each row of a query resultViewViewViewView
    Generating the multirow datasource in TCLViewViewViewView
    Repeating template chunks for each row of a query result, with +custom manipulation of dataViewViewViewView
    Repeating template chunks with grouping +ViewViewViewView
    Repeating template chunks as cells of a gridViewViewViewView
    Repeating template chunks for each element of a listViewViewViewView

    Both Iteration and Composition

    + + + + + + + + + +
    DescriptionDataTemplateCompiled
    +Template    		Output
    Apply different skins to the same dataView +Plain
    Fancy +    		 +Plain
    Fancy +    		 +Plain
    Fancy
    Absolute +
    Passing a multirow datasource to an included pageView +Outer
    Included +    		 +Outer
    Included +    		View
    Processing a template from a string (not file)ViewViewViewView

    Using ListBuilder

    + + + + + + + + + + + + + + + + + + + + + +
    DescriptionDataTemplateCompiled
    +Template    		Output
    Simplest (single-column) list, no features +View +.tcl
    postgres +query
    oracle +query +    		 +No +master
    W/ master +    		 +No +master
    W/ master +    		 +No master
    W/ master +
    Add some columns +View +.tcl
    postgres +query
    oracle +query +    		ViewViewView
    Add the ability to sort by any column +View +.tcl
    postgres +query
    oracle +query +    		ViewViewView
    Link the title to a one-note detail page +index
    detail +    		 +index
    detail +    		 +index
    detail +    		View
    Add a bulk action to delete all checked notes +index
    delete
    postgres +query
    oracle +query +    		indexindexView
    Add a single/non-bulk action to create a note +index
    add-edit +    		 +index
    add-edit +    		 +index
    add-edit +    		View
    Add a filter +index
    postgres +query
    oracle +query +    		 +index
    +    		 +index
    +    		View
    Add pagination with no page group cache +index
    postgres +query
    oracle +query +    		 +index
    +    		 +index
    +    		View
    Add page group caching to pagination (no looks difference) +index
    add-edit
    delete
    +    		 +index
    +    		 +index
    +    		View

    Forms

    + + + + + + + +
    DescriptionDataTemplateCompiled
    +Template    		Output
    Using ad_page_contractTarget +Form
    Target
    Error Page +    		 +Form
    Target
    Error Page +    		 +Form
    Target
    + 
    Report an error related to a request.ViewViewPlainView

    Using the Form Manager.

    + + + + + + + + + + + + + + + + + + + + + +
    DescriptionDataTemplateCompiled
    +Template    		Output
    A simple formViewViewViewView
    A form with button groupsView +Simple
    Gridded +    		 +Simple
    Gridded +    		 +Simple
    Gridded +
    A form with Select widgetsViewViewViewView
    Custom validation of a requestViewViewViewInline Error +Message
    Sitewide Error Page
    Valid +Request
    A form with the Date widgetViewViewViewView
    Editing: several pages in oneViewViewViewView
    A form with a custom confirmation pageView +Submit
    Confirm +    		 +Submit
    Confirm +    		View
    A form with display/edit modesViewViewViewView
    A form with multiple submit buttonsViewViewViewView

    templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/exercise/ats-for-designers.adp 17 Sep 2014 19:06:39 -0000 1.1.2.1 @@ -0,0 +1,246 @@ + +{/doc/acs-templating {Templating}} {The ACS Templating System for Web Designers} +The ACS Templating System for Web Designers + + + +

    The ACS Templating System for Web Designers

    Reading

    Sections

      +
    1. Overview
    2. Exercises
      3. +

    Overview

    This series of exercises is meant as a learning tool for any web +graphic designer wanting or needing to understand how the ACS +Templating System, or ATS, works, and how to use it in building web +pages.

    First, perhaps an explanation of what the templating system does +will help us understand how it works. An ATS template itself serves +as a reusable, unchanging framework that delivers dynamic data. The +advantage to this is something you probably already realize: you +need only build and edit a few pages to maintain a consistent +presentation style while accomodating numerous permutaions of +changing data.

    This training module will teach largely by exercise and example, +but you should also refer regularly to the ATS documents provided and more specific +pointers will be given to help you out along the way.

    Okay, let's get to the nitty gritty.

    Exercises

    The basic building block of dynamic data in a template is the +onevalue variable. A variable +is simply a tag used in your .adp file that holds data +supplied by another source file; that source will probably be +another file of the same name with a .tcl extension. +Variable tags come in three basic formats, as lists, multiples and onevalues.

    +Exercise 1: Onevalues, onelists, multilists and +multirows
    +(nestedlists, too?)

    Let's first take a look at some list and variable tags in +action. Open up another browser and look at this page, which is a text rendition +of the /ats/doc/exercise/list-and-var-sample.tcl page +we'll be sourcing our data from; at the top of the page you'll find +a block of commented text describing the variables generated by +this page, followed by the actual code itself. Now, using your +preferred text editor, open the file +list-and-var-sample.adp located in the same directory +and compare the html script that you see there with the final +user-viewed page, list-and-var-sample.acs. +Almost every .acs page the user sees is supported by one .tcl file +which supplies the data to be shown, and one .adp file specifying +the format of it's presentation. Compare what you see in +list-and-var-sample.acs with its supporting .adp file +and make note of the textual and structural differences between the +two, specifically:

      +
    • +variables in the +.adp file are designated with "\@" markers, like the +\@name\@ variable that litters the opening text block of +list-and-var-sample.adp; here, \@name\@ is +used as a place-marker for the value set in +list-and-var.sample.tcl +
    • the variables within the <multiple> tag, though only +appearing once in the .adp file, are cycled repeatedly to show +multiple sets of information when displayed in +list-and-var-sample.acs; example: +
          <multiple name="your_multirow">
+    <tr><td>\@your_multirow.first_names\@ \@your_multirow.last_name\@ </td> </tr>
+    </multiple>
+
      +The user will see one table row filled with a different person's +name for each row contained in the multirow +your_multirow.
    • multirow variables are identified with this format: \@<name +of the multirow>.<name of a field in the multirow>\@, and +can only be called within their respective +<multiple> tags
      • +

    You probably noticed some other funky looking tags, too, but +ignore those for now.

    Now since the variable marker \@name\@ is set in +list-and-var-sample.tcl, you can go ahead and edit +that file to replace "(Your Name)" with whatever your +name really is (be sure to leave the quotes); if you wish,edit some +of the other values to personalize the page. You'll see your +changes take effect upon saving the .tcl file and reloading +list-and-var-sample.acs. In general, though, you +should probably not be editing .tcl files unless you have a pretty +good sense of their innerworkings.

    Okay, now go back to the web browser in which you are viewing +list-and-var-sample.acs and change the ".acs" +extension to ".dat". This +page displays a view of datasources generated in the .tcl file that +can be used in your .adp template (actually, the information is +generated from commented text parsed from the top of the .tcl file, +so you can view this information in either the .dat page or +straight from the .tcl file). Go ahead and make use of the +datasource variables not already included in the .adp file; +specifically, change list-and-var-sample.adp so +that:

      +
    • your personal phone number information is included
    • each of your friends' names serves as a hyperlink that allows +the viewer to email your friend
    • a listing of recently watched movies and your reactions to them +follows after the information about your friends
    • also, note that the use of any variable tags referring to +variables not declared in the .tcl file will break the .acs +page
      • +

    Congratulations! You've just created a personalized web page +describing friends you've never met and movies you've possibly +never seen.

    Exercise Two: <if> and <else>, the conditional +tags

    Dynamic data implies a changing page, and also changing +presentation. The <if> and +<else> tags allow you to alter the format of your page to +accomodate data changes. The function of <if> is +straightforward enough: given a condition -- such as \@x\@ equals 5 +-- all the text/html/dynamic data between the the opening and +closing <if> tags will be displayed if and only if \@x\@ does +in fact equal 5. A complete listing of currently supported +conditions and some brief explanatory notes can be found here. Also, a few more things to keep in +mind:

      +
    • in Tcl all variables, even numbers, are stored as text strings +with quantitative values, so conditions like less than, greater +than, and (not) between can also be used with text to determine +alphabetical order: a < b < ... < z, +lower-case letters are greater than upper-case, and numbers less +than letters. Example: "you" are greater than "me", and "I" am less +than "you"
    • the "between" conditions checks inclusively, so <if 2 +between 2 6> will test true
    • +<if \@a\@ between \@b\@ \@c\@> requires that +\@a\@ is greater than or equal to \@b\@and less than or equal to \@c\@; so <if +\@x\@ between 4 2> will always test false
    • the "in" condition uses a regular expression check (or will it? +come back here and revise)
      • +

    Now, alter a few of the <if> tags in +list-and-var-samle.adp and add a few of your own. +Specifically, add one <if> and <else> combination so +that the friend description reads "likes chocolate" when +likes_chocolate_p is "t", "doesn't like chocolate" +when likes_chocolate_p is "f", or "probably like +chocolate" if likes_chocolate_p is an empty string. +Also, add one <if>, and one <if> only, so that a +is appropriately changed to an for any 11-, 18- or 80- to +89-year olds.

    Exercise Three: The <master> and <slave> tags -- +a call to the dominatrix in you

    The <master> and +<slave> tags allow you to +maintain a consistent style and format among pages without having +to edit each page individually. To get a sense of what these tags +do and how they work, go ahead and run through this short demonstration, and then use a text editor to +view the related .adp files. Also, read this discussion on the use of master +pages.

    One thing you may have noticed earlier about +list-and-var-sample.adp is that it lacks the standard +<html>, <head>, <title> and <body> tags. +This is because list-and-var-sample.adp is, as +indicated by the <master> tag at the top of the file, also a +slave section, contained within master-sample.adp.

    Let me stress a few key points you might have already picked up +on from the demonstration and upon examining the .adp files, and +add a few pointers:

      +
    • the <slave> tag indicates where on the master page the +slave section is inserted
    • slave pages indicate the source of the master file with the +<master> tag, referring by the file name only, and not +including its ".adp" extension
    • as mentioned earlier, slave sections do not require +<html>, <head>, and <body> tags when contained +within a master tag already formatted for HTML
    • as the demonstration points out, pages are browsed at the .acs +page sharing the same file name as the slave, not master
    • the master page can be viewed at its own .acs page, but shows +nothing in place of the <slave> tag
    • you can have nested slave sections, that is, a slave section +within another slave
    • you cannot have two different slave sections within the +same master (go ahead and try adding an extra <slave> tag to +a master page to see what happens)
    • +<property> tags are +used within a slave section to pass text, HTML and references to +local datasources up to the master page; these values are placed in +the master page in the same fashion as onevalues
    • data and HTML can be passed from a nested slave section to its +uber-master by using one <property> tag on each intermediate +page
    • if a variable set in the Tcl file of a master page shares the +same name as a variable declared within the slave section's +<property> tag, the master value overrides the slave's +(unless the Tcl code checks for pre-existing information)
      • +

    Now that the secrets of <master> and <slave> have +been revealed, it's time to put a little of your newfound knowledge +to use. Open up form-sample.adp, a standalone, +independently formatted html page, and enslave it to the mastery of +of your personal web page. It would also be nice if you were to +label the newly inserted form with some slave-specific title.

    +Exercise Four: The functions of +<formtemplate>
    +

    Creating forms with ATS can be as simple as inserting two tags +into a page. Try this: open form-sample.adp and add +the two following ATS tags:

    <formtemplate +id="add_entry"></formtemplate>

    Save the page and reload it. You should see now see a big +baby-blue form block; this is the ATS default style for form +presentation. Aside from requiring no HTML code, the +<formtemplate> default has the added convenience of automated +entry validation with appropriate correction requests. Test this +out by trying to submit a form without including first or last name +or gender information.

    However, if ever you wish to build a form according to the +mandates of your own taste, <formtemplate> also leaves you +this option. Manually stylizing forms with ATS requires you to +learn only two more tags, <formwidget> and <formgroup>. Browse through the +ATS demo for examples of +<formwidget> and <formwidget> usage. For the most part +<formwidget> should be used in most places you might have +used <select> or <input> in plain HTML, save for +<input> checkboxes and radio buttons, which should be +replaced with the <formgroup> tag. When working with ATS you +should probably refrain from using plain <input> and +<select> tags altogether.

    You may have already noticed a few <formwidget> and +<formgroup> in use within the block of HTML and ATS text +commented out in form-sample.adp. Go ahead and put +that block of HTML/ATS code into action by removing the comment tag +wrapper and deleting the </formtemplate> tag; +you should now see a hand-built version of the same form.

    There are noticeable differences between the two form templates, +most obviously the lack of background color and a few missing entry +fields in the manually constructed one. Maybe not so noticeable is +the grouping of entry widgets into one HTML table row (check out +the Name field) and the multi-input combination of text +entry boxes and radio buttons for entering telephone number +information. Take a look at how the phone information entry section +is constructed in form-sample.adp. Note specifically: +<formgroup> is somewhat similar to the <multiple> tag +in that the block of ATS code contained within the +<formgroup> tags will be parsed into plain HTML once for each +<formgroup> value option.

    Practice using <formwidget> and <formgroup> by +adding the missing entry fields manually into the form. Make free +use of any HTML properties to streamline the form to your liking. +If you can't remember what those fields were you can replace the +closing </formtemplate> tag to recover the default format, or +make use of the .dat datasource page to view your developer's +description and comments about the form.

    Also, try customizing your form's error response/correction +request text. You'll need to use the <formerror> tag, an example of +which can be found under the gender formwidget.

    Exercise Five: more fun with multirows

    Now that you've confidently added the conditional <if> and +<else> tags to your ATS toolbelt, it's time to put those +tools to good use in formatting multirow data. First, read the +docs to learn about the +automatcally generated \@your_multirow.rownum\@ +column, the \@your_multirow:rowcount\@ onevalue +which contains the total number of rows contained in your multirow, +and the <multiple> startrow and +maxrows attributes. Possible point of confusion: the +variable \@your_multirow:rowcount\@ is a onevalue +and not a column of the multirow your_multirow, +so it need not be used within <multiple> tags and in many +cases should not be used within <multiple> tags. Why is this? +(Take a look at how \@address:rowcount\@ is used.) Now +make the following improvements to the address book listing you +found in form-sample.acs:

      +
    • stripe the table with banded rows of alternating grey and +white, or some other color scheme of your preference
    • use the startrow attribute so that the address +book listing begins at a rownumber determined by the Tcl file code +(check the .dat page)
    • add navigation links to the address book so that users can move +forward or back between row listings, or jump to the beginning or +end of their address book
      • +
      • each link should set the url variable that determines the first +row of the set to be displayed
      • the links should only appear when necessary, that is, a link +pointing towards the next set of rows should not appear if the user +is already viewing rows 1-5 of 5 total rows.
        • +
      • +
    shuynh\@arsdigita.com
    +Last modified: Fri Nov 17 10:14:44 EST 2000 + Index: openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/gen/proc-doc.adp 17 Sep 2014 19:06:39 -0000 1.1.2.1 @@ -0,0 +1,149 @@ + +{/doc/acs-templating {Templating}} {Commenting Tcl procedures for parsing} +Commenting Tcl procedures for parsing + + + +

    Using comments to document Tcl procedures

    Templating System

    Text divisions, grouping

    < blah blah > The Tcl proc parser relies on three main +text markers to divvy the Tcl library file into neat compartments: +namespace, procedure and directive. Each of these divisions has its +own text marker(s). In the end, your Tcl file should look somthing +like this: +
    
+[------------------------------------------------------]
+[------  ignored text at beginning of file  -----------]
+[------------------------------------------------------]
+
+# \@namespace<name><description of namespace>
+        # <continued description>
+
+        # \@author<name of the primary author for this namespace>
+
+        # \@see<type of reference, like proc, namespace, url, or other><full name of reference><url of reference>
+        # \@see ... <more references>
+
+
+   # (\@public|\@private) <name><description of procedure>
+     # <continued description>
+
+     # \@param<name><default value><description>
+     # <continued description>
+
+     # \@param ... <info for other paramaters>
+
+     # \@option<name><default value><description>
+     # <continued description>
+
+     # \@option ... <info for other options>
+ 
+     # \@author<name of author>
+
+     # \@return<description of return variable>
+
+     # \@see<just like the namespace \@see directive>
+
+     [------------------------------------------------------]
+     [----------  source text for procedure  ---------------] 
+     [------------------------------------------------------]
+
+
+   # \@public or \@private ... < more procedures within the same namespace >
+
+
+# \@namespace ... <other namespaces>
+
    +Note that comment lines are indented to indicate the manner in +which they should be grouped only, and that there is no required +spacing scheme for comments. +

    Use of these directive markers is largely straightforward, but a +more in depth guideline of how the markers guide parsing may help +those documenting their own work:

    +the \@namespace marker
      +
    • +\@namespace is used to indicate the starting +point of all text -- code and comments -- related to the procedures +contained within that namespace. All text between one +\@namespace marker and the next is parsed out as either +Tcl proc source text or commentary of some sort
    • the body of text that falls between two \@namespace +markers is divided into sections identified by
      • +
    the \@public/private markers
      +
    • although this convention is in no way enforced, each Tcl +procedure should be prefaced with an \@private marker +if the procedure is meant only for internal package use, or with an +\@public marker if the proc is intended to be a CMA, +ATS, or ACS Content Repository developer api
    • any text that falls between one \@public/private marker and the +next proc <procedure name> call will be parsed +out as commentary text; all text after the proc +command but before the next \@private or +\@public marker is recorded as source code
      • +
    the directive markers
    +The commentary text that precedes a Tcl proc command +should contain a list of directives identified by these markers: +
      +
    • \@author
    • \@param
    • \@option
    • \@return
    • \@see
      • +
    +The parser requires no specified ordering or grouping of these +directives. Note: there should be one \@param or +\@option directive marker for each parameter and option +accepted by Tcl procedure. For the \@option and +\@parameter markers, please follow one of the following +formats, depending on whether or not the parameter or option you +are detailing has a default value: +
    with a default value: +
    # \@(param|option) <parameter name> +{default <description of default value>} +<description or explanation> +
    +for required parameters: +
    # \@param <parameter name><description or explanation> +
    +
    +Note that the literal curly brackets with the word +default are required to include any information about +the option or parameter's default values. When default-value +information is not included, the entry value will be marked as +required if it is a parameter, or display no information if +it is an option. +

    For example: the fictional procedure grant_permission might be +preceded by these comments:

    # \@public grant_permission
+# checks for whether or not a user has the privilege 
+# to manipulate an object in a specific manner
+
+# \@param user_id id of the user to be granted the privilege
+
+# \@param object_id id of the object which the user has been 
+# granted privilege to manipulate
+
+# \@param privilege_id {default defaults to read-write-edit on the object} 
+# id of the privilege specifying 
+# what actions the user can perform upon the object
+
+# \@option granter_id {default taken from the current user's id} id of the user granting the privilege
+# \@option alert_admin_email email of an admin to be alerted
+
+# \@see namespace util util.html
+
+
    +In the above example user_id and +object_id would be marked as required, +alert_admin_email would show no default-value +description, and granter_id and +privilege_id would show the the default info from +above. +

    On to \@see directive markers:

    # \@see <type of reference><name of +reference><url of reference> +
    +Indicating the url of the reference is made somewhat simple because +all namespaces will be described within their own static html page, +and all procedure information is anchor-referenced: +
    
+# \@see namespace util util.html
+# \@see proc template::multirow::create multiow.html#template::multirow::create
+# \@see url <a picture of wally my dog> http://my.page.net/dogs/wally.jpg
+# \@see proc doc::util::eat_chicken
+
    +If you are referring to a namespace or procedure (use +proc for the reference type), the url value is +optional as long as you use the full and completely +qualified name of the namespace or procedure.
    templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/gen/proc-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/gen/proc-doc.html,v diff -u -N -r1.1.1.1 -r1.1.1.1.28.1 --- openacs-4/packages/acs-templating/www/doc/gen/proc-doc.html 13 Mar 2001 22:59:27 -0000 1.1.1.1 +++ openacs-4/packages/acs-templating/www/doc/gen/proc-doc.html 17 Sep 2014 19:06:39 -0000 1.1.1.1.28.1 @@ -96,7 +96,7 @@ Content Repository developer api
  • any text that falls between one @public/private marker and the next proc - call will be parsed out as commentary text; all text after +<procedure name> call will be parsed out as commentary text; all text after the proc command but before the next @private or @public marker is recorded as source code
Index: openacs-4/packages/acs-templating/www/doc/guide/components.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/components.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/components.adp 17 Sep 2014 19:06:39 -0000 1.1.2.1 @@ -0,0 +1,28 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Building Reusable Template +Components} +Templating System User Guide: Building Reusable Template +Components + + + +

Building Reusable Template Components

Templating System : Developer Guide : User Guide +

Most page layouts can be separated into smaller components, many +of which may appear in different contexts throughout a site. +Examples include:

    +
  • A box or section of the page listing contextual links related +to the contents of the page.
  • A list of comments on the contents of the page.
  • A search box, user poll, or other small embedded form.
  • Reports and other administrative pages, where the employee may +wish to assemble multiple panels of information on a single +page.
  • Many popular portal sites allow users to customize their home +pages by choosing and arranging a set of small layout components +within a table grid.
    • +

The templating system makes it easy to build reusable components for any of the above +scenarios. The basic process is to build a container template, +which delineates the skeletal layout of the page. Component +templates may then be placed in the container template with the +include tag. The container may pass arguments to the +components as needed for personalization or any other purpose.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/composite.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/composite.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/composite.adp 17 Sep 2014 19:06:39 -0000 1.1.2.1 @@ -0,0 +1,129 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Composite Page} +Templating System User Guide: Composite Page + + + +

Assembling a Page from Components

Templating System : Developer Guide : User +Guide : Composite +

A typical page served to a browser is made up from several +component pages. The idea is to have reusable parts (widgets, +skins), a bit like in a programming language where code that may be +used more than once makes up a procedure. The complete page may +have the following structure.

+master + +
top
+root (main)

 

widget
+
bottom
+

The "root" page includes the "widget" and wraps itself in the +"master". That page in turn includes the "top" and "bottom".

Overall structure

The parts are put together with the <include> tag (in the diagram +below, black links going right) and the <master> tag (brown link going +left); and the concept is similar to a procedure call. The +structure of the composite page looks like this as a graph.

+ + + + + + + + + + + + + + + + + + + + + + + +
root
 code  template 
+ +
master code  template  code  template widget
 code  template  code  template 
topbottom

Any (sub)page can have 0 or 1 master and 0 or more included +pages. Each page has its own separate scope for variables. +Arguments can be passed to dependent pages as attributes to +<inlcude>, or as properties to +<master>. The directed graph of pages will often +be be acyclic, as in the example, but this is not required.

Evaluation Order

Sometimes it is of interest in which order the different parts +are evaluated. The "code" always runs first, followed by the +template. The <inlcude> tag causes the subpage +to be evaluated at this point of the template, and the rest of the +including template is evaluated after that's done. This is like a +procedure call. In contrast, the <master> tag is +deferred until the whole slave page ("root" in the example) is +done. For our example, the following order results.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
root.tcl
root.adp(beginning and middle)
 widget.tcl
widget.adp
root.adp(end)
 master.tcl
master.adp(beginning)
 top.tcl
top.adp
master.adp(middle, containing <slave> tag)
 bottom.tcl
bottom.adp
master.adp(end)

Here we assume the ACS/Tcl situation, where the "code" is a tcl +script in a .tcl file. The template is a .adp file.

Variants of Page Nodes

The graph of the overall structure has five nodes, shown as a +code/template pair. This is the standard situation, where the +"code" part sets up datasources and the template uses them. In some +situations, the following facility can help to reduce duplication +or to handle special situations more effectively.

The "code" part can divert to another page by calling +template::set_file to modify the file name stub of the +page being processed. For convenience, +ad_return_template can be used with the same effect; +it is a wrapper for template::set_file, and it +supplies the current file as the reference path. Neither affects +the flow of control; the script runs to completion. If at the end +the name is changed, the template of the original page is not used; +instead the new page is processed, code first, then template. As +that page's code can call set_file again, we get the +following picure.

+ + + + + + + +
code A(template A +ignored)
code B(template B +ignored)
...
code Ztemplate Z

This assumes page "A" was originally wanted. An arrow () exits from code +which calls template::set_file (directly or through +ad_return_template). All scripts and the template are +executed in the same scope, i.e., they share +variables.

Furthermore either of the final files can be omitted if it is +not needed, giving three basic possibilities.

+ + + + + + + +
a)codetemplate
 
b)(no code)template
 
c)code(no template)

It is an error to omit both parts; this is a special case +intended to speed up debugging.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/data.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/data.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/data.adp 17 Sep 2014 19:06:39 -0000 1.1.2.1 @@ -0,0 +1,67 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Data Sources} +Templating System User Guide: Data Sources + + + +

Implementing Data Sources

Templating System : Developer Guide : User Guide +

Data sources are implemented in a Tcl script using regular Tcl +variables, lists and arrays. The templating system includes a set +of procedures to simplify the construction of data sources from +relational database queries.

The Structure of Data Sources

The templating system can manipulate four basic types of +structures as data sources:

+ + + + + + + + + +
onevalueA simple scalar, such as a user's first name or the total due +on a purchase order.
onelistA list of simple scalars.
onerowA one-row data table, with values in one or more columns.
multirowA multi-row, multi-column data table.

onevalue

+onevalue data sources are implemented simply by setting +a Tcl variable:

set name "Walter Cronkite"

The query procedure may be used to set a onevalue data +source based on a database query:

query name onevalue "select name from users where user_id = +123"

You can embed a onevalue data source in a template with +simple variable +substitution.

onerow

+onerow data sources are implemented as Tcl arrays:

set name(first_name) Walter
+set name(last_name) Cronkite

The query procedure +may be used as a convenient way to store the result of a one-row +database query into an array:

+query name onerow "
+  select 
+    first_name, last_name 
+  from 
+    users 
+  where  
+    user_id = 123"
+

You can embed references to column values of a onerow +data source in a template with simple variable substitution.

onelist

+onelist data sources are implemented by creating a Tcl +list:

+set names [list "Walter" "Fred" "Susy" "Frieda"]
+

The query procedure may be used to set a onelist data +source based on a one-column database query:

query name onevalue "select name from users"

You can iterate over a onelist data source in a +template with the list tag.

multirow

+multirow data sources are not represented by a single +Tcl data structure. As such the templating system includes a +special API for constructing and manipulating them.

+multirow create cars make model year
+multirow append cars "Toyota" "Camry" "1996"
+multirow append cars "Volvo" "960" "1995"
+

The query procedure +may be used as a convenient way to store the result of a multi-row, +multi-column database query into a multirow data +source:

+query name multirow "
+  select 
+    make, model, year
+  from 
+    cars"
+

You can iterate over a multirow data source in a +template with the multiple +tag.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/document.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/document.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/document.adp 17 Sep 2014 19:06:39 -0000 1.1.2.1 @@ -0,0 +1,55 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Documenting Data +Sources} +Templating System User Guide: Documenting Data +Sources + + + +

Documenting Data Sources

Templating System : Developer Guide : User Guide +

Effective coordination between the developer and designer is one +of the major challenges of any publishing team. The templating +system provides a set of simple documentation directives so that +developer comments on data sources can be extracted from Tcl +scripts and summarized for non-technical members of the publishing +team automatically.

To take advantage of this capability, the developer must +structure comments on a datasource in the following way:

+  # \@datasource cars multirow
+  # The cars owned by a user.
+  # \@column make The make of the car, i.e. Toyota
+  # \@column model The model of the car, i.e. Camry
+  # \@column year The year of manufacture
+   
+  # \@datasource name onevalue
+  # the name of the user
+  
+  # \@data_input add_entry form
+  # a form for adding entries to user's address book 
+  # \@input first_names text 
+  # entry subject's first and middle names
+  # \@input last_name text
+  # \@input title text form of address for entry subject
+  # \@input birthday date birthdate w/ "MONTH DD YYYY" format
+  # \@input gender radio
+  # either "m" for male or "f" for female
+    
+

A few formatting guidelines:

    +
  • all datasources (onevalues, onelists, multilists, multirows) +are documented with the datasource directive, their name, the type +of datasource, and then necessary comments:
  • # \@datasource name <type of +datasource> comments +
  • multirow datasources are followed with a series of column +directives, column names, and associated explanations:
  • # \@column namecomments +
  • forms are documented with the data_input directive, and are +also followed with a series of input directives with the name and +type of input widgets, and necessary comments:
  • +
    # \@data_input name form comments # +\@input name <type of form entry> +comments +
    +Possible form entry types include text (or textentry), date, +checkbox, radio, select, multiselect and textbox
    • +

Once the templates have been enabled, the designer can simply +visit the URL from which the page will be served, substituting +acs with the dat extension.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/form-datatypes.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/form-datatypes.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/form-datatypes.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,9 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Custom Data Types} +Templating System User Guide: Custom Data Types + + + +

Custom Data Types

Templating System : Developer Guide : User Guide +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/form-process.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/form-process.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/form-process.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,33 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Validating and Processing Form +Submissions} +Templating System User Guide: Validating and Processing Form +Submissions + + + +

Validating and Processing Form Submissions

+Important Note: The ad_form +function has been written to be a more consistent, easier way to +create and manage dynamic forms. Behind the scenes it uses the +templating system's form builder, but it hides much of its +complexity. You should definitely look at it and at the pages that +use it in the survey package.

The templating system provides a simple infrastructure for +validating form submissions. The typical life-cycle of a form is as +follows:

    +
  1. The user makes the initial request for a page containing a +form. The code associated with the page creates the form (with the +form create command) and populates it with elements.
  2. The developer may use the form is_request command to +encapsulate any special initialization (for example, setting a +primary key value for an Add form, or retrieving current +values for an Edit form).
  3. The formtemplate tag is used to enclose the form +template. This tag is responsible for generating the appropriate +HTML FORM tag in the final output. The +formtemplate tag also embeds a special hidden variable in +the form for the purpose of identifying incoming submissions.
  4. By default, the formtemplate tag sets the +ACTION attribute of the FORM tag to the +same URL as that of the form itself. The submission is +therefor processed within the framework of the same code that was +used to create the form.
    5. +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/form-templates.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/form-templates.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/form-templates.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,27 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Customizing Form +Templates} +Templating System User Guide: Customizing Form +Templates + + + +

Customizing Form Templates

Templating System : Developer Guide : User Guide +

The templating system allows the designer to have full control +over the layout of a dynamic form.

Starting with an autogenerated form template

In most cases, the simplest way for the designer to get started +is to edit the autogenerated form template. This template will have +all the necessary formwidget and formgroup +tags.

Using form metadata

The designer must take care that all form elements created by +the developer in the code file are also represented in the +associated template. Checking the template against the form +metadata is the best means to ensure that elements are not +omitted.

Viewing of form metadata is not implemented yet.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/form-widgets.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/form-widgets.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/form-widgets.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,17 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Custom Form Widgets} +Templating System User Guide: Custom Form Widgets + + + +

Custom Form Widgets

Templating System : Developer Guide : User Guide +

Form widgets are implemented as tcl procs that output the html +to generate the form element. The tcl proc must be in the +template::widget namespace. So the proc for the search widget is +called template::widget::search. The code that generates the built +in widgets is in packages/acs-templating/tcl/widget-procs.tcl.

If the data from the form widget needs to be formatted or +processed a tcl proc is created in the template::data::transform +namespace. For example, templatete::data::transform::search. This +takes the input from the user and processes it to be returned to +the tcl code handling the form.

+ Index: openacs-4/packages/acs-templating/www/doc/guide/forms.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/forms.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/forms.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,45 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Creating and Populating +Forms} +Templating System User Guide: Creating and Populating +Forms + + + +

Creating and Populating Forms

Templating System : Developer Guide : User Guide +

This document outlines the steps necessary to build a dynamic +form in Tcl code.

+Important Note: The ad_form +function has been written to be a more consistent, easier way to +create and manage dynamic forms. Behind the scenes it uses the +templating system's form builder, but it hides much of its +complexity. You should definitely look at it and at the pages that +use it in the survey package.

Create a form

Use the form create command to initialize a form:

+form create add_user
+

See the form API for optional +parameters to this command.

Add elements

Once the form is created, use the element create +command to add elements to it:

+element create add_user first_name -datatype text \ 
+                                   -label "First Name" \
+                                   -html { size 30 }
+

In auto-generated forms, elements appear in the order they were +created. See the element API for +optional parameters to this command.

Set values

Self-validating forms should check whether a request or +submission is currently being processed. If a request is being +processed, then form elements may need to be initialized with their +appropriate values.

+if { [template::form is_request add_user] } {
+
+  set db [ns_db gethandle]
+
+  set query "select ad_template_sample_users_seq.nextval from dual"
+  template::query user_id onevalue $query -db $db
+
+  ns_db releasehandle $db
+
+  template::element set_properties add_user user_id -value $user_id
+}
+

This may also be done using the value option to +element create. In this case the value is set separately +to avoid the additional database query during a submission.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/index.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/index.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,105 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Overview} +Templating System User Guide: Overview + + + +

Overview

Templating System : Developer Guide : User Guide +

This document provides a brief introduction to the design of the +templating system and the process of building dynamic pages with +the templating system.

Introduction

+The templating system solves a clear business need: providing a +system for efficient collaboration between designers and developers +on building a web site. Writing a dynamic web page requires writing +application logic that retrieves data from a database and HTML +markup that presents this data in a readable form for the user. In +practice on production sites, this requires collaboration between +designers sensitive to issues of usability and the user experience +and developers who are sensitive to programming and performance +requirements. Without a templating system, a single script +containing the application logic and presentation markup is often +authored by both a designer and a developer simultaneously. This is +inefficient, error-prone, and difficult to maintain, as multiple +people with different purposes in mind must change the same file. +To solve this problem, the ACS Templating System, separates the +responsibilities of writing the page into separate application +logic and presentation layers. +

How the Templating System Works

This separation is achieved through utilization of the +Model-View-Controller (MVC) pattern. The MVC pattern is a classic +design pattern that identifies clear roles for components in GUI +application with persistent data originally developed for +SmallTalk-80 by Steve Burbeck. The model +represents the object, its data, and methods for updating the data. +The view provides a user a UI to see and +manipulate the data in the model. The controller +provides the system necessary to connect the model and the view to +the user's requests. This diagram +summarizes how the process flow of the templating system using the +MVC framework. The filename dynamic-page is simply +an example.

The model in the templating system is the +representation in the database of the ACS Objects and their associated PL/SQL +package methods. The view is the ADP template that +formats the datasources retrieved through the controller into a +presentation for a user. The controller is the +combination of the Request +Processor and the application logic pages implemented as .tcl +scripts that prepare data sources for the templating system.

This framework permits a clear separation between the logic that +retrieves data from the database and the markup that prepares the +data for display. The designer can focus on presentation and +usability issues and need only write HTML markup. The developer can +focus on the programming necessary to retrieve the data for the +designer and does not need to write HTML markup. These tasks are +separated into separate files so that the two tasks do not +interfere with each other.

The design of the templating system makes it easier to include +reusable presentation components as included templates and master templates, as explained in "Composite Page". Moreover, the ACS Core pages +are templated which enables users of the ACS who want to customize +their look and feel to update a site-wide master or the individual +templates without touching the application logic. If a bug is fixed +in the application logic, the application logic script can be +replaced without affecting the template.

The rest of this document explains the steps necessary to write +a templated page.

Choose the data you wish to present

The first step in building a dynamic page is to decide, at least +to a first approximation, on the data you wish to present to the +user. For example, a site that allows users to manage their car +maintenance records might want to present the following data on the +user's home page:

    +
  • The user's name.
  • The user's city of residence.
  • A list of the user's cars, showing the year, make, and +model.
  • A list of messages or alerts related to the user's cars.
  • A list of local events or special offers from mechanics or +dealers.
    • +

Note that our definition of data encompasses +everything that is unique to a particular user's +experience. It does not include text or other layout +features that will appear the same for all users.

Each of the items in the above list constitutes a data +source which the system merges with a template to produce the +finished page. The publisher typically describes the data to +present on each page as part of the site specification.

Implement the Data Sources

Once the publishing team has described the data to present on a +page, the developer writes a Tcl script to implement the data sources. The Tcl script should +be located under the page root at the URL of the finished page. For +example, a dynamic page that will be located at +http://yoursite.com/cars.acs requires a Tcl script located +on the server at /web/yoursite/www/cars.tcl (or wherever +your pages happen to be located).

In addition to setting data sources, the Tcl script may perform +any other required tasks, such as checking permissions, performing +database transactions or sending email. It may also redirect to +another URL if necessary. The Tcl script may optionally use logic +to change which page is being delivered, specified by +ad_return_template <filename>. If no filename is +supplied, ad_return_template does nothing. If the page +as defined after the last call to ad_return_template differs from +what it was at the beginning of the page, its datasource +preparation script is run in the same scope, in fact +accumulating datasources. By default the templating system looks +for a file with the same name as the Tcl script, but for the +template with the extension .adp.

Document the Data Sources

The developer should include comments in the Tcl code +documenting each data source. A templating system specifies +recognizes special documentation +directives that allow the comments to be extracted from the +code and accessed by the designer or publisher for reference.

Write the Template

The final step is to write a +template specifying the layout of the page. Template files must +have the adp extension. By default the system looks for +the template at the same location as the associated Tcl script, +such as /web/yoursite/www/cars.adp.

The layout is mostly HTML, with a small number of additional +custom tags to control the presentation of dynamic data on the +page. In most cases, the initial draft of the template will be +written by the developer in the course of testing the Tcl script. +The designer may then enhance the layout as required.

docs\@openacs.org + Index: openacs-4/packages/acs-templating/www/doc/guide/master.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/master.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/master.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,109 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Using Master Templates} +Templating System User Guide: Using Master Templates + + + +

Using Master Templates

Templating System : Developer Guide : User Guide +

Master templates dramatically simplify the task of maintaining a +consistent look and feel across all the pages of a site (or section +of a site). This document gives a brief overview of how to +implement a master template.

Design a Content Frame

Most web pages are laid out with a central content area +where the actual unique content of the page is displayed. +Surrounding the content area is a frame with common +elements that are consistent from page to page:

+ + + + + +
LogoAd +Banner
Navigation/Context +Bar
Section
+Links		 +

 

 

+CONTENT
+AREA +

 

 

+
Footer

Most sites use an HTML table to delineate the content area +within the frame, allowing for the inclusion of a sidebar along +with a header and footer. Sites that opt for a simpler layout may +only have a header above and a footer below the content area.

The master template is typically highly dynamic. Menus, context +bars and other navigational controls must change depending on the +section of the site the user is browsing. A "Related Links" box +would have to reflect the specific contents of the page. The master +template may also be personalized for registered users to include +their name and access to restricted areas of the site. Special +formatting preferences may also be applied for registered +users.

Write the Master Template

A master template to implement the page layout shown above would +have this basic structure:

+<html><body><table width=100% cellspacing=0 cellpadding=0 border=0>
+
+<tr>
+  <td><!-- LOGO --></td>
+  <td colspan=2><!-- AD BANNER --></td>
+</tr>
+
+<tr><td colspan=3><!-- NAVIGATION/CONTEXT BAR --></td></tr>
+
+<tr>
+  <td><!-- SECTION LINKS --></td>
+  <td colspan=2>
+    <!-- CONTENT -->
+    <slave>
+  </td>
+</tr>
+
+<tr><td colspan=3><!-- FOOTER --></td></tr>
+
+</table></body></html>
+

The only special feature of this master template is the +slave tag, which marks the location of the content area. +Note that the content is inserted into the master template as a +single passage of HTML or plain text. The master template should +always frame the content area within a td tag when using a +table to specify the overall layout of the page. Page layouts that +do not rely on tables often use hr tags to demarcate the +content area from the header and footer.

Write the Page Template(s)

A page template must include a master tag to specify +that its output should be enclosed in a master template:

+<master src="/templates/master">
+
+<!--Begin layout of page content-->
+<h3>\@title\@</h3>
+<p>by \@name\@</p>
+<p><b>\@byline\@</b>: \@text</p>
+...
+

The master tag may be included anywhere in the body of +the page template, although usually the top of the file is the best +location for it.

Adding Dynamic Elements to the Master Template

The master template may be associated with its own Tcl script, +which may set data sources to support dynamic elements outside the +main content area. For example, you might wish to include the +user's name on every page to indicate that the site has been +personalized. The Tcl script associated with the master template +would include code like this:

+set user_name [your_procedure_to_get_the_current_user_name]
+

The template would have a section like this:

+<if \@user_name\@ nil>
+  <a href="/register.acs">Register Now!</a>
+</if>
+<else>
+  \@user_name\@ (<a href="/signout.acs">Sign Out</a>)
+</else>
+

Passing Property Values from the Page Template to Master +Template

As mentioned above, in many cases the dynamic elements of the +master template depend on whatever is appearing in the content area +for a particular request. The property tag may be used in +the page template to specify values that should be passed to the +master template:

+<master src="/templates/master">
+<property name="title">\@title\@</property>
+
+<!--Begin layout of page content-->
+...
+

In this case, the property tag establishes +title as a data source for the master template. Properties +are set as regular Tcl variables prior to executing the Tcl script +associated with the master template. This allows the page template +to pass an ID which the Tcl script associated with the master +template may use to query for additional information.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/search.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/search.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/search.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,59 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Search-and-Select +Forms} +Templating System User Guide: Search-and-Select +Forms + + + +

Implementing Search-and-Select Forms

Form designers are often confronted by the need to provide users +with a way to choose from hundreds or even thousands of potential +options, exceeding the practical capacity of a select list or set +of checkboxes or radio buttons. One common solution is to allow the +user to select from a search result:

    +

  1. The user is prompted to enter or choose some search criteria. +For example, travel sites typically begin the reservation process +by prompting the user to enter a city of origin and +destination.

  2. +

    The search may return any number of results. Depending on the +specific application, the system may require the user to make one +choice, or allow multiple selections. If the search returns no +results, the system returns the user to the search form to modify +the search criteria and search again.

    To continue the travel site example, if an exact match is found +for the cities entered by the user, the system immediately returns +a list of flights. If several possible matches are found, the +system prompts the user to choose a city before proceding. If no +matches are found, the sytem prompts the user to search again.

    +
    3. +

To illustrate how to implement this type of page flow using the +templating system, we will build the framework for a simple +user-management interface. Required actions for such an interface +might include editing basic user properties, changing user +permissions or adding users to roles or groups.

The simplest way to implement this page flow using the +templating system is to create a single page that conditionally +includes two different forms:

    +

  1. Say the administrator wishes to edit the name and screen name of +a user. The administrator requests a page, user-edit.acs. +The page looks for a query parameter named user_id to +specify which user to edit.

  2. Initially, user_id is not specified. In this case, the +page includes a user search form.

  3. The user enters part of a user name or screen name and submits +the form, which returns to the same URL with the query parameter +user_search. If this parameter is defined, the page +queries the database for potential matches.

  4. If one match is found, the page sets a user_id variable +and includes the actual user edit form.

  5. If multiple matches are found, the page includes a listing of +users. The name of each each user is linked back to the same page, +with the appropriate user_id. The page prompts the +administrator to choose one. A link is also provided with no +user_id so that the administrator may search again.

  6. If the administrator chooses a user, the page detects the +user_id and displays the edit form.

    7. +

A working implementation of this example is provided in the +files demo/user-edit.tcl and demo/user-edit.adp. +You must execute the demo data file (demo/demo.sql) for +the page to function.

Try the following scenarios:

    +
  1. Submit the search form without entering any search +criteria.
  2. Submit the search form with obscure criteria that does not +yield a match.(i.e. zzzzz).
  3. Submit the search form with criteria likely to produce multiple +results (i.e. e).
  4. Submit the search form with criteria likely to product a single +result (i.e. Sally).
    5. +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/skins.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/skins.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/skins.adp 17 Sep 2014 19:06:40 -0000 1.1.2.1 @@ -0,0 +1,12 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Presenting Data in Multiple +Styles and Formats} +Templating System User Guide: Presenting Data in Multiple +Styles and Formats + + + +

Presenting Data in Multiple Styles and Formats

Templating System : Developer Guide : User Guide +

(Discussion of how to do cobranding, syndication of data in XML, +etc.).

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/tcl.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/tcl.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/tcl.adp 17 Sep 2014 19:06:41 -0000 1.1.2.1 @@ -0,0 +1,17 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Embedding Code in +Templates} +Templating System User Guide: Embedding Code in +Templates + + + +

Embedding Code in Templates

Templating System : Developer Guide : User Guide +

There are various ways to use Tcl in ADPs like ASP or JSP.

You can use the <% ... %> and <%= +... %> tags just as in an ADP page handled by the +AOLserver. For examples, see the section "embedded tcl" on the +demonstration page.

Generally, avoid putting escaped Tcl code in adp files, or +generating HTML fragments in tcl procedures. It subverts the +separation of code and layout, one of the benefits of templating. +Embedded Tcl makes templates non-portable to ACS/Java.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/templates.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/templates.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/templates.adp 17 Sep 2014 19:06:41 -0000 1.1.2.1 @@ -0,0 +1,57 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Writing Templates} +Templating System User Guide: Writing Templates + + + +

Writing Templates

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. 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 document introduces the basic concepts underlying the use +of template tags in ACS 4.0.

Variable 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.

See Variable +Substitution.

Use of Components

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 +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.

Property Declarations

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.

Conditional Insertion

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.

Iteration

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:

    +

  1. First and last items may be formatted differently from items in +between.

  2. 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.

  3. Colors or patterns may alternate between items. For example, the +designer may want to have alternate between white and gray bands in +a table.

    4. +

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.

See multiple, +group, list.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/guide/wizard-procs-doc.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/wizard-procs-doc.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/wizard-procs-doc.adp 17 Sep 2014 19:06:41 -0000 1.1.2.1 @@ -0,0 +1,175 @@ + +{/doc/acs-templating {Templating}} {Using the Wizard} +Using the Wizard + + + +

Overview Of How To Make A Wizard

    +
  1. Create a wizard file (ex. wizard.tcl) that contains the +"template::wizard create" code. +
    +ex.
+       template::wizard create -action "wizard" -name my_wizard -params {
+          my_param1 my_param2
+       } -steps {
+          1 -label "Step 1" -url "step1"
+          2 -label "Step 2" -url "step2"        
+          3 -label "Step 3" -url "step3"
+       }
+    
+
      +
    • action - the url where the wizard will always submit, normally +its the same as your current wizard file. Has no effect for +subwizards.
    • name - use to distinguish between the different wizards, since +you can have 1 or more subwizard. name must be no spaces, +alpanumeric similar to normal tcl variable naming convention
    • params - are used to keep values that you would like to pass on +to the other steps
    • steps - are use to define what includes to use for each step of +the wizard
      • +
    +
  2. +

    Add the "template::wizard get_current_step" on wizard.tcl. Make +sure that you call any "template::wizard set_param" if needed +before calling get_current_step. get_current_step will redirect to +the wizard -action properly setting all -params value and its other +needed http state vars

    Note: the wizard will rewrite the url always. Only self +submitting forms are preserved. Once the form is finished +processing the wizard will take over and rewrite the url.

    +
  3. Create the wizard template file (ex. wizard.adp). This file +will include the file based current step of the wizard +
    +ex.
+       <include src="\@wizard:current_url\@">
+    
+
    +
  4. Create the individual steps, these are just normal tcl and/or +adp files. So make a step1.tcl, step1.adp, step2.tcl, step2.adp, +step3.tcl and step3.adp. Normally this files are self submitting +forms
  5. Add "template:wizard forward" on each step (eg. step1.tcl, +step2.tcl, step3.tcl) , usually the code where the step is +processed and successful.
  6. On each step add the wizard buttons on the .tcl files. Ex. +step1.tcl will include +
    +    template::wizard submit myform -buttons {back next}
+    
+
    +On the last step you may want to use the following on step3.tcl +
    +    template::wizard submit myform -buttons {back next}
+    
+
    +The following values are acceptable for the buttons: back, next and +finish. Back buttons are not rendered if the step is the first +step, like wise next buttons are not displayed if its the last +step. Finish can appear on any step and will finish the current +wizard even if not all steps are done.
    7. +

Tips And How To Use The Wizard

    +
  • +

    How do you display the steps in the wizard to serve as an +indicator?

    +On your adp file do the following: +
    +       <multiple name="wizard">
+          <if "\@wizard.id\@" eq "wizard:current_id">
+             \@wizard.label\@ - you are at this step <br>
+          </if>
+          <else>
+             \@wizard.label\@ <br>
+          </else>
+       </multiple>
+    
+
    +
  • +

    How do you set the value of a wizard param?

    Use "template::wizard set_param myparam_name" to set it. +Normally you place this in the steps of the wizard where the form +has been processed. A param is normally used when you want to reuse +a value across the steps.

    Note: if you are to use "template::wizard set_param" on a wizard +file ex. (wizard.tcl). Make sure to do it before "template::wizard +get_current_step". So when "template::wizard get_current_step" +redirects it will properly set the correct values of the param to +the new value.

    +
  • +

    How do you get the value of a wizard param?

    +For example you wizard was created this way: +
    +           template::wizard create -action "wizard" -name my_wizard -params {
+              my_param1 my_param2
+           } -steps {
+              1 -label "Step 1" -url "step1"
+              2 -label "Step 2" -url "step2"    
+              3 -label "Step 3" -url "step3"
+           }
+    
+
    +You can access my_param1 and/or my_param2 on any step1.tcl, +step2.tcl, or step3.tcl by using "ad_page_contract" or +"template::wizard get_param" +
    +ex.
+    ad_page_contract {
+       gets the wizard params
+    } {
+       my_param1
+       my_param2
+    }
+    
+
    +or +
    +    set my_param1 [template::wizard get_param my_param1]
+    set my_param2 [template::wizard get_param my_param2]
+    
+
    +Note: "template::wizard get_param" has the advantage of getting the +param value during the response time. What does this mean? It will +properly get the current value of the param which was set by +"template::wizard set_param", while ad_page_contract will not pick +that up since it will get what is the request http var value. This +is because "template::wizard get_param" gets the value from the tcl +var while ad_page_contract gets the value from the http var. So +while processing in tcl that value may change.
  • +

    How can you get the url of a wizard that is not your current +step?

    +You can use the following on your wizard.adp +
    +       <multiple name="wizard">
+             <a href="[template::wizard get_forward_url \@wizard.id\@">
+             \@wizard.label\@ <br>
+             </a>
+       </multiple>
+   
+
    +Note: that this is not a very wise thing to do especially if the +latter steps will depend on the inputs from the earlier steps. You +can however do checking on each step.
  • +

    How do you know if a step is already visited or not?

    There are situations where in you would like to build a wizard +when you can go back several steps and jump back to the step +furthest you have been.

    On your wizard.adp you can do the following

    +       <multiple name="wizard">
+          <if "\@wizard.id\@" le "wizard:visited_step">
+             <a href="[template::wizard get_forward_url \@wizard.id\@">
+             \@wizard.label\@ <br>
+             </a>
+          </if>
+          <else>
+             \@wizard.label\@ <br>
+          </else>
+       </multiple>
+   
+
    +Note: that this is not a very wise thing to do especially if the +latter steps will depend on the inputs from the earlier steps. You +can however do checking on each step.
  • +

    Can I use a wizard as a step?

    Yes you can use another wizard a step of a wizard. This will act +as a subwizard.

    Note: That visited steps will loose its value when moving from +one subwizard to another subwizard in the same level. In order to +preserve this you must call "template::wizard +load_last_visited_step -key $yourkey" before "template::wizard +get_current_step", after "get_current_step" call "template::wizard +save_last_visited_step -key $yourkey"

    Also the wizard params name is present across the curent wizards +being used, so the developer has to be aware not to use the same +names with different purpose. For example on main wizard with have +a param called "name" for the user name. And on on sub wizard we +have the param again called "name" but used for the file name.

    +
    • +
+ Index: openacs-4/packages/acs-templating/www/doc/guide/wizards.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/guide/wizards.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/guide/wizards.adp 17 Sep 2014 19:06:41 -0000 1.1.2.1 @@ -0,0 +1,78 @@ + +{/doc/acs-templating {Templating}} {Templating System User Guide: Integrating Forms into a +Wizard} +Templating System User Guide: Integrating Forms into a +Wizard + + + +

Integrating Forms into a Wizard

This document outlines the steps necessary to build a dynamic +form wizard in Tcl code.

Updated documentation of +wizards

Create a wizard

Use the wizard create command to initialize a wizard, +declaring any wizard state variables in the -params +option:

+wizard create make_sandwich -params { sandwich_id }
+

See the wizard +API for optional parameters to this command.

Add steps

Once the wizard is created, use the wizard create +command to add steps to it:

+wizard add make_sandwich -label "Add the lettuce" -url "add-lettuce"
+

In auto-generated wizards, the wizard steps appear in the order +they were created. See the wizard +API for optional parameters to this command. Alternatively, +wizard steps can be created in the wizard create statement +with the -steps option:

+wizard create make_sandwich -action "eat-sandwich.acs?sandwich_id=$sandwich_id" -params { 
+  sandwich_id 
+} -steps { 
+  1 -label "Add Meat"    -url "add-meat" -repeat
+  2 -label "Add Lettuce" -url "add-lettuce"
+  3 -label "Add Cheese"  -url "add-cheese" -repeat
+}
+

Setting wizard state variables

Most likely, a wizard will store one or more state variables +using the -params option in the wizard create +statement. At any point in the wizard process, a state variable's +value can be updated using the wizard set_param +command.

+# check to see if a sandwich_id has been passed in by the wizard
+request set_param sandwich_id -datatype integer -optional
+
+# if not, then set the sandwich_id
+if { [template::util::is_nil sandwich_id] } {
+
+  set db [ns_db gethandle]
+  query sandwich_id onevalue "select sandwich_id_seq.nextval from dual" -db $db
+  ns_db releasehandle $db
+
+  wizard set_param sandwich_id $sandwich_id
+}
+

Integrating forms into the wizard

+Integrating forms into the wizard involves augmenting the standard +ATS form by: +
    +
  • Adding wizard submit buttons to the form in place of the +standard form submit button: +

    In the .tcl file:

    +if { [wizard exists] } {
+  wizard submit form_name -buttons { 
+    { previous "Back" } repeat { next "Continue" } { finish Save } 
+  }
+} else {
+  element create form_name submit -datatype keyword -widget submit
+}
+

    In the .adp file:

    +<formtemplate id=\@form_name\@ style=wizard>
+
    +
  • Advancing the wizard with the wizard forward command. +The page the wizard forwards to depends on which wizard submit +button was pressed (next, repeat, previous, finish): +
    +if { [wizard exists] } {
+  # go to the next wizard step
+  wizard forward
+} else {
+  template::forward "http://cms.arsdigita.com"
+}
+
    +
    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/formerror.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/formerror.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/formerror.adp 17 Sep 2014 19:06:41 -0000 1.1.2.1 @@ -0,0 +1,64 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: formerror} +Templating System Tag Reference: formerror + + + +

formerror

Templating System : Designer Guide : Tag Reference : formerror +

Summary

The formerror tag is used to specify the presentation +of a form validation error.

Usage

+  <formtemplate id="add_user">
+  <table>
+  <tr>
+    <td>First Name</td>
+    <td>
+      <formwidget id="first_name">
+      <formerror id="first_name" type="no_special_characters">
+      The first name may not not contain special characters such as 
+      \@, $, !, %, & or #.
+      </formerror>
+    </td>
+  </tr>
+  </table><br>
+  <input type=submit value="Submit">
+  </formtemplate>
+

Another example:

+  <formtemplate id="add_user">
+  <table>
+  <tr>
+    <td>First Name</td>
+    <td>
+      <formwidget id="first_name">
+    </td>
+  </tr>
+  <formerror id="first_name">
+  <tr>
+    <td colspan="2"><font color="red">\@formerror.first_name\@</font></td>
+  </tr>
+  </formerror>
+  </table><br>
+  <input type=submit value="Submit">
+  </formtemplate>
+

This adds another table row which contains the error message for +that widget in red color. If there is no error then the table row +will not be added.

Notes

    +

  • The contents of the formerror tag may appear on the +form when a submission is returned to the user for correction.

  • The contents of the tag may use the special variables +label and value to refer to the element label and +submitted value.

  • You can use the variable \@formerror.element_id\@ to refer to the +automatically generated error message within the formerror +tags.

  • The type attribute is optional and is used to +distinguish messages for specific types of validation errors. Each +element may have any number of error messages associated with it, +corresponding to each of the validation checks performed by the +developer in the script associated with template.

  • If the contents of the tag are empty +(<formerror></formerror>), the message specified by the +developer in the script are inserted when appropriate. This is +particularly useful for international sites, where locale-dependent +messages may be stored in the database.

  • If the type attribute is not specified and the +contents of the tag are empty, all appropriate messages are +inserted (separated by <,br> tags).

  • See the formwidget and +formgroup tags for more +information on writing the body of a dynamic form template.

    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/formgroup.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/formgroup.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/formgroup.adp 17 Sep 2014 19:06:41 -0000 1.1.2.1 @@ -0,0 +1,43 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: Formgroup} +Templating System Tag Reference: Formgroup + + + +

Formgroup

Templating System : Designer Guide : Tag Reference : Formgroup +

Summary

The formgroup tag is used to lay out a set of check +boxes or radio buttons in a dynamic form template. All the check +boxes or radio buttons in a group share the same name. A button +group must be created as an element in the Tcl script associated +with the template.

Usage

+  <formtemplate id="choose_services">
+    <table>
+      <formgroup id=services>
+         <tr><td>\@formgroup.widget\@</td><td>\@formgroup.label\@</td></tr>
+      </formgroup>
+    </table><br>
+  <input type=submit value="Submit">
+  </formtemplate>
+

Notes

    +

  • The formgroup tag contains a template for formatting +each check box or radio button in the group. The tag makes a +special multirow data source named formgroup available in +the body of the tag. The formgroup data source includes +two columns. The first is widget, containing an HTML +input tag for one of the buttons in the group. The second +is label, containing a corresponding label for the +button.

  • The formgroup tag may emulate either the multiple or grid tags in repeating the template +section within the tag. By default it emulates the multiple tag. If the cols +attribute is specified, the formgroup tag will emulate the +grid tag.

  • +

    HTML attributes, including JavaScript event handlers, may be +specified as attributes to the formgroup tag. The system +will include all such attributes in the input tags of each +radio button or check box in the group.

    +<formgroup id="services" onChange="validate();">
+
    +

  • See the formtemplate +and formwidget tags for more +information on writing the body of a dynamic form template.

    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/formtemplate.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/formtemplate.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/formtemplate.adp 17 Sep 2014 19:06:41 -0000 1.1.2.1 @@ -0,0 +1,49 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: Formtemplate} +Templating System Tag Reference: Formtemplate + + + +

Formtemplate

Templating System : Designer Guide : Tag Reference : Formtemplate +

Summary

The formtemplate tag is used to embed a dynamic form in +a template. The elements of the form must be created in the Tcl +script associated with the template.

Usage

+  <formtemplate id="add_user">
+  <table>
+  <tr>
+    <td>First Name</td><td><formwidget id="first_name"></td>
+  </tr>
+  <tr>
+    <td>Last Name</td><td><formwidget id="last_name"></td>
+  </tr>
+  </table><br>
+  <input type=submit value="Submit">
+  </formtemplate>
+

Notes

    +

  • The formtemplate tag takes the place of the +form tag in a static HTML form. Explicit form tags in the +template should not be used to enclose dynamic forms.

  • +

    If the body of the formtemplate is empty, the +templating system will generate a form automatically based on the +list of elements created in the Tcl script associated with the +template:

    +<formtemplate id="add_user" style="standard"></formtemplate>
+

    The style attribute is optional. It may be used to +select a style template from /ats/templates/forms for +determining the layout of the auto-generated form. The default +style is defined in the DefaultFormStyle parameter on the +acs-templating package, and is by default set to standard, +which is included in the distribution.

    +
  • +

    HTML attributes, including JavaScript event handlers, may be +specified as attributes to the formtemplate tag. The +system will include all such attributes in the form tag of +the rendered HTML form.

    +<formtemplate id="add_user" onSubmit="validate();">
+

    This will work for both autogenerated and explicitly formatted +forms.

    +

  • See the formwidget and +formgroup tags for more +information on writing the body of a dynamic form template.

    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/formwidget.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/formwidget.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/formwidget.adp 17 Sep 2014 19:06:42 -0000 1.1.2.1 @@ -0,0 +1,40 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: Formwidget} +Templating System Tag Reference: Formwidget + + + +

Formwidget

Templating System : Designer Guide : Tag Reference : Formwidget +

Summary

The formwidget tag is used to position a form element +in a dynamic form template. The element itself must be created in +the Tcl script associated with the template.

Usage

+  <formtemplate id="add_user">
+  <table>
+  <tr>
+    <td>First Name</td><td><formwidget id="first_name"></td>
+  </tr>
+  <tr>
+    <td>First Name</td><td><formwidget id="first_name"></td>
+  </tr>
+  </table><br>
+  <input type=submit value="Submit">
+  </formtemplate>
+

Notes

    +

  • The formwidget tag takes the place of input +and select tags in static HTML forms. The system +substitutes these tags with the appropriate HTML tags, complete +with their proper values, options and other attributes, while +rendering the template. Explicit form tags in the template may be +used in special circumstances, but should be avoided wherever +possible.

  • +

    HTML attributes, including JavaScript event handlers, may be +specified as attributes to the formwidget tag. The system +will include all such attributes in the input or +select tag of the rendered HTML form.

    +<formwidget id="cc_number" onChange="validate();">
+
    +

  • See the formtemplate +and formgroup tags for more +information on writing the body of a dynamic form template.

    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/grid.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/grid.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/grid.adp 17 Sep 2014 19:06:42 -0000 1.1.2.1 @@ -0,0 +1,73 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: Grid} +Templating System Tag Reference: Grid + + + +

Grid

Templating System : Designer Guide : Tag Reference : Grid +

Summary

The grid tag is used to output each row of a multirow +datasource as a cell of an n column grid.

Usage

+<!-- Begid grid layout, i.e. <table> -->
+<table>
+
+<grid name="datasource" cols="n">
+
+  <if \@datasource.col\@ eq 1>
+    <!-- Begin row, i.e. <tr> -->
+    <tr>
+  </if>
+
+  <!-- Cell layout, i.e. <td>...</td> -->
+  <td>
+
+    <!-- Cells may be unoccupied at the end. -->
+    <if \@datasource.rownum\@ le \@datasource:rowcount\@>
+      ...
+      \@datasource.variable\@
+      ...
+    </if>
+
+    <else>
+      <!-- Placeholder to retain cell formatting -->
+       
+    </else>
+
+  </td>
+
+  <if \@datasource.col\@ eq "n">
+    <!-- End row, i.e. </tr> -->
+    </tr>
+  </if>
+
+</grid>
+

Notes

    +
  • +

    Rows from the data source are output in column-first order. For +example, if a datsource has 10 datasources and the grid has 3 +columns, the rows from the datasource will appear in the following +order:

    + + + + + + + + + +
    159
    2610
    37 
    48 
    +
  • +

    The \@datasource.row\@ variable can be used to band grid +rows:

    +  <if \@datasource.col\@ eq 1 and \@datasource.row\@ odd>
+    <tr bgcolor=#eeeeee>
+  </if>
+
+  <if \@datasource.col\@ eq 1 and \@datasource.row\@ even>
+    <tr bgcolor=#ffffff>
+  </if>
+

    Note that this is different from the multiple tag, where the +\@datasource.rownum\@ is used for this effect.

    +
    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/group.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/group.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/group.adp 17 Sep 2014 19:06:42 -0000 1.1.2.1 @@ -0,0 +1,78 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: Group} +Templating System Tag Reference: Group + + + +

Group

Templating System : Designer Guide : Tag Reference : Group +

Summary

The group tag is used only within the body of a +multiple tag to provide additional +formatting control between subsets of a multirow data source. The +tag takes a column name from the enclosing multiple tag as its only +attribute. It repeats a template section as long as the value of +the column does not change from row to row.

The group tag also sets two additional values in your +multirow:

    +
  • +groupnum is the rownum within the innermost group tag, +starting from 1, 2, 3, etc.
  • +groupnum_last_p is a boolean saying whether this is +the last row inside the current group tag, before the value of +column changes. Note, however, that this +only works inside the inner-mostgroup if +you have multiple group tags nested within each +other.
    • +

Usage

+<table>
+
+<multiple name="shirts">
+
+  <!-- Start a new row if the style changes -->
+
+  <tr>
+    <td>
+      \@shirts.style\@
+    </td>
+    <td>
+
+  <!-- List colors for the same style in a single cell -->
+
+  <group column="style">
+    \@shirts.color\@
+
+    <!-- \@shirts.groupnum\@ will be the number of the color within the style -->
+
+    <if \@shirts.groupnum_last_p\@ false>, </if>
+    <else>, or </if>
+
+  </group>
+
+  <!-- End the row if the style is going to change on the next row
+
+    </td>
+  </tr>
+
+</multiple>
+
+</table>
+

[Note: Carsten added this feature during the Berlin Hackaton +2004-02-14]

The delimiter attribute will add a string after each +row except the last row in the group:

+  <group delimiter=" | ">
+  ...
+

This attribute will cause the rows within the group to appear to +be sepparated by vertical bars. This is much more convenient than +using the <groupnum_last_p> tags to check whether we +are on the last row.

Notes

    +

  • +Group tags may be nested to perform even more complex +formatting.

  • Be careful when nesting several group tags. The group tag works +very narrowly - it only looks at the column you provide it with and +so long as that column doesn't change, it keeps looping. E.g. if +you have 3 levels and the value of the outermost column changes but +the value of the middle column doesn't, the inner group tag won't +notice and will continue to loop. A workaround would be to create a +derived column, which contains e.g. "$f1,$f2", and use that as the +column for the inner group tag. (See also this +bug).

    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/if.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/if.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/if.adp 17 Sep 2014 19:06:42 -0000 1.1.2.1 @@ -0,0 +1,136 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: If} +Templating System Tag Reference: If + + + +

If

Templating System : Designer Guide : Tag Reference : If +

Summary

The if tag is used to output a template section only +when certain conditions are met.

Usage Examples

+<if \@x\@ eq 5>True</if>
+<if \@x\@ eq "Greta">True</if>
+
+<if \@x\@ ne 5>True</if>
+<if \@x\@ ne "Greta">True</if>
+
+<if \@x\@ lt 5>True</if>
+<if \@x\@ le 5>True</if>
+
+<if \@x\@ gt 5>True</if>
+<if \@x\@ ge 5>True</if>
+
+<if \@x\@ odd>True</if>
+<if \@x\@ even>True</if>
+
+<if \@x\@ between 3 6>True</if>
+<if \@x\@ not between 3 6>True</if>
+
+<if \@x\@ eq 5 and \@y\@ eq 2>True</if>
+<if \@x\@ ge 5 or \@y\@ le 2>True</if>
+
+<if \@s\@ nil>True</if>
+<if \@s\@ not nil>True</if>
+
+<if \@z\@ in "Greta" "Fred" "Sam">True</if>
+<if \@z\@ not in "Greta" "Fred" "Sam">True</if>
+

Expression Syntax

+The condition of the <if> tag is built from terms of the form +
+x0 [not] +opx1x2 ...
+The operator op determines the number operands +(x0, ... +x +n-1). +

The following operators are available:

    +
  • binary +
      +
    • +x0gt  +x1 +
    • +x0ge  +x1 +
    • +x0lt  +x1 +
    • +x0le  +x1 +
    • +x0eq  +x1 +
    • +x0ne  +x1 +
      • +
    +
  • n-ary +
    • +x0in  +x1x2x3 ...
    +
  • ternary +
    • +x0between  +x1x2 +
    +
  • unary +
      +
    • +x0nil +
    • +x0defined +
    • +x0odd +
    • +x0even +
    • +x0true +
    • +x0false +
      • +
    +
    • +

Any of these operators can be prefixed with +not to invert the outcome.

Notes

    +

  • Any legal variables that may be referenced in the template may +also be used in if statements. Words not surrounded with +the commerical at sign (\@) are interpreted literally.

  • +

    Phrases with spaces in them must be enclosed in quotes to be +grouped correctly:

    +  <if \@datasource.variable\@ eq "blue sky">
+    <td bgcolor=#0000ff>
+  </if>
+
    +
  • +

    The elseif tag may be used following an if +block to specify an alternate conditional template section.

    +  <if \@datasource.variable\@ eq "blue">
+    <td bgcolor=#0000ff>
+  </if>
+  <elseif \@datasource.variable\@ eq "red">
+    <td bgcolor=red>
+  </elseif>
+  <else>
+    <td bgcolor=#ffffff>
+  </else>
+
    +
  • +

    The else tag may be used following an if block +to specify an alternate template section when a condition is not +true:

    +  <if \@datasource.variable\@ eq "blue">
+    <td bgcolor=#0000ff>
+  </if>
+  <else>
+    <td bgcolor=#ffffff>
+  </else>
+
    +

  • Compound expressions can be created by combining terms with the +and and or keywords, as illustrated above. Any +number of statements may be connected in this fashion. There is no +way to group statements to change the order of evaluation.

  • When a variable is tested using the nil operator, it +will return true if the variable is undefined or if the value of +the variable is an empty string.

    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/include-optional.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/include-optional.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/include-optional.adp 17 Sep 2014 19:06:42 -0000 1.1.2.1 @@ -0,0 +1,35 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: include-optional} +Templating System Tag Reference: include-optional + + + +

Include

Templating System : Designer Guide : Tag Reference : include-optional +

Summary

The include-optional tag is used to include another +template in the current template, but make some other chunk +dependent on whether or not the included template returned +something.

This is useful if, say, you want to wrap the template with some +HTML, for example, a frame in a portal, but if there's nothing to +show, you don't want to show the frame either.

Usage

+<include-optional src="blog-months">
+  <tr>
+    <th bgcolor="\@header_background_color\@">
+      Archive
+    </th>
+  </tr>
+  <tr>
+    <td nowrap align="center">
+      <include-output>
+    </td>
+  </tr>
+  <tr>
+    <td height="16">
+      <table><tr><td></td></tr></table>
+    </td>
+  </tr>
+</include-optional>
+

Notes

  • The output of the included template will be put where the +<include-output> appears.
Tag added by: Lars Pinds (lars\@collaboraid.net)
+Documentation added from sources on Nov 2002, Roberto +Mello. + Index: openacs-4/packages/acs-templating/www/doc/tagref/include.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/include.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/include.adp 17 Sep 2014 19:06:42 -0000 1.1.2.1 @@ -0,0 +1,62 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: Include} +Templating System Tag Reference: Include + + + +

Include

Templating System : Designer Guide : Tag Reference : Include +

Summary

The include tag is used to include a dynamic +subtemplate into the current template. Subtemplates are evaluated +in the same fashion as any other dynamic template; the developer +may associate data sources and other properties to them.

Usage

+<include src="subtemplate" attribute="value" ...>
+
+or +
+<include src="/packages/packagename/www/lib/subtemplate" attribute="value" ...>
+

Notes

    +
  • Arguments may be passed to the subtemplate by specifying +additional attributes to the include tag. All attributes +except for src are assumed to be arguments and are set as +variables which the subtemplate may reference using the +var tag. To pass a dynamic variable to the subtemplate, +specify the variable name surrounded by at signs as the value: +
    +<include src="subtemplate" source_id="\@source_id\@" ...>
+
    +Note that passing an html string to a subtemplate via +\@var\@ will result in passing an html-escaped string. +To prevent this, use \@var;noquote\@ when passing html +to subtemplates. Alternatively the variable can by passed by name +(similar to call-by-reference) causing a variable alias to be +created in the scope of the subtemplate. This variant is necessary +for e.g. passing a Tcl array like a templating datasource. To pass +e.g. users by reference, use this notation: +
    +<include src="subtemplate" &persons="users" ...>
+
    +This is particularly useful for passing onerow and multirow data +sourced. Note that in this case, if the subtemplate modifies the +value this will affect the includer. When the datasource in the +included page has the same name (&users="users"), +you can use the shorthand &="users".
  • It is important to note that variables passed through +include become available to the .tcl and .adp files being +include'd, but it does not make them settable through +ad_page_contract. +

    So if you'd like to have a template that will return a fragment +of a page that you'd like to include in other pages, make sure its +.tcl component does not call ad_page_contract.

    If you'd like to include a full page (that is, one which calls +ad_page_contract) then instead of passing a parameter +through <include>, you could use rp_form_put +to add the variable to that page's form. For additional references, +see how message-chunk is used throughout the forums package.

    +
  • If the src attribute begins with a slash, the path is +assumed to be relative to the server root, the parent directory of +the tcl library. If not, the path is assumed to be relative to the +current template, not the URL of the page +request.
  • If the page layout is sensitive to additional whitespace +surrounding the subtemplate, then care must be taken that the +subtemplate does not contain any blank lines at the beginning or +end of the file.
    • +
+ Index: openacs-4/packages/acs-templating/www/doc/tagref/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/index.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/index.adp 17 Sep 2014 19:06:43 -0000 1.1.2.1 @@ -0,0 +1,46 @@ + +{/doc/acs-templating {Templating}} {Template Markup Tag Reference} +Template Markup Tag Reference + + + +

Template Markup Tag Reference

Templating System : Designer Guide : Tag Reference +

Overview

The publishing system implements a small number of special +markup tags that allow template authors to add dynamic features to +their work. The tags allow authors to accomplish four basic tasks +that are not possible with standard HTML:

    +
  • Embed a dynamic variable in a template (variables).
  • Repeat a template section for each object in a dynamic list of +objects (multiple, +grid).
  • Output different template sections depending on the value of +one or more dynamic variables (if).
  • Provide a mechanism for building complete pages from multiple +component templates (include).
    • +

Available Tags

Notes

    +

  • 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 +in the HTML source code of the delivered page.

  • +

    With normal usage, the use of dynamic tags tends to increase the +amount of whitespace in the final HTML as compared to the template. +This usually does not affect how browsers display the page. +However, if a page layout depends on the presence or absence of +whitespace between HTML tags for proper display, then special care +must be taken with dynamic tags to avoid adding whitespace.

    When placed on a line by themselves, tags that are containers +for template sections (grid, if, and +multiple) will cause newlines to be added to the page at +the beginning and end of the section. This can be avoided by +crowding the start and end tags like so:

    +<td><if %x% eq 5><img src="five.gif"></if>
+<else><img src="notfive.gif"></else></td>
+        
+

    Note that this should not be done unless necessary, since it +reduces the legibility of the template to others who need to edit +the template later.

    +
    • +
Christian +Brechbühler
+Last modified: $Id: index.adp,v 1.1.2.1 2014/09/17 19:06:43 gustafn Exp $ + Index: openacs-4/packages/acs-templating/www/doc/tagref/list.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/list.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/list.adp 17 Sep 2014 19:06:43 -0000 1.1.2.1 @@ -0,0 +1,28 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: List} +Templating System Tag Reference: List + + + +

List

Templating System : Designer Guide : Tag Reference : List +

Summary

The list tag is used to repeat a template section for +each item in a list data source.

Usage

+<list name="datasource">
+
+  <if \@datasource:rownum\@ ne \@datasource:rowcount\@>
+    \@datasource:item\@ :
+  </if>
+  <else>
+    <b>\@datasource:item\@</b>
+  </else>
+
+</list>
+

Notes

    +

  • The special variable datasource:rownum has the +same meaning as the special column +datasource.rownum in the body of a +multiple tag.

  • The special variable datasource:rowcount has the same +meaning in the list context as it does for multirow data +sources.

    • +
templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/master.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/master.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/master.adp 17 Sep 2014 19:06:43 -0000 1.1.2.1 @@ -0,0 +1,23 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: Master} +Templating System Tag Reference: Master + + + +

Master

Templating System : Designer Guide : Tag Reference : Master +

Summary

The master tag is used to specify the relative or +absolute URL of another template to serve as a frame for the +current template. The entire contents of the current template are +inserted into the master template at a position designated by the +slave tag in the master +template.

Usage

+<master src="master">
+
+<property name="title">My Home Page</property>
+
+<p>Welcome to my home page!</p>
+
+...
+

Note(s)

  • See property and slave for more information related to +master templates.

templating\@arsdigita.com + Index: openacs-4/packages/acs-templating/www/doc/tagref/multiple.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/multiple.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/tagref/multiple.adp 17 Sep 2014 19:06:43 -0000 1.1.2.1 @@ -0,0 +1,87 @@ + +{/doc/acs-templating {Templating}} {Templating System Tag Reference: Multiple} +Templating System Tag Reference: Multiple + + + +

Multiple

Templating System : Designer Guide : Tag Reference : Multiple +

Summary

The multiple tag is used to repeat a template section +for each row of a multirow data source. Column variables are reset +with each repetition to the values of the next row of the data +source.

Usage

+<!-- Begin multiple layout, i.e. <table> -->
+<table>
+
+<multiple name="users">
+
+  <!-- Row layout, i.e. <tr>...</tr> -->
+  <tr>
+
+    <td>
+     \@users.first_name\@
+    </td>
+
+    <td>
+      \@users.last_name\@
+    </td>
+
+    <td>
+      \@users.state\@
+    </td>
+
+  </tr>
+
+</multiple>
+
+<!-- End multiple layout, i.e. </table> -->
+</table>
+
Notes
    
+
  • The special variable datasource:rowcount may be used to
+check for no rows in a data source (or any other special condition
+related to the number of rows in the data source).
  • 
+
    The special column datasource.rownum is set implicitly
+for each repetition and can be used in conjunction with the
+if tag to do row banding:
    +  <multiple>
+
+  <if \@datasource.rownum\@ odd>
+    <tr bgcolor=#eeeeee>
+  </if>
+
+  <if \@datasource.rownum\@ even>
+    <tr bgcolor=#ffffff>
+  </if>
+
+  ...
+
    
+
  • 
+
    The maxrows attribute may be used to limit the number
+of rows that are output from the data source:
    +  <multiple maxrows="n">
+  ...
+
    This attribute will cause processing to stop after n
+rows have been output.
    
+
  • 
+
    The startrow attribute may be used to skip a number of
+rows at the beginning of the data source:
    +  <multiple startrow="n">
+  ...
+
    This attribute will cause processing of the data source to begin
+at row n + 1.
    
+
  • 
+
    [Note: Carsten added this feature during the Berlin Hackaton
+2004-02-14]
    The delimiter attribute will add a string after each
+row except the last row:
    +  <multiple delimiter=" | ">
+  ...
+
    This attribute will cause the rows to appear to be sepparated by
+vertical bars. This is much more convenient than using the
+<if> tags to check whether we are on the last
+row.
    
+
  • The startrow and maxrows attributes may be
+used together to output any range from the data source.
  • See the group tag for
+formatting subsets of a multirow data source. In the current
+implementation, the <multiple> tag does not
+nest.
    • 
+
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/tagref/noparse.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/noparse.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/tagref/noparse.adp	17 Sep 2014 19:06:43 -0000	1.1.2.1
@@ -0,0 +1,23 @@
+
+{/doc/acs-templating {Templating}} {Templating System Tag Reference: Noparse}
+Templating System Tag Reference: Noparse
+
+
+
+
Noparse
Summary
The noparse tag is used to protect template tags that
+should not be parsed. It is useful when templates are generated
+dynamically. For example, the templating system uses the
+noparse tag in the "style" templates used for
+auto-generated forms.
Usage
+<noparse>
+  <multiple name=cars>
+    \\@cars.make\\@
+    \\@cars.model\\@
+  </multiple>
+</noparse>
+
Note(s)
  • Normal variable references are interpreted, even within
+a noparse tag. This is useful for generating templates
+where the attributes of the output template (such as references to
+component templates in an include tag or to form elements
+in a formwidget tag) must be
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/tagref/property.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/property.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/tagref/property.adp	17 Sep 2014 19:06:44 -0000	1.1.2.1
@@ -0,0 +1,22 @@
+
+{/doc/acs-templating {Templating}} {Templating System Tag Reference: Property}
+Templating System Tag Reference: Property
+
+
+
+
Property
Templating System : Designer Guide : Tag Reference : Property
+
Summary
The property tag is used to set display attributes of
+the page. The contents of the tag may be plain text, static HTML,
+or a dynamic template that references local data sources.
+Properties are most commonly used to pass information to a master
+template, such as a title or logo.
Usage
+<master src="master">
+
+<property name="title">My Home Page</property>
+
+<p>Welcome to my home page!</p>
+
+...
+
Note(s)
  • See master and slave for more information about master
+templates.
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/tagref/slave.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/slave.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/tagref/slave.adp	17 Sep 2014 19:06:44 -0000	1.1.2.1
@@ -0,0 +1,21 @@
+
+{/doc/acs-templating {Templating}} {Templating System Tag Reference: Slave}
+Templating System Tag Reference: Slave
+
+
+
+
Slave
Templating System : Designer Guide : Tag Reference : Slave
+
Summary
The slave tag is used to mark the position in the
+master template where the body template should be inserted.
Usage
+<html>
+<head><title>\@title\@</title></head>
+<body>
+<h2>\@title\@</h2>
+<hr>
+<blockquote>
+  <slave>
+</blockquote>
+<hr>
+
Note(s)
  • See property and master for more information related to
+master templates.
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/tagref/switch.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/switch.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/tagref/switch.adp	17 Sep 2014 19:06:44 -0000	1.1.2.1
@@ -0,0 +1,64 @@
+
+{/doc/acs-templating {Templating}} {Templating System Tag Reference: Switch}
+Templating System Tag Reference: Switch
+
+
+
+
Switch
Templating System : Designer Guide : Tag Reference : Switch
+
Summary
The switch tag is used to output one of n-sections when
+the switch variable matches one of the n-case statements. A default
+section can also be output if none of the n-case statements matches
+the switch variable.
Usage Examples
+<switch \@x\@>
+    <case value="Fred">
+         Hello Fred.
+    </case>
+    <case value="Greta">
+         Hello Greta.
+    </case>
+    <case value="Sam">
+         Hello Sam
+    </case>
+    <default>
+         I don't recognize your name.
+    </default>
+</switch>
+
Tcl-equivalent flags have the same meaning as in the tcl-switch
+statement. Supported flags include exact, glob, and regexp.
+<switch flag=glob \@x\@>
+    <case value="F*">
+         Hello Fred.
+    </case>
+    <case value="G*">
+         Hello Greta.
+    </case>
+    <case value="H*">
+         Hello Sam
+    </case>
+    <default>
+         You are in the section for people whose names start with F, G, or H.
+    </default>
+</switch>
+
Case tags also have an alternative form for matching a list of
+items.
+<switch \@x\@>
+    <case in "Fred" "Greta" "Sam">
+         Your must be Fred Greta or Sam, but I'm not sure which one.
+    </case>
+    <default>
+         I don't recognize your name.
+    </default>
+</switch>
+
Notes
    
+
  • Any legal variables that may be referenced in the template may
+also be used in switch statements.
  • 
+
    Phrases with spaces in them must be enclosed in double quotes
+and curly braces to be matched correctly. Failure to quote words
+with spaces correctly results in an error.
    +  <case "{blue sky}">
+    <td bgcolor=#0000ff>
+  </case>
+
    
+
    • 
+
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/tagref/variable.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/variable.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/tagref/variable.adp	17 Sep 2014 19:06:45 -0000	1.1.2.1
@@ -0,0 +1,23 @@
+
+{/doc/acs-templating {Templating}} {Templating System Tag Reference: Variables}
+Templating System Tag Reference: Variables
+
+
+
+
Variables
Templating System : Designer Guide : Tag Reference : 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
+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 -->
+<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.
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/widgets/date.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/date.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/widgets/date.adp	17 Sep 2014 19:06:45 -0000	1.1.2.1
@@ -0,0 +1,180 @@
+
+{/doc/acs-templating {Templating}} {Templating System Widget Reference: Date}
+Templating System Widget Reference: Date
+
+
+
+
The Date Widget
Overview
The date widget provides a versatile HTML control for entering
+dates in a variety of formats. The widget operates in conjunction
+with various template::util::date functions in order
+to validate and manipulate the user's input. Please see the
+demo pages for some examples of
+the widget's behavior.
The Date Object
The widget's value is a Date object, defined in
+template::util::date. The date object stores 7 fields:
+the year, month, day, hours, minutes, seconds, and the format in
+which these values should be displayed. The function
+template::util::date::create can be used to
+instantiate a blank date:
+proc template::util::date::create {
+  {year {}} {month {}} {day {}} {hours {}} 
+  {minutes {}} {seconds {}} {format "YYYY/MM/DD"}
+} {
+  return [list $year $month $day $hours $minutes $seconds $format]
+}
+
The two functions
+template::util::date::get_property and
+template::util::date::set_property are used to get or
+set the fields of a Date object. The get_property
+function accepts the desired field and the Date object, and returns
+the value of the field:
+proc template::util::date::get_property { what date } {
+...
+}
+
The set_property function accepts the field, the
+Date object and the new value, and returns the modified Date
+object:
+proc template::util::date::set_property { what date value } {
+...
+}
+
The fields which can be accessed or changed are summarized
+below:

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
FieldGet ?Set ?MeaningSample Value
yearYesYesThe 4-digit year2000
monthYesYesThe month, January = 18
dayYesYesThe day of month21
hoursYesYesThe hour, in 24-hour format23
minutesYesYesThe minute59
secondsYesYesThe second59
formatYesYesThe format (see below for a detailed explanation)YYYY/MM/DD
long_month_nameYes The symbolic month nameJanuary
short_month_nameYes The abbreviated month nameJan
days_in_monthYes The number of days in the month stored in the Date object; will
+return an empty string if the month or the year are undefiend.
+Takes into account the leap years.29
short_yearYesYesThe 2-digit year. When mutating, 2000 is added to the year if
+it is less than 69; otherwise, 1900 is added to the year.99
short_hoursYesYesThe hour, in 12-hour format. When mutating, the hour is always
+assumed to be in the "a.m." range; the ampm field may
+be used to change this.3
ampmYesYesThe meridian indicator: either am or
+pm. Can be used in conjunction with the
+short_hour field in order to completely specify the
+hour.am
not_nullYes This field will be 1 if and only if at least one of the date
+fields (year, month, date, hours, minutes or seconds) is present in
+the Date object. Otherwise, this field will be 0.1
sql_dateYes The SQL code fragment representing the date stored in the Date
+object.to_date('2000/08/12 11:15:00', 'YYYY/MM/DD
+HH24:MI:SS')
clockYesYesThe value of the date in the same format as the value returned
+by the clock seconds function. The clock
+function appears to be locale-dependent and therefore unreliable;
+however, manipulating the clock value with clock scan
+is currently the only way to perform arithmetic operations on
+dates, such as adding a day, comparing two dates, etc.(An integer representing the number of elapsed seconds)
For example, the following code produces the tomorrow's date in
+SQL:
+
+# Create a blank date
+set today_date [template::util::date::create]
+
+# Get the tomorrow's date
+set clock_value [clock scan "1 day" -base [clock seconds]]
+set tomorrow_date [template::util::date::set_property \
+  clock $today_date $clock_value]
+
+# Get the SQL value
+set tomorrow_sql [template::util::date::get_property \
+  sql_date $tomorrow_date]
+
+
The Date Element
The widget is created with the usual template::element
+create statement, with the datatype and widget set to
+date. In addition, the element requires a
+-format switch, which specifies the format for the
+date, as follows:

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
OptionFormatMeaning
-format longYYYY/MM/DD HH24:MI:SSThe full widget including the date and the time
-format shortYYYY/MM/DDThe widget capable of entering the date only, without the
+time
-format timeHH24/MI/SSThe widget capable of entering the time only, without the
+date
-format americanMM/DD/YYThe widget representing the more familiar American date
-format expirationDD/YYAn expiration date, as it may appear on a credit card

+-formatcustom string
+Custom formatSee below
Any other value for the format flag is interpreted
+as a custom format string. The custom format string should consist
+of format specifiers separated by any of /\-.: or
+spaces. The valid format specifiers are as follows:

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Format SpecifierFieldDefault Widget
YYYYyearInput box, 4 characters
YYshort_yearInput box, 2 characters
MMmonthSelection list
MONmonthSelection list of abbreviated month names
MONTHmonthSelection list of full month names
DDdaySelection list
HH12short_hoursSelection list from 1 to 12
HH24hoursSelection list from 0 to 23
MIminutesSelection list from 0 to 60, skipping every 5 minutes
SSsecondsSelection list from 0 to 60, skipping every 5 seconds
AMampmSelection list of "A.M." and "P.M."
Any format specifier may be followed by a lowercase
+t, in order to force the widget to use an input box
+(instead of a selection list) for entering the specified date
+fragment.
The -format switch is required, but the date widget
+also supports the following optional switches:

+
+
+
+
+
+
+
+
SwitchMeaningExample

+-field_intervalinterval
+Specifies a custom interval for the given field, as a list of
+three values: the starting value, the ending value, and the
+step-minute_interval {0 59 5}
-helpCauses the date widget to display a description of each date
+fragment widget showing the purpose of the widget, such as "Year"
+or "24-Hour"-help
Examples of various Date widgets can be found on the demo pages.
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/widgets/index.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/index.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/widgets/index.adp	17 Sep 2014 19:06:45 -0000	1.1.2.1
@@ -0,0 +1,11 @@
+
+{/doc/acs-templating {Templating}} {Templating System Widget Reference}
+Templating System Widget Reference
+
+
+
+
Slave
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/widgets/input.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/input.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/widgets/input.adp	17 Sep 2014 19:06:45 -0000	1.1.2.1
@@ -0,0 +1,44 @@
+
+{/doc/acs-templating {Templating}} {Templating System Widget Reference: Input}
+Templating System Widget Reference: Input
+
+
+
+
The Input Widgets
Overview
These widgets provide a variety of HTML controls, all of which
+are based on <input type=...>. In particular,
+the hidden, text, radio and checkbox widgets are currently
+implemented; their use is demonstrated in the acs-templating demo.
The Hidden Widget
This is simply an <input type=hidden> widget,
+which is used for passing pre-set variables along with the
+form.
The Text Widget
This widget allows the user to enter one line of text. It is
+completely identical to the <input type=text>. The
+-html parameter can be used to set its properties
+(such as size, maxlength, etc.), as
+described in the general widgets reference. The value of this widget is the text
+string.
The Radio Group Widget
This widget actually represents a group of radio buttons, at
+most one of which can be selected at any given time. The widget has
+one required parameter,
+-option option_list, which specifies the
+radio buttons to display. The option_list is a list of
+label-value pairs. For example,
+template::element create test_form cost \
+ -label "Car Cost" -datatype number -widget radio \
+ -options { {Cheap 1000} {Medium 50000} {Expensive 999999} }
+

+will create a radio button group with 3 options: "Cheap", whose
+value is 1000, "Medium", whose value is 50000, and "Expensive",
+whose value is 999999. The value of the entire widget is either the
+empty string (if the user did not select any of the radio buttons),
+or a the value of the currently selected radio button. For
+instance, if the user selects "Medium" in the example above, the
+value of cost will be 50000.
+
The default form template renders the Radio Group widget as a
+column of radio buttons. Since the Radio Group can consist of many
+HTML controls, the usual formwidget tag cannot be used
+to position the widget; instead, the formgroup tag must be
+used.
The Checkbox Group Widget
This widget is identical in use to the Radio Group widget, but
+instead of radio buttons it generates a group of checkboxes, any
+number of which can be checked at any given time. The
+values (plural) property of the corresponding element
+contains a list of all the checked values; the value
+(singular) property contains the first element in the list.
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/widgets/select.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/select.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/widgets/select.adp	17 Sep 2014 19:06:45 -0000	1.1.2.1
@@ -0,0 +1,55 @@
+
+{/doc/acs-templating {Templating}} {Templating System Widget Reference: Select}
+Templating System Widget Reference: Select
+
+
+
+
The Input Widgets
Overview
These widgets provide the single-selection and
+multiple-selection HTML controls; their usage is demonstrated in
+the acs-templating demo.
The Select Widget
This widget creates a list of choices, only one of which may be
+selected at any given time, using the HTML
+<select> control. Similarly to the button group widgets, the Select widget has one
+required parameter, -option option_list,
+which specifies all the possible choices. The option_list
+is a list of label-value pairs. For example,
+template::element create pizza_form topping \
+ -label "Pizza Topping" -datatype keyword -widget select \
+ -options { 
+    {Pepperoni pepperoni} 
+    {Sausage sausage} 
+    {{Canadian Bacon} cbacon} 
+  }
+

+will create a widget with 3 choices: "Pepperoni", "Sausage" and
+"Canadian Bacon". By default, the widget looks like a drop-down
+"picklist", however, it can be forced to look like a scrollable
+vertical list of n elements by using the
+-html { size n }
+parameter.
+
The value of the Select widget is the value of the currently
+selected choice. If no choice is selected, the value will be the
+empty string. However, if the widget happens to look like a
+picklist, most Web browsers automatically select the first option
+on the list. This behavior may be changed by supplying an extra
+"null" option. For example, the options for the pizza topic
+selection widget shown above could be changed to
+template::element create pizza_form topping \
+ -label "Pizza Topping" -datatype keyword -widget select \
+ -options { 
+    {{No Topping} {}}
+    {Pepperoni pepperoni} 
+    {Sausage sausage} 
+    {{Canadian Bacon} cbacon} 
+  }
+
The Multiselect Widget
This widget is similar to the Select widget, but it allows
+multiple values to be selected. Because of this, the Multiselect
+widget cannot look like a picklist. By default, the widget looks
+like a scrollable list of items, which grows up to 8 items in size
+(in other words, up to 8 items will be shown without the need to
+scroll). This size can be overwritten with the
+-html { size n }
+parameter.
The values (plural) property of the corresponding
+element contains a list of all the selected choices; the
+value (singular) property contains the first selected
+choice.
templating\@arsdigita.com
+
Index: openacs-4/packages/acs-templating/www/doc/widgets/table.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/widgets/table.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-templating/www/doc/widgets/table.adp	17 Sep 2014 19:06:45 -0000	1.1.2.1
@@ -0,0 +1,11 @@
+
+{/doc/acs-templating {Templating}} {Templating System Widget Reference: Table}
+Templating System Widget Reference: Table
+
+
+
+
Table Widget
Overview
The table widget facilitates the creation of a dynamic table
+with controls for sorting on any number of columns. The table
+layout may be based on a standard sitewide style, or on a custom
+template.
templating\@arsdigita.com
+